{ "version": "https://jsonfeed.org/version/1", "title": "vixalien.io", "home_page_url": "http://vixalien.com/", "feed_url": "https://vixalien.com/feed/feed.json", "description": "Feed for my personal website!", "icon": "http://vixalien.com/favicon/maskable.png", "author": { "name": "Angelo Verlain", "url": "https://vixalien.com" }, "items": [ { "id": "setup-git", "content_html": "Setup Git - vixalien
Thu Mar 31 2022

Setup Git

How I set up Git on my systems with using opinionated defaults.



How to setup Git

\n

This is my default setup

\n

1. Install Git

\n

Git has a high chance of being already installed on some systems. First run git version to see if it is installed and up-to-date.

\n
brew install git # on macos\n\nyay -S git # arch (or use pacman)\nsudo apt install git # ubuntu\nsudo dnf install git # fedora\n\n# this guide is not really meant for windows but everything should work, go to https://git-scm.com/download/win to download git for windows\n
\n

2. Update Git settings

\n

Create a file called .gitconfig in your home directory. On Windows, it is C:\\Users\\username\\.gitconfig.

\n
# ~/.gitconfig\n# Tell Git who you are\n[user]\n    email = good@email.dne\n    name = Beatiful Name\n# It is a good idea to tell Git to remember your credentials so that you don't have to log in everytime especially if you use Personal Access Tokens as seen below.\n# Note: If you don't want Git to remember your credentials forever, use `cache` instead of `store` or run `git help -a | grep credential-` to view all available helpers.\n[credential]\n    helper = store\n# Allow you to view pretty outputs when you fo `git log`. To enable these aliases, add the following lines to your `~/.gitconfig` file (create one if it doesn't exist)\n# some are stolen from https://stackoverflow.com/questions/1057564/pretty-git-branch-graphs\n[alias]\n    lg1 = log --graph --abbrev-commit --decorate --format=format:'%C(bold blue)%h%C(reset) - %C(bold green)(%ar)%C(reset) %C(white)%s%C(reset) %C(dim white)- %an%C(reset)%C(bold yellow)%d%C(reset)' --all\n    lg2 = log --graph --abbrev-commit --decorate --format=format:'%C(bold blue)%h%C(reset) - %C(bold cyan)%aD%C(reset) %C(bold green)(%ar)%C(reset)%C(bold yellow)%d%C(reset)%n''          %C(white)%s%C(reset) %C(dim white)- %an%C(reset)' --all\n    lg = !"git lg1"\n    adog = log --all --decorate --oneline --graph\n    # silly amend the last commit using the same message, useful when you forgot to add something before committing.\n    silly = commit --amend -a --no-edit\n[filter "lfs"]\n    required = true\n    clean = git-lfs clean -- %f\n    smudge = git-lfs smudge -- %f\n    process = git-lfs filter-process\n# Set the default branch to main\n[init]\n    defaultBranch = main\n[color]\n    ui = true\n# Set editor to VS Code\n[core]\n      editor = code\n
\n

Github

\n

Git and Github are a pair. This is how I set them up.

\n

1. Logging in

\n

You will need to login to Github from Git to access private repositories or push to repos. To my knowledge, you can either use SSH (Secure Shell) or Personal Access Tokens to login to Github from Git. You can choose whatever you like but I personally like to use SSH.

\n

1. Using SSH

\n

SSH is a protocol for logging into a remote machine and for executing commands on a remote machine. You can use the protocol to sign in into Github.

\n
1. Check if SSH files are present
\n

FIrst check if you have the files ~/.ssh/id_rsa and ~/.ssh/id_rsa.pub.

\n
ls ~/.ssh/id_rsa{,.pub}\n
\n

If the 2 files are present, skip to step 3.

\n
2. Generate the SSH keys
\n
ssh-keygen -t rsa -C "good@email.dne"\n
\n
3. Copy the contents of the id_rsa.pub
\n
pbcopy < ~/.ssh/id_rsa.pub # on macOS\n\ncat ~/.ssh/id_rsa.pub # on *nix, copy by hand-erm-mouse\n
\n
4. Add your SSH to Github
\n

You will now need to add your SSH key to Github.

\n
    \n
  1. Go to your Github's Account Settings
  2. \n
  3. On the sidebar, Click on "SSH and GPG keys".
  4. \n
  5. Scroll and click on "New SSH Key".
  6. \n
  7. Add a descriptive label and paste the text you had copied from the previous command and save.
  8. \n
\n
5. Test SSH
\n

To test SSH, run the following command:

\n
ssh -T git@github.com\n
\n

If you see something like the following, it worked:

\n
Hi username! You've successfully authenticated, but Github does\nnot provide shell access.\n
\n

Also, don't mind it if you see a message that says the authenticity of 'github.com' can't be established. It's normal.

\n

Now clone a repo using SSH by running your clone commands in the form:

\n
git clone git@github.com:user/repo.git\n
\n

2. Using Personal Access Tokens

\n

You need to push a repo to Github to initiate the authentication flow using Personal Access Tokens. Clone one of your repos and try to push it to Github using git push. If you do, it will ask for your username and password. Do not enter your real password, instead, create a new Personal Access Token that will serve as your password.

\n
    \n
  1. Go to Github
  2. \n
  3. Go to Settings by clicking your account icon in the top right corner.
  4. \n
  5. On the sidebar on the left, scroll down and click on "Developer Settings"
  6. \n
  7. On the new sidebar that appears, click on Personal access tokens
  8. \n
  9. "Generate new token"
  10. \n
\n

Choose a name for your token. I recommend the format: COMPUTER_NAME OS VERSION "GIT". For example: HP Laptop Ubuntu 21.04 Git. It may help you remember which tokens are used for what.

\n

I recommed you check the workflow scope ONLY. This will automatically select repo too and this will allow you to do basically almost anything you want on Git (including pushing & running Workflows/Automations). If you don't know what workflows are, only select repo. If you feel compelled as those are not enough, create it with those scopes anyways as you can create other tokens anyways anytime.

\n

It is equally important to note that Personal Access Tokens are used only once and cannot be viewed ever again although you can delete them.

\n

2. Adding a GPG Key to your account.

\n

You can show a Verified Badge or a blue tick next to your commits by setting up a GPG Key and using it to sign your commits. Commits made through the Github web interface are automatically signed.

\n

1. Install gpg

\n
brew install gpg # on macos\n# it's usually preinstalled on linux\n# on windows go to https://www.gnupg.org/download/\n
\n

2. Generate a new GPG Key

\n
gpg --full-generate-key\n
\n

GPG will ask you for many details. You must follow the prompts and enter the data provided. However it is extremely important that you enter the same email as you use on Github otherwise your commits won't be verified.

\n

GPG will ask some questions and this is how I choose to answer them. The circled texts are my answers.

\n
\ngpg (GnuPG) 2.2.20; Copyright (C) 2020 Free Software Foundation, Inc.\nThis is free software: you are free to change and redistribute it.\nThere is NO WARRANTY, to the extent permitted by law.\n\nPlease select what kind of key you want:\n   (1) RSA and RSA (default)\n   (2) DSA and Elgamal\n   (3) DSA (sign only)\n   (4) RSA (sign only)\n  (14) Existing key from card\nYour selection? 1\nRSA keys may be between 1024 and 4096 bits long.\nWhat keysize do you want? (3072) 4096\nRequested keysize is 4096 bits\nPlease specify how long the key should be valid.\n         0 = key does not expire\n      <n>  = key expires in n days\n      <n>w = key expires in n weeks\n      <n>m = key expires in n months\n      <n>y = key expires in n years\nKey is valid for? (0) 3m\nKey expires at Thu 30 Jun 2022 00:20:24 CAT\nIs this correct? (y/N) y\n\nGnuPG needs to construct a user ID to identify your key.\n\nReal name: Beautiful Email\nEmail address: good@email.dne\nComment: The comment you provided\nYou selected this USER-ID:\n    \"Beautiful name (The comment you provided) <good@email.dne>\n\nChange (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? o\nWe need to generate a lot of random bytes. It is a good idea to perform\nsome other action (type on the keyboard, move the mouse, utilize the\ndisks) during the prime generation; this gives the random number\ngenerator a better chance to gain enough entropy.\nWe need to generate a lot of random bytes. It is a good idea to perform\nsome other action (type on the keyboard, move the mouse, utilize the\ndisks) during the prime generation; this gives the random number\ngenerator a better chance to gain enough entropy.\ngpg: key YOUR KEY WILL BE HERE marked as ultimately trusted\ndgpg: revocation certificate stored as '/home/USERNAME/.gnupg/openpgp-revocs.d/RANDOM40CHARACTERSIDKWHYUREADINGTHISLMAO.rev'\npublic and secret key created and signed.\n\npub   rsa4096 2022-03-31 [SC] [expires: 2022-06-29]\n      RANDOM40CHARACTERSIDKWHYUREADINGTHISLMAO\nuid                      \"Beautiful name (The comment you provided) <good@email.dne>\nsub   rsa4096 2022-03-31 [E] [expires: 2022-06-29]\n
\n\n

At this point you will be demanded to enter a password twice. Please remember it or save it somewhere (in a password manager, does paper still exist in the future?)

\n

3. Verify the GPG key

\n
gpg --list-secret-keys --keyid-format LONG\n
\n

It should return text in the following format. Take note of the [KEY_ID].

\n
\nsec   rsa4096/[KEY_ID] 2022-03-31 [SC] [expires: 2022-06-29]\n      A13CD138DCCB7314834CD603049EF1938BFB0ACD\nuid                 [ultimate] \"Beautiful name (The comment you provided) <good@email.dne>\nssb   rsa4096/795E8F10B7A9C97D 2022-03-31 [E] [expires: 2022-06-29]\n
\n\n

4. Export the key and add it to Github

\n

Run the following command using the [KEY_ID] from the previous command to export your newly-created GPG key.

\n
gpg --armor --export [KEY_ID]\n
\n

This will generate a large block of text. In the following format.

\n
-----BEGIN PGP PUBLIC KEY BLOCK-----\n[SCRAMBLE]\n-----END PGP PUBLIC KEY BLOCK-----\n
\n

Copy the whole text including the comments.

\n

To add the key to Github.

\n
    \n
  1. Open Github
  2. \n
  3. Go your settings
  4. \n
  5. On the sidebar, Click on "SSH and GPG keys".
  6. \n
  7. Scroll and click on "New GPG Key" in the "GPG" keys section. (Below the SSH section).
  8. \n
  9. Paste the text you had copied from the previous command and save.
  10. \n
\n

5. Configure Git to always sign commits

\n

Now that you have GPG set up with Git, run the following commands to tell git to always sign your commits with your GPG key.

\n
git config --global user.signingkey [KEY_ID]\ngit config --global commit.gpgsign true\n
\n

If you do not enable commit.gpgsign you can always sign each commit individually by running git commit -S.

\n

Now try and commit to one of your projects. And it should show a verified commit.

\n

Troubleshooting

\n

If you run into issues while on the last part and the response says the commit can't be verified, try running the following command.

\n
echo "test" | gpg --clearsign\n
\n

If it fails, set the GPG_TTY variable.

\n
export GPG_TTY=$(tty)\n
\n

Then try re-running the command and it should be successful.

\n

It is also a good idea to kill the GPG client so that it asks for the password the first time.

\n
gpgconf --kill all\ngpg-agent --daemon\n
\n

Sources

\n\n
", "url": "https://vixalien.com/post/setup-git", "title": "Setup Git", "summary": "How I set up Git on my systems with using opinionated defaults.", "date_modified": "2022-03-31T23:47:12.886Z", "author": { "name": "Angelo Verlain", "url": "https://vixalien.com" } }, { "id": "explosiv-blog", "content_html": "Building a blog with Explosiv - vixalien
Sun Dec 19 2021

Building a blog with Explosiv

Building a static lightweight and fast blog with Explosiv.



Earlier this year, I created Explosiv ↗, a lightweight & fast static site generator that allows pages to be built with JSX. This is a tutorial on how to build a functional blog with Explosiv.

\n

Terminology

\n

We'll first talk about how the blog will be built. You can directly jump to the programming part or directly view the source code of the final blog on Github.

\n

What's in this blog?

\n

The blog will be a simple one with room for improvement (I invite you to be creative.) It will simply render a homepage, an about page and a group of posts. That's it. We'll not be using any heavy styling or custom components library. Of course we'll use Explosiv to build the blog and we'll write the blog posts themselves in Markdown.

\n

Explosiv?

\n

Explosiv ↗ is a NodeJS framework that uses JSX to render pages. It transforms .jsx files into .html files. That is: you write code that uses components, run js etc and Explosiv convert them into native HTML ready to be displayed to your favorite web browser.

\n

JSX?

\n

JSX ↗ stands for XHTML in JSX and it allows you to write HTML inside JS files simplifying data binding. JSX was created by the React team and is famously used within React so if you come from React, Explosiv will be easy for you to understand because it uses that same loved JSX syntax. Here is an example of JSX syntax.

\n
// JSX syntax is coool!\nlet Site = (data) => {\n    return <div>Hello {data.name}!</div>\n}\n
\n
Why not use React instead? or NextJS? or Gatsby? - Rant\n\n

 

\n

Why not use React instead? or NextJS? or Gatsby?

\n

React is only a library. React is in the core of NextJS or Gatsby and they all use it to create their own opinionated way of rendering React pages into HTML pages.

\n

NextJS ↗ is a framework created by Vercel and it provides many features to build very complex web apps: API Routes, Internationalisation, Analytics, Typescript, Image Optimization. It's many features means you can use it to create any type of website, from TikTok to Twitch to others ↗. However this means that it's also pretty bloated for simple websites like blogs where you end up not using much of the features. And the site ends up containing many and many JS files you'll not use and takes some time to load.

\n

\n\t\t\t\t\"NextJS\n\t\t\t\t
NextJS waterfall - View Image ↗
\n\t\t\t

\n

As you can see in the above screenshot from https://www.joshwcomeau.com/blog/how-i-built-my-blog. NextJS served more than 120 requests weighing 6 MBs in 13 seconds. Hmm??

\n

Gatsby ↗ touts itself as a fast static site generator that also uses React. It is NOT fast ↗. It takes about 30 seconds to make a production build. Imagine what would happen if you customize your site. Plus there are also some features that I think are overkill like GraphQL integrations. I mean I get it, but I would like to install GraphQL as a plugin, not baked into my static site that won't use it

\n


\n\n\n

Markdown?

\n

Markdown is a lightweight language that will convert plain text to formatted text. It's the language we'll use to write our own blog posts. It is used by bloggers, software developers and documentation writers. All those README.md files on GitHub are Markdown!. You can view the simple syntax of Markdown here:

\n
# This is a heading\n\nThis is a paragraph wil _emphasized_ and **strongly emphasized** text. And this is [a link to Google](https://google.com)\n\n1. This is an ordered list\n2. Another list item\n3. - A nested unordered list\n   - Another list item.\n
\n

This blog post you are reading is written in markdown too! You can view the source code here ↗.

\n

Code

\n

Explosiv is a NodeJS framework. That means you'll need to have NodeJS installed first. NodeJS comes with a package manager called npm and we'll use it to install Explosiv.

\n

1. Install Explosiv

\n

The first step is creating a folder for your blog. I used explosiv-blog for mine. Open the folder in your favorite shell (or command prompt or command line interface). You'll first need to initialize the folder as a NodeJS project.

\n
npm init -y\n
\n

NPM will generate a package.json that will be used to identify your app and manage your dependencies. The next step is to install Explosiv.

\n
npm install explosiv\n
\n

You're now ready to start building with Explosiv.

\n

2. Create homepage and about page.

\n

Now go ahead and create a folder called pages at the root of your project. This folder will hold all Explosiv pages.

\n

Homepage

\n

Create a file called index.js for our homepage. index is a special name as it denotes that this file will be the first one that the user sees when they visit our site for the first time. Add some simple JSX to our index page to show a warm welcome message to visitors of the blog.

\n
// index.js\nlet Homepage = () => {\n    return <>\n        <Head>\n            <title>my blog</title>\n            <meta name="description" content="This is my own blog"/>\n        </Head>\n        <main>\n            <h1>Welcome to my blog</h1>\n            <p>This is my cool new blog built with Explosiv. <a href="/about">About Me</a></p>\n        </main>\n    </>\n};\n\nexport default Homepage;\n
\n

We can now see how our site will look in the browser. Switch to your shell and run the following command.

\n

Explosiv Development mode

\n
npx explosiv dev\n
\n

This will start Explosiv in Development Mode, build the app then serve it locally at http://localhost:3000. Visit the URL to view the homepage.

\n

\n\t\t\t\t\"Blog\n\t\t\t\t
Blog homepage - View Image ↗
\n\t\t\t

\n

About Page

\n

Create a file called about.js. This will be our about page and it will be accessible at /about on our website. Add some JSX for the about page as well.

\n
// about.js\nlet About = () => {\n    return <>\n        <Head>\n            <title>about my blog</title>\n            <meta name="description" content="About my blog"/>\n        </Head>\n        <main>\n            <h1>About my blog</h1>\n            <p>Hey there! Welcome to my new blog built with Explosiv. Here you can find all my blog posts. <a href="/">Go back to homepage</a></p>\n        </main>\n    </>\n};\n\nexport default About;\n
\n

Now go to http://localhost:3000/about to view the about page. Note that Explosiv automatically rebuilt the app because we started explosiv in development mode.

\n
\n

ProTip: Creating a page at pages/about.js is equivalent to creating one at pages/about/index.js.

\n
\n

3. Styling

\n

Now the page looks a little bit ugly doesn't it? We can add CSS styles to make our site look nicer. We'll create a folder called public/ and create a stylesheet at public/app.css. Files in the public/ folder will be publicly accessible so you can visit http://localhost:3000/app.css to view the stylesheet.

\n
/* public/app.css */\nbody {\n  max-width: 600px;\n  padding: 0 20px;\n  margin: 0 auto;\n  font-family: system-ui, -apple-system, "Segoe UI", "Roboto", "Ubuntu", "Cantarell", "Noto Sans", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"\n}\n
\n

Now to allow Explosiv to include the above CSS, create a document file at pages/_document.js to customize the overall behavior of the blog.

\n
// pages/_document.js\nlet Document = () => {\n    return (<html lang="en">\n        <head>\n            <meta charset="utf-8"/>\n            <meta name="viewport" content="width=device-width,initial-scale=1"/>\n            <link rel="stylesheet" href="/app.css"/>\n        </head>\n        <body>\n            <div class="root"></div>\n        </body>\n    </html>)\n}\n\nexport default Document;\n
\n

The _document.js file is a special one because it provides a wrapper to the whole site, hence it can be used to customize the site. Let's explain the components of this _document.js:

\n
    \n
  • <html lang="en"> specify the language of our site.
  • \n
  • <meta charset="utf-8"/> to specify the character set of our site to prevent incorrect renderings of our site's text.
  • \n
  • <meta name="viewport"> to correctly scale the site for mobile users.
  • \n
  • <link rel="stylesheet"> to allow web browsers to fetch our stylesheet.
  • \n
  • <div class="root"></div> where the main page's content will be rendered.
  • \n
\n

You can now refresh http://localhost:3000 in your browser to see the updated page.

\n

\n\t\t\t\t\"Looks\n\t\t\t\t
Looks better already - View Image ↗
\n\t\t\t

\n

Now you know how to add custom styles, the limit is the sky. You can start to style your app this way. You can even use PostCSS or Stylus to build stylesheets faster.

\n

4. Blog Posts

\n

Writing the first blog post

\n

Off to writing the real posts now. Create a blog post at blog/first-post.md:

\n
---\ntitle: My First Blog Post\ndescription: "The first blog post to be created on this site."\ncreated: 1639915508100\n---\n\nHello people, a warm welcome to you. This is the first blog post on this site.\n
\n
\n

Note: Notice the block at the beginning of the file that starts and ends with ---. This is called Front Matter and is used to describe the blog posts like who wrote it, the title, when was it written etc. Also, be sure to update the created field to show the real time you created it. View time in terms of milliseconds after the UNIX epoch.

\n
\n

Showing the blog posts on the homepage

\n

Now comes the part that requires us to be a little bit ingenious. We are going to show all the blog posts on the homepage and provide links to them.

\n

First of all, we'll be installing 2 other dependencies to allow us deal with Markdown files.

\n
npm install front-matter marked\n
\n
    \n
  • front- matter: Allows use to parse page's front matter.
  • \n
  • marked: Allows use to parse Markdown files into HTML.
  • \n
\n

We are going to write a script at src/posts.js that loads all blog posts then give us info about them.

\n
// src/posts.js\n\n// Import dependencies\nlet path = require("path");\nlet fs = require("fs");\nlet fm = require("front-matter");\n\n// This function resolves where files or folders are relative to the `cwd` or current working directory.\nlet resolve = (...link) => path.resolve(process.cwd(), ...link);\n\n// Where all our blog posts are stored\nlet blogsPath = resolve("blog");\n\nlet blogs = fs\n    // Get all blog posts in the `blogsPath` folder.\n    .readdirSync(blogsPath)\n    .map((blog) => {\n         // Get the slug. i.e `first-post` from `first-post.md`\n        let slug = blog.replace(/\\.md$/, "");\n        // And return an array of posts and their front matter\n        // Example: [ "first-post", { title: "My First Blog Post", created: 1639915508100, description: "..." } ]\n        return [\n            slug,\n            { slug, ...fm(fs.readFileSync(resolve(blogsPath, blog), "utf8")).attributes },\n        ]\n    })\n    // Sort the blog posts by date created\n    .sort(([_, a], [$, b]) => b.created - a.created);\n\n// Export the posts as an object\nmodule.exports = Object.fromEntries(blogs);\n
\n

We are then going to display all blog posts on the homepage. To do this, we'll create a component at components/posts.js that uses the post data to display a list of info about posts.

\n
// components/posts.js\n// Load the posts as an object.\nimport postsJSON from "../src/posts";\n\nlet PostsCard = ({ ...props }) => {\n    // Convert the posts object into an array.\n    let posts = Object.entries(postsJSON)\n\n    return (\n        <p>\n            <h2>Posts</h2>\n            <div className="posts">\n                 {/* Display the posts one by one */}\n                 {/* Display each post's title, date of creation and description with a link to read the post */}\n                {posts.map(([slug, { title, description, created }]) => (\n                    <p>\n                        <a href={"/post/" + slug}>{title} &rarr;</a><br/>\n                        <small>{new Date(created).toDateString()}</small><br/>\n                        <span>{description}</span>\n                    </p>\n                ))}\n            </div>\n        </p>\n    );\n};\n\nexport default PostsCard;\n
\n

We'll then modify pages/index.js to show blog posts using the newly created component on the homepage.

\n
// index.js\nimport PostsCard from "../components/posts.js";\n\nlet Homepage = () => {\n    return <>\n        <Head>\n            <title>my blog</title>\n            <meta name="description" content="This is my own blog"/>\n        </Head>\n        <main>\n            <h1>Welcome to my blog</h1>\n            <p>This is my cool new blog built with Explosiv. <a href="/about">About Me</a></p>\n            <PostsCard/>\n        </main>\n    </>\n};\n\nexport default Homepage;\n
\n

At this point you can visit http://localhost:3000 to view the site in a web browser. Notice the list of posts

\n

\n\t\t\t\t\"Blog\n\t\t\t\t
Blog Homepage with Posts - View Image ↗
\n\t\t\t

\n

Showing the blog posts on their URLs

\n

Yay!! Our blog can now show posts. But if you click on the link to read the blog post, you'll reach a 404 page. We are going to create a page that will render each blog post to allow readers to read it.

\n

Meet dynamic pages

\n

We would need to write each blog's page like /pages/post/first-blog.js and /pages/post/second-blog.js etc. However, there is a feature called Dynamic Pages that simplify the development of related pages. We will be creating one single dynamic page at /pages/post/[slug].js that will render each post according to the [slug] provided. For example, visiting /post/first-blog will render /pages/post/[slug].js with a slug that is equal to first-blog.

\n
\n

Note: You can change [slug] to any other name you like. For example [id] or [post]. However, it is important to enclose the slug in brackets ([]).

\n
\n
// pages/post/[slug].js\n\n// Import dependencies, will be used later\nimport { promises as fs } from 'fs'\nimport path from 'path'\nimport matter from 'front-matter'\nimport { marked } from 'marked'\n\n// The Post component will be used to render each post\nconst Post = ({ post }) => (\n    <>\n        {/* Add a HEAD that shows the title of the page and expose the description of the post */}\n        <Head>\n            <title>{post.attributes.title} - vixalien</title>\n            <meta name="description" content={post.attributes.description} />\n        </Head>\n        <main>\n            {/* Show a link to the homepage */}\n            <div style={{marginTop:"20px"}}><a href="/">Homepage</a><br/><br/></div>\n            <small>{new Date(post.attributes.created).toDateString()}</small>\n            <h1>{post.attributes.title}</h1>\n            <p>{post.attributes.description}</p>\n            <div>===</div>\n            <br/>\n            {/* Render the post's content as HTML in an `article` tag */}\n            <article html={post.content}/>\n        </main>\n    </>\n)\n\nexport default Post;\n
\n

getPaths and getProps

\n

However, the above content is not enough for a dynamic page to work. For it to work correctly, we need to export 2 other functions beside the default export which is the main page JSX.

\n

The first needed export is getPaths and it is used to determine the number of all acceptable paths (or slugs). For example, it can be used to allow /post/first-blog to be rendered and /post/unknown-post to return a 404 page (Not Found). In our case, it's pretty straightforward to know the range of acceptable slugs. We just read the blog folder and see which blog posts are there:

\n
// Append to the end of `pages/post/[slug].js`\nexport const getPaths = async () => {\n    // Read all files in the `blog` folder.\n    const files = await fs.readdir(path.resolve('blog'))\n    // Remove the training extensions like `.md` (remove the 3 last characters of filename)\n    return files.map((filename) => filename.slice(0, filename.length - 3))\n}\n
\n

Now that we know what posts are there, we'll use getProps to read info about the post themselves given the slug. The getProps function is provided with a slug and use it to get information that will be passed to default export of the function (as props.)

\n
// Append to the end of `pages/post/[slug].js`\nexport const getProps = async (slug) => {\n    // Read the file named `slug`+.md in the `blog` directory with the utf-8 format.\n    let post = await fs.readFile(path.join('blog', `${slug}.md`), 'utf-8')\n    // uses the `front-matter` package to get the post's attributes.\n    post = matter(post)\n\n    // parse the post's body to get the raw HTML content.\n    post.content = marked(post.body)\n    // Return an object that will be passed onto the default page export.\n    return { post }\n}\n
\n

Now visit http://localhost:3000/post/first-blog to read first-blog.

\n

\n\t\t\t\t\"First\n\t\t\t\t
First Blog - View Image ↗
\n\t\t\t

\n

Final Steps

\n

Now that you are done, here are a list of things you should do next.

\n
    \n
  • Visit Explosiv on Github for docs, stars etc.
  • \n
  • Host your site on Vercel
  • \n
  • Provide feedback in Github Issues
  • \n
  • View the source of this site, which is written with Explosiv as well.
  • \n
\n
", "url": "https://vixalien.com/post/explosiv-blog", "title": "Building a blog with Explosiv", "summary": "Building a static lightweight and fast blog with Explosiv.", "date_modified": "2021-12-19T12:05:08.100Z", "author": { "name": "Angelo Verlain", "url": "https://vixalien.com" } }, { "id": "rabbet", "content_html": "How Rabbet Works - vixalien
Fri Dec 17 2021

How Rabbet Works

A lightweight site that allow you to build pages from links.



Rabbet is a very small and minimal app that allows users to create pages on the Internet with a set of URLs.

\n

I will try my best to share how Rabbet works in this short write-up. You can try to browse the source to follow along the explanations.

\n

Useful links:

\n\n

Rabbet is a monorepo

\n

Rabbet is built as a monorepo. That is, it is one repository (folder) but it contain other packages inside of it. The monorepo doesn't use any repo manager like Lerna or Yarn workspaces as the packages are not tightly coupled. The different packages are for different uses:

\n
    \n
  • render: a simple library that consume pages as JSON and return rendered HTML ready to be used in pages or dash to preview pages.
  • \n
  • db: a library that allows other packages to access the database where the users and pages are stored.
  • \n
  • pages: the express app that serves the rabbet pages at [username].rabbet.me/[page-slug].
  • \n
  • dash: a NextJS app that renders the Rabbet dashboard ↗ that serves as a front end that allows users to sign in and create pages.
  • \n
\n

Render

\n

render was one of the hardest packages to create. The hardest part is that it has different templates so that a user can choose a template they choose.

\n

Templates

\n

TODO: Allow user to select template in Dashboard UI

\n

Templates reside in the /templates directory. The default template is called Lnks. Templates favorably use React and Stylus to render HTML and CSS respectively. Because the render package is meant to be run in the browser, Templates can't access the filesystem. So the template is split into 2 files:

\n

metadata.js

\n

This file is run at build time and is used to get all files necessary using require statements. For example, Lnks use metadata.js to load it's JSX file (the one that will be used to render the page into HTML.) And the CSS file that will be used to style the rendered page.

\n
const jsFn = require("./page.jsx").default;\nconst cssString = require('./style.css');\n\nmodule.exports = async () => {\n    return { cssString, jsFn };\n}\n
\n

page.js

\n

This file is used to provide info about the template itself. It exports a JSON object with the following properties and a render function.

\n
{\n    "label": "lnks",\n    "settings": [\n        {\n            "key": "show_rabbet",\n            "label": "Show Powered by Rabbet",\n            "description": "Show the text 'Powered by Rabbet' at the end of the page.",\n            "type": "boolean", // can be boolean, number, string\n            "default": true,\n        }\n    ],\n    render,\n};\n
\n

The settings property affect Settings related to the template itself.

\n

The render function is a function that is fed the Page JSON and a meta attribute (which is the data returned from metadata.json.) The render function returns an object with properties that will be converted into HTML.

\n
let render = (page, meta) => {\n  return {\n    title: "Sample page",\n    about: "A sample page",\n    scripts: [\n      { src: "https://uri", type: "module" },\n      { html: "console.log(\\"Hello\\")" },\n      "https://uri",\n      "console.log(\\"Hello\\")"\n    ],\n    links: [\n      { href: "https://uri", rel: "stylesheet" },\n      "https://uri"\n    ],\n    styles: [\n      { html: 'body { color: "red" }' },\n      'body { color: "red" } '\n    ],\n    html: "HTML"\n  }\n}\n
\n

The html attribute is what will be in the body of the rendered page. The reason for styles, links and scripts is that the template may or may not need some scripts. For example, Lnks only use Lite Youtube scripts and external CSSs when the page's hero is a YouTube Embed.

\n

DB

\n
\n

Note: All DB functions are expected to be promises.

\n
\n

This is the most trivial package of all. It provides an /init script that is called before any database operation (may be called multiple times.) It's main export is a file that provide a set of trivial operations such as:

\n

DB operations.

\n
    \n
  • get(COLLECTION, id): Get an item with given id from collection.
  • \n
  • set(COLLECTION, id, data, merge = false): Update data for an item with given id from collection and whether to merge the new data with already exisiting data.
  • \n
  • add(COLLECTION, data): Add an item with given data to collection. The id is inferred automatically.
  • \n
  • query(COLLECTION, ...queries): Perform a set of queries on given collection.
  • \n
  • deleteAll(COLLECTION, ...queries): Delete all records that match a set of queries on given collection.
  • \n
\n

A query is built with the exported where property. For example, to get all users who have the given username use:

\n
import db from "@rabbet/db";\n\ndb.get("users", db.where("username", "==", "exampleusername"));\n
\n

Account operations

\n
\n

In the future, all account operations will be moved to /account instead of the current default export.

\n
\n
    \n
  • getCurrentUser(): Get the logged in user or null.
  • \n
  • getRealUser({ uid }): Get the real user's info (from the database) based on the uid returned from login.
  • \n
  • onCurrentUserChange(callback): Calls the given callback when the current user changes (logged out, logged in, loaded, logged out remotely)
  • \n
\n
\n

Note: Firebase take a while to initialize so when yu call getCurrentUser for the first time it will always return null. Rabbet doesn't use getCurrentUser but instead listen to the onCurrentUserChange to get a real result when the user has changed.

\n
\n

Example:

\n
import db from "@rabbet/db";\n\nlet user = await dbgetCurrentUser();\n
\n

Optimized Account operations

\n

Optimized account operations are located at /account.

\n
    \n
  • login {}: Currently an object with { withGoogle } that launchs a login dialog.
  • \n
  • logout(): Logout from the current device.
  • \n
\n

Example:

\n
import account from "@rabbet/db/account";\n\nloginWithGoogleButton.addEventListener("click", account.login.withGoogle);\nlogoutButton.addEventListener("click", logout);\n
\n

Pages

\n

pages is a small Express app that resides at https://rabbet.me. It renders a page from the given url. You can always visit a test rabbet page ↗.

\n

Assuming the root URL is rabbet.me, the pages app routes using the following rules:

\n
    \n
  • [username].rabbet.me/[slug]: Return the page with given slug created by user with given username.
  • \n
  • rabbet.me/: Redirects to Rabbet dashboard.
  • \n
  • A 404 page with a link to the Rabbet dashboard when a resource isn't found.
  • \n
\n
\n

Note: Pages doesn't currently use the db package but use a custom implementation that access the firebase API using URLs instead of a native driver (library) because it was thought to be faster. TODO: fix this.

\n
\n

Dash

\n

This is the dashboard that appears to all visitors of the service. It allows users to log in and create accounts, create, modify and delete pages. It is a NextJS app.

\n

The package has the following directory structure:

\n
\n\n

dash\n ├─ components: Components used throughout the app.\n ├─ lib: Useful libraries and tools.\n │ ├─ constants: Holds app constants.\n ├─ pages: Contains JSX files for the project.\n │ ├─ account: Pages related to user accounts'\n │ ├─ pages: Pages related to linkpages created by users\n │ ├─ home: Homepage: the site which the users see when not logged in.\n ├─ public: Static files\n ├─ partials: Reused high-level components\n ├─ schemas: Validation schemas for different objects\n ├─ stores: Zustand stores for different objects like user, pages etc.\n ├─ stylus: Stylus for the site that will be transcribed into CSS

\n
\n\n
\n
\n\n

If you've read this much, you might as well create a PR for a template. Inspirations: Orcd ↗ Linkfire ↗ Dev.page ↗

\n
", "url": "https://vixalien.com/post/rabbet", "title": "How Rabbet Works", "summary": "A lightweight site that allow you to build pages from links.", "date_modified": "2021-12-17T18:57:10.259Z", "author": { "name": "Angelo Verlain", "url": "https://vixalien.com" } }, { "id": "git", "content_html": "Learn Git! - vixalien
Sun Aug 01 2021

Learn Git!

Learn to use Git, a popular Distributed Control System to effectively collaborate and manage your software projects.



So now you understand a certain programming language and coffee is your new best friend. But everywhere there is code, you see Git. They say a true developer must know Git and here you are, knowing nothing about Git, but longing to getting started.

\n

I have to admit, Git is as complex as it is popular. However, you don't need to know all the 160+ commands of Git to do daily operations. Here is a short but comprehensive tutorial that will teach you the most used features of this world-famous version control system.

\n

What is a Version Control System?

\n

A Version Control System (VCS) is a system that track and manages changes to files. A project with a VCS is usually called a repository or repo for short.

\n

A VCS allows you to have multiple versions of a project. To visualize the need for a VCS, imagine you are working on a new feature in a project, and a bug that needs to be fixed immediately is reported. With a VCS, you can easily create a new version of your repository, fix the bug, then return to the previous version when you are done fixing the bug. You can also see the different changes you've made in your repository over time and can easily rollback when a change is undesired or introduced a bug. If you also modify your files or lose them, you can restore your repository to the last saved snapshot.

\n

What is Git?

\n

Git is a version control system that manages a collection of files in a certain directory. Git is a Distributed Version Control System. This means Git does not rely on a central server to store all the versions of a project's files. Instead, every person "clones" a copy of a repository and get all the history and branches (more on that later) of the project. Although the original source code of a repository may be stored on a third-party hosting service like Github, any person can have their own copy of the project.

\n

Git was created by Linus Torvalds in 2005 for development of the Linux kernel, with other kernel developers contributing to its initial development.

\n

Installation

\n
\n

Note: You'll need to be able to work with the command line fluently before learning Git. Even though there are Git GUIs, Git itself is a command line application. If you don't understand the arts of the command line yet, you can check Tania's command line tutorial.

\n
\n

You can download Git for macOS, Windows, Linux or build it from source from the Official Git website.

\n

When you are finished installing, you can check if git is installed by running the following code in your Terminal (or Command Prompt for windows).

\n
git --version\n
\n

If you see a result like the following, you are good to go.

\n
git version 2.30.2.windows.1\n
\n

Configuring Git

\n

After you install Git, you will have to set some configurations. These include your name and email and are used to mark changes that you introduce in a repository. That way, people can see changes you made and contact you easi;y.

\n
git config --global user.name "Firstname Lastname"\ngit config --global user.email username@email.com\n
\n

The above commands tell Git your names and email. Remember to change Firstname Lastname and username@email.com to your own names and email respectively.

\n

You can type the following command to check the saved config:

\n
git config --list\n
\n

And you may get results similar to this:

\n
color.ui=auto\ncore.editor='C:\\Program Files\\Sublime Text 3\\subl.exe' -w\ncore.symlinks=true\ncore.eol=lf\nuser.email=username@email.com\nuser.name=Firstname Lastname\n
\n

Git workflow

\n

Any git repository consists of 3 "trees" maintained by Git:

\n
    \n
  • Working Directory: This is your folder with the actual files, the one you can see in File Explorer.
  • \n
  • Index: This is a staging area where Git put files that you are going to commit soon. (i.e. changes that are going to be marked as a new version.) This is because there are certain files that you may want to mark as finished and won't change, while there are others you are still working on and don't want to be released in this version.
  • \n
  • HEAD: This is a reference that points to the last commit you've made.
  • \n
\n

So you add files from the Working directory to the Index. As you work further, you can add more files to the Index or even remove (restore) files from the Index. When you are ready, you commit your changes. This will next generate a commit and a new HEAD that points to your last commit.

\n

Working with repositories

\n

In this tutorial, we will need a new blank directory to learn Git and follow along. You can create a new folder anywhere to start experimenting with Git. I created mine at D:\\project.

\n

Initializing a Git repository

\n

By Initializing a Git repository, you convert an unversioned project to Git or as in our case, create a new empty repository. (Yep, you can now call your project a repository!) You will need to run the rest of the commands in the root of the project. You can type cd to see where you are now and check if it is indeed where you are planning to create a new repository.

\n
git init\n
\n

After initializing your git repository, you should see a message like: "Initialized empty Git repository in C:/project/.git/" to confirm that a new repo has been created successfully. Note that Git create a hidden folder called .git to store version and history data.

\n

Tracking files

\n

You will now need to create two files at the root of your project folder: index.html and style.css. You can use your favorite text editor (I ❤ Sublime Text) to save them to the root of your repository.

\n

Checking the status of a repository

\n

You can check the status of your local repository by using the git status command. You will use this command a lot while working with Git repositories.

\n
git status\n
\n

Output:

\n
On branch main\n\nNo commits yet\n\nUntracked files:\n  (use "git add <file>..." to include in what will be committed)\n        index.html\n        style.css\n\nnothing added to commit but untracked files present (use "git add" to track)\n
\n
\n

Note: On some older versions of Git, the main branch may be called master by default, this is normal. To change the name of the master branch to main, run: git checkout master then git branch -M main

\n
\n

Staging files

\n

The output above tells us that Git knows there are new files in the Working Directory but they are not tracked (They are not part of our Git repo; Git is not tracking changes to them, yet). We have to stage the files using the git add command.

\n
git add .\n
\n

Adding/Staging the files put them to Git's Index.

\n
\n

The . (or *) tells git to add EVERYTHING to the repo.

\n

You can also add a single file to the index at a time by using the git add <filename> syntax. git add index.html would add index.html only.

\n

You could also add a range of files using the * (wildcard character). git add hello/* would add all files in the hello folder.

\n
\n

Committing changes

\n

Let's check the status again with git status.

\n
On branch main\n\nNo commits yet\n\nChanges to be committed:\n  (use "git rm --cached <file>..." to unstage)\n        new file:   index.html\n        new file:   style.css\n
\n

We are now ready to commit the files (i.e. mark the changes we made a version).

\n
git commit -m "Initial Commit"\n
\n

Output:

\n
[main (root-commit) 154dcd7] Initial Commit\n 2 files changed, 2 insertions(+)\n create mode 100644 index.html\n create mode 100644 style.css\n
\n

While committing, the option -m can be used to provide a commit message, in this case "Initial Commit". You are encouraged to always provide a descriptive commit message that show a gist of the changes you've made.

\n
\n

If you don't provide a commit message, Git will use the default editor, set in the installation process on Windows or otherwise Vim, which could be weird for users who don't know to use Vim because it shows a strange screen where you can no longer enter any commands. To quit Vim, press ESC and type :q! followed by ENTER. You can learn how to configure Git to use your favorite text editor.

\n
\n

Branches

\n

Branches are used to develop features isolated from each other. The main branch (or master, depending on the version of Git) is the "default" branch when you create a repository. Use other branches for development and merge them back to the main branch upon completion.

\n

Creating a new branch

\n

In this project, we will be creating a new branch to add javascript.\nYou use the git chekout -b <branch-name> syntax to add a new branch.

\n
git checkout -b javascript\n
\n
Switched to a new branch 'javascript'\n
\n

Listing all branches

\n

You can use the git branch command to list all branches in the current repository.

\n
git branch\n
\n
* javascript\n  main\n
\n

The current branch is highlighted in green and an asterisk is shown before it's name.

\n

We can starting working on code in our new branch. Create a file called script.js. We can the use git status to view the state of our repo.

\n
git status\n
\n
On branch javascript\nUntracked files:\n  (use "git add <file>..." to include in what will be committed)\n        script.js\n\nnothing added to commit but untracked files present (use "git add" to track)\n
\n

Notice that the output shows that we're on branch javascript and that script.js is untracked. We will need to add it to the \nIndex.

\n
git add .\n
\n

Then commit.

\n
git commit -m "Add script"\n
\n
[javascript 355fad9] Add script\n 1 file changed, 1 insertion(+)\n create mode 100644 script.js\n
\n

Reviewing and Merging

\n

When you are done implementing a feature in a branch, the only thing left is to merge it to the main branch. Merging is Git's way of taking a forked history (an independent line of that divergd from the current branch) and incorporating it the current branch. Merging allows you to "combine" different versions of code that diverged from a shared branch. We are going to merge code from the javascript branch back into the main branch.

\n

We'll need to go back to the main branch first.

\n
git checkout main\n
\n

git diff

\n

It is good practise to first review changes before merging or committing. You can use the git diff command (short for difference) to show changes between different revisions or paths. (You can use it to compare branches, commits and whatnots).

\n

If you provide only one argument, Git shows the changes in your working tree relative to the named reference. You can use HEAD to compare it to the latest commit, or a branch name to compare it to the tip of a different branch, which is what we'll do here.

\n
git diff javascript\n
\n
diff --git a/script.js b/script.js\nnew file mode 100644\nindex 0000000..d7ac302\n--- /dev/null\n+++ b/script.js\n@@ -0,0 +1 @@\n
\n

git merge

\n

After now reviewing the changes we are about to merge, it's time we merge the actual changes back into the main branch.

\n
git merge javascript\n
\n
Updating 154dcd7..355fad9\nFast-forward\n script.js | 1 +\n 1 file changed, 1 insertion(+)\n create mode 100644 script.js\n
\n

After the branch is merged successfully, we can now delete the javascript branch because it is no longer needed.

\n
git branch -d javascript\n
\n
\n

Git tries to auto-merge changes. Unfortunately, this is not always possible and results in conflicts. You are responsible to merge those conflicts manually by editing the files shown by git. After changing, you need to mark them as merged with git add <filename> before merging changes.

\n
\n

Logging

\n

You can type git log see the repository's history and confirm that the branch has been merged.

\n
commit 355fad97c2d442bb4a307385bfd6bac2198e825d (HEAD -> main)\nAuthor: Firstname Lastname <username@email.com>\nDate:   Sun Aug 1 15:35:31 2021 +0200\n\n    Add script\n\ncommit 154dcd7ce38589eb903346f6996e810401fa4910\nAuthor: Firstname Lastname <username@email.com>\nDate:   Sun Aug 1 15:07:37 2021 +0200\n\n    Initial Commit\n
\n

Because git feeds git log results to a pager, you may need to press q when the log is too long.

\n

You can add a lot of parameters to make the log look like what you want. Here are a few examples:

\n
    \n
  • To see only the commits of a certain author:\ngit log --author=alice
  • \n
  • To see a very compressed log where each commit is one line:\ngit log --pretty=oneline
  • \n
  • Or maybe you want to see an ASCII art tree of all the branches, decorated with the names of tags and branches:\ngit log --graph --oneline --decorate --all
  • \n
  • See only which files have changed:\ngit log --name-status
  • \n
\n

These are just a few of the possible parameters you can use. For more, see git log --help

\n

Tags

\n

When you are done and ready to mark a version of your code, you can add a git tag.

\n
git tag v1.0.0\n
\n

The End

\n

You are now mostly ready to contribute to projects while using Git to track your projects. Although you must note that this is only a basic tutorial of Git and you still have more to learn namely working with remotes. Git is a very complex software and has more than 160 commands but it's amazing how you don't have to know even a half to contribute to open source projects and track your project's progress. You'll know more git commands naturally as you become more experienced with Git and when the need for them comes.

\n

Resources

\n\n
", "url": "https://vixalien.com/post/git", "title": "Learn Git!", "summary": "Learn to use Git, a popular Distributed Control System to effectively collaborate and manage your software projects.", "date_modified": "2021-08-01T11:42:49.271Z", "author": { "name": "Angelo Verlain", "url": "https://vixalien.com" } }, { "id": "let-it-snow", "content_html": "Let it snow! - vixalien
Sun Jan 31 2021

Let it snow!

Building an optimized snowing weather with the Web Animations API and Promises.



\n

Easter egg: Run this page with #snow at the end

\n
\n

🌨⛄ Do you like snow? Does it snow in your region? Are we in December yet?

\n

We are going to create virtual snow using the chilly Web Animations API.

\n

A snowflake!

\n

First and foremost, let's create a snowflake! Our snowflake will be loaded as an .svg file provided by the beautiful Ionicons.

\n

Loading the snowflake

\n

You can store it as a local file then load it as SVG, or use it from Ionicon's library, but we will be storing it as a string.

\n
let svg_str = `<!-- snowflake svg text here -->`;\n
\n

Parsing the string into a DOM element

\n

Then we'll use DOMParser to parse the string into an actual DOM element.

\n
let snow = new DOMParser().parseFromString(svg_str, "text/xml").children[0];\n
\n
\n

Note: Because parseFromString returns a #document, we used .children[0] to get the <svg> element instead. (<svg> is equivalent to <html>.)

\n
\n

Setting the snowflake to float

\n

Our snowflake is fixed (it doesn't scroll like other elements) and initially, it is placed just above the screen.

\n
snow.style.position = "fixed";\nsnow.style.top = "-24px";\n
\n

Creating a new snowflake

\n

Because our page will have many snowflakes, we'll clone the snowflake we just created.

\n
let newSnow = () => {\n    let clonedSnow = snow.cloneNode(true);\n    // we pass true to clone the node deeply (that is, with all it's children).\n};\n
\n
\n

Note: from now on, our code will be in the newSnow function.

\n
\n

Next, we'll generate a random left position for that snowflake

\n
let left = Math.floor(document.body.offsetWidth * Math.random());\n// we use Math.floor to ensure left is an integer\nclonedSnow.style.left = left + "px";\n
\n

Then we'll just add it to the DOM

\n
document.body.append(clonedSnow);\n
\n

Animating the snowflake

\n

Here we'll just use Web Animations API to animate an element. To use the API, we run element.animate(keyframes, options). You can read more in the MDN Page.

\n

To make real snow effect, we will also generate a random speed (think the animation's duration)

\n
let time = Math.max(10 * Math.random(), 5) * 1000;\n// Math.max choose the largest argument it was given. By using it here, we restrict time to be larger than 5.\n
\n

We will animate the snow to change it's top CSS property gradually. At the end, the element will be placed just below the viewport, where you can't see it.

\n
let anim = clonedSnow.animate(\n    {\n        top: window.innerHeight + 24 + "px",\n    },\n    { duration: time, fill: "forwards" }\n);\n
\n

One last thing, we'll do Garbage Collection. When the animation ends, delete that snowflake as it is no longer useful.

\n
// garbage collection\nanim.onfinish = el => el.target.effect.target.remove()\n
\n

Now go ahead, in your console, run newSnow(). You'll see a snowflake falling slowly.

\n

Snowing!!!

\n

So far, we can only create snowflakes on demand by running newSnow() everytime we need it. What about we create a loop that create as many snowflakes as possible?

\n

The problem with native JS loops

\n

If you use for loops or while or whatever, it won't work. Why? It will create many snowflakes at a time. Your browser will be filled with snowflakes and unless you are on a supercomputer, your browser will crash, badly. This creates a need for a custom loop!

\n

Looping asynchronously

\n

Async Iterate

\n

Here's an implementation of an async loop.

\n
let asyncIterate = async (start, iterations, fn) => {\n    // initialize the iterator\n    let i = start;\n    let call = res => fn(res)\n        // waits for the function to resolves before calling the next iteration\n        .then(async result => {\n            if (i >= iterations) return result;\n            i++\n            return await call(i)\n        });\n    return await call(i);\n}\n
\n

It accepts 3 parameters. start is what the iterator is initialized as. iterations is pretty self-explanatory. it is the number of times the function will run. then fn is the function to execute.

\n

It is important to remember that this is an async loop. That means, it will run the function, then waits that it resolves. then execute the next iteration.

\n

wait

\n

Next is the wait function. This is a wrapper around setTimeout. It waits some time (in milliseconds), then execute a function. (It is available on the npm registry as async-wait-then).

\n
wait = time => new Promise(res => setTimeout(res, time))\n
\n

Here is a simple example using wait.

\n
wait(1000)\n    .then(() => console.log('This will be logged after one second!'));\n
\n

Using wait and asyncIterate to snow

\n

By combining wait and asyncIterate, we get a powerful function set that uses the Promises API.

\n

So, to create realistic snow (and prevent browser crashes) we'll have to wait before we create a snow element

\n
asyncIterate(0, 10, async () => {\n    await wait(1000)\n    newSnow()\n})\n
\n

This will make it rain 10 snowflakes, but with an interval of 1 seconds between each snowflake

\n

To make it look more realistic (and add some suspense), we will wait for a random amount of time instead of the static 1 second.

\n
asyncIterate(0, 10, async () => {\n    await wait(Math.max(3 * Math.random(), 1) * 300)\n    newSnow()\n})\n
\n

But then, this will only create 10 snowflakes. Let's make it rain forever.

\n
asyncIterate(0, Infinity, async () => {\n    await wait(Math.max(3 * Math.random(), 1) * 300)\n    newSnow()\n})\n
\n

The full code, complete with some optimizations is posted as Github Gist

\n
", "url": "https://vixalien.com/post/let-it-snow", "title": "Let it snow!", "summary": "Building an optimized snowing weather with the Web Animations API and Promises.", "date_modified": "2021-01-31T15:49:22.776Z", "author": { "name": "Angelo Verlain", "url": "https://vixalien.com" } }, { "id": "explosiv", "content_html": "How Explosiv Works - vixalien
Thu Jan 28 2021

How Explosiv Works

The most lightweight, yet fully featured static-site generator you'll see.



Explosiv npm ↗ Github ↗ is a static site generator for JSX content.

\n
\n

This article is about how Explosiv works, if you want to want to learn how to use Explosiv go to Explosiv's Github Page instead.

\n
\n

Why Explosiv was made.

\n

While I was creating this blog, I thought.

\n

About all the front-end options I had. Because, I was not going to write static HTML for a fully featured site! While I had already met stylus for all my CSS needs, I was still looking for an option to write my markup seamlessly.

\n

React

\n

TBH, I love React. It's syntax, it's community, it's everything really. Yet, React also put so much overhead on your site, like Build times, Babel, Webpack, hydrating or rendering etc. After some digging, I found out the foundation behind React was JSX, dubbed as XHTML within Javascript.

\n
// JSX syntax is coool!\nlet Site = (data) => {\n    return <div>Hello {data.name}!</div>\n}\n
\n

Well because JSX is tightly coupled with React, I kinda thought it would not work on it's own, but yet kartiknair made Dhow, which proved me otherwise.

\n

Dhow

\n

Dhow, is a static site generator, that uses JSX to render static HTML at build time, ready to be served as is. It is quick, very fast and still uses JSX, so migrating my app from React was a breeeeze. Until I encountered the severe limitations of Dhow.

\n

Dhow was very young. That means It just implemented JSX, nothing else. Many features were lacking. While creating this site, I cloned Dhow. I found myself adding many features as I wanted. I saw it was incredible. I decided to push it to My Github as Explosiv

\n

Explosiv

\n

Explosiv, being a clone of Dhow, inherits all it's current features. Here is a simple example.

\n

First, add explosiv to your site's dependencies.

\n
npm i explosiv\n
\n

And install explosiv globally, so that you can use the CLI wherever you are...

\n
npm i explosiv -g\n
\n

Or, to keep up with modern standards, although I personally like the first syntax more, use npx to always use the latest version of explosiv

\n
npx explosiv\n
\n

To make an Explosiv site, just create a folder and generate a pages/ directory. Add a simple index.js file to get started.

\n
// pages/index.js\nimport Explosiv from 'explosiv'\n\nexport default () => (\n    <main>\n        <h1>Hello there!</h1>\n        <p>\n            This is a super simple example of generating static files using Explosiv.\n            You can learn more at{' '}\n            <a href="https://github.com/vixalien/explosiv">here</a>\n        </p>\n    </main>\n)\n
\n

To build, and serve, the site use:

\n
explosiv build\nexplosiv serve\n
\n

Et voìla! A static site was generated in your /out directory. Magic right!

\n

How it works

\n

You can learn how JSX works by this article from the React team.

\n

You can read a very nice article by kartiknair, the creator of Dhow about converting JSX into HTML without React.

\n

TL;DR: We use a pragma function that generate real DOM elements using a minimal DOM implementation, min-document.

\n
// A general overview of how it works.\n// !! Not real code\nconst document = require('min-document');\n\nconst createElement = (tag, props, ...children) => {\n    const element = document.createElement(tag)\n\n    children.forEach((child) => {\n        element.appendChild(child)\n    })\n\n    return element\n}\n
\n

We transpile Javascript using ESBuild, a verrry fast, yet fully featured transpiler. We transpile the code in the pages directory from JSX into pure, native Javascript, while replacing all instances of JSX with our pragma function.

\n

The transpiled file will look like this

\n
// transpiled/index.js\nlet { createElement } = require('explosiv')\n\nexport default () => (\n    createElement('main', null, \n        createElement('h1', null, 'Hello there!'),\n        createElement('p', null, \n            'This is a super simple example of generating static files using Explosiv.',\n            'You can learn more', ' ',\n            createElement('a', {\n                href: "https://github.com/vixalien/explosiv"\n            }, 'here'\n        ),\n    )\n)\n
\n

At the end we render our DOM into static HTML by using document.toString() and piping the output into the relevant output directory.

\n

Impovements over Dhow

\n

Explosiv, is a personal project. It is not a competitor, or even an alternative to Dhow, yet all current improvements are listed for anyone interested. Many of these can also be implemented in Dhow if worth it.

\n
    \n
  • Provide an explosiv serve command that serve a static directory on a specified port (defaults to 3000).
  • \n
  • Head elements are added on top of document.head instead of the bottom (allowing overriding existing tags)
  • \n
  • Rewritten for build code to be independent and ease debugging
  • \n
  • Does not use polka but the more minimal connect.
  • \n
  • Use middleware deemed as useful like morgan which log all requests and compression which compress resources on HTTP.
  • \n
  • Fixed bugs on edge cases like rendering <> (aka Fragment tags) as root elements and rendering empty children.
  • \n
  • Added support for className HTML attribute.
  • \n
  • Fixed bug where self-closing (like <img src="/path/to.img">) elements doesn't render correctly.
  • \n
  • Use tabs instead of 4 spaces lol!
  • \n
  • And other many but subtle changes.
  • \n
\n
", "url": "https://vixalien.com/post/explosiv", "title": "How Explosiv Works", "summary": "The most lightweight, yet fully featured static-site generator you'll see.", "date_modified": "2021-01-28T17:23:43.290Z", "author": { "name": "Angelo Verlain", "url": "https://vixalien.com" } } ] }