DEV Community: Kartik Nair

Using JSX without react

Kartik Nair — Sat, 25 Jul 2020 17:28:02 +0000

I'm personally a big fan of JSX & love the way it allows me to split up & componentize my code. Even though JSX had been around before React, it wouldn't have been nearly as popular without React picking it up. However we can actually use JSX without React & it's not that difficult either.

The way React works is by configuring your bundler to convert JSX into calls to a createElement function. So for example:

const foo = (
    <div className="cool">
        <p>Hello there!</p>
    </div>
)

// Would become this:
React.createElement(
    'div',
    { className: 'cool' },
    React.createElement('p', null, 'Hello there!')
)

However most transpilers allow you to choose your own JSX pragma (function that will be in the place of React.createElement). For example if you were using Babel you could specify what function to use through a simple comment like this:

/** @jsx myJsxFunction */

const foo = (
    <div className="cool">
        <p>Hello there!</p>
    </div>
)

And now babel would pass those some parameters to myJsxFunction. Now all we need to do is create a function that takes these parameters & created real DOM nodes which we can add to our DOM. So let's get started. (If you need a code sandbox to play around you can use this static template using standalone babel)

DOM nodes are created using the document.createNode() function & it requires just a tagname so a good place to start would be with that:

export const createElement = (tag, props, ...children) => {
    const element = document.createElement(tag)
    return element
}

Now that we have a DOM node we have to actually add the attributes provided to us. These can be anything like class or style. So we'll just loop through all the provided attributes (using Object.entries and just set them on our DOM node:

export const createElement = (tag, props, ...children) => {
    const element = document.createElement(tag)

    Object.entries(props || {}).forEach(([name, value]) => {
        element.setAttribute(name, value.toString())
    })

    return element
}

This approach has one issue though. How do we handle events, for example if I have this JSX:

const SayHello = (
    <div>
        <button onClick={() => console.log("hello there!")}>Say Hello</button>
    </div>
)

Our function would set onClick as a normal attribute with the callback as actual text. Instead what we can do is check if our attribute starts with 'on' & is in the window scope. This will tell us if it's an event or not. For example onclick is in the window scope however onfoo is not. If it is then we can register an event listener on that node using the part of the name without the 'on'.

This is how it looks:

export const createElement = (tag, props, ...children) => {
  const element = document.createElement(tag)

  Object.entries(props || {}).forEach(([name, value]) => {
      if (name.startsWith('on') && name.toLowerCase() in window)
          element.addEventListener(name.toLowerCase().substr(2), value)
      else element.setAttribute(name, value.toString())
  })

  return element
}

Nice! Now all that's left to do is add all the children to the parent. However you can't append a string to a DOM node so in case the child is not also a node we can create a text node & append that instead:

export const createElement = (tag, props, ...children) => {
    const element = document.createElement(tag)

    Object.entries(props || {}).forEach(([name, value]) => {
        if (name.startsWith('on') && name.toLowerCase() in window)
            element.addEventListener(name.toLowerCase().substr(2), value)
        else element.setAttribute(name, value.toString())
    })

    children.forEach(child => {
        element.appendChild(
            child.nodeType === undefined
                ? document.createTextNode(child.toString())
                : child
        )
    })

    return element
}

However this quickly runs into issues with deeply nested elements & also elements that are created using array maps. So instead let's replace that part with aa recursive appendChild method:

const appendChild = (parent, child) => {
  if (Array.isArray(child))
    child.forEach(nestedChild => appendChild(parent, nestedChild));
  else
    parent.appendChild(child.nodeType ? child : document.createTextNode(child));
};

And now we can use this in place of our old method:

export const createElement = (tag, props, ...children) => {
    const element = document.createElement(tag)

    Object.entries(props || {}).forEach(([name, value]) => {
        if (name.startsWith('on') && name.toLowerCase() in window)
            element.addEventListener(name.toLowerCase().substr(2), value)
        else element.setAttribute(name, value.toString())
    })

    children.forEach(child => {
          appendChild(element, child);
      });

    return element
}

It works! Try it out. We can now render basic JSX to the DOM:

import { createElement } from "./Vanilla"

/** @jsx createElement */

const App = (
    <div>
        <p>My awesome app :)</p>
    </div>
)

document.getElementById("root").appendChild(App)

And you should see your JSX rendered out perfectly. There are a few more things we can add though, for example in React, elements are usually functions, implementing this will allow us to nest components & take full advantage of props, which are crucial featured of JSX.

Thankfully it's pretty simple to implement. All we have to do is check if the tagname is a function instead of a string. If it is we don't do any of the other stuff but rather just call the function. Here's how it looks:

export const createElement = (tag, props, ...children) => {
    if (typeof tag === "function") return tag(props, children)

    {...}
}

And now let's try that out:

import { createElement } from "./Vanilla"

/** @jsx createElement */

const SayHello = props => (
    <div>
        <h3>Hello {props ? props.name : "world"}</h3>
        <p>I hope you're having a good day</p>
    </div>
)

/* <Component /> === Component() */
document.getElementById("root").appendChild(<SayHello name="foo" />)

As you can see implementing that allowed us to use props as well! You can actually say we're done here but there's one more feature I want to implement & that's fragments. For those not familiar fragments are a way to have empty containers in JSX & they use empty tags. Example:

/** @jsx createElement */
/** @jsxFrag createFragment */

const UsingFragment = () => (
    <div>
        <p>This is regular paragraph</p>
        <>
            <p>This is a paragraph in a fragment</p>
        </>
    </div>
)

But for this to work we need a function that takes this fragment & instead of creating a DOM element for it just returns it's children. Here's how it looks:

const createFragment = (props, ...children) => {
  return children;
}

And that's it! It works out of the box because of our recursive appendChild method.

And that's it! We've done it. A super simple JSX to DOM function that let's us use the power of JSX without having to use react specifically. You can find the source code for it in this codesandbox.

I hope you found this post helpful & I also hope you find some cool ways to use the power of JSX. I actually learned about all of this while working on Dhow, which is a JSX-powered static-site generator for Node.js. It basically lets you write Next.js style code but converts it to static HTML with no hydration qualms. Check it out & let me know what you think. Peace!

SPA-like instant navigation in static sites

Kartik Nair — Sun, 21 Jun 2020 06:38:52 +0000

Single page applications have instant navigation. You click on a link and it changes views instantly. There might not be data & you might be shown a loading screen but still the navigation itself is instant and I've always missed this in pure static websites so, I thought I would try & implement something really simple to accomplish this nice boost in user experience.

The idea for the code is pretty simple. We need to get all the links on the page, check if they are internal, if they are we need to add a click event handler on them. This click handler will prevent the default action from happening & instead use the Browser History API to push a new entry in while also updating the DOM with the fresh content. It's only that last part which is a bit complex. So let's take a look at the Browser History API first.

It gives us a few functions that we can use to manipulate the browser history. They are:

back()
forward()
go()
pushState()
replaceState()

back() and forward() are pretty self-explanatory, they basically mimic the back and forward buttons in your browser. go() is the same except instead of back and forward you can specify exactly how far you want to travel from the current location (negative number for back, positive for forward; imagine a number line where 0 is the current location). pushState() let's us create a new entry in the history. This is what we're gonna use for our links as well, the reason we won't use replaceState() is because it won't create a new entry, all it will do is update the current entry. This would mean the back and forward buttons won't work as expected.

Alright so let's start implementing this in code. First we're gonna listen for the page load and then loop through all our links.

window.onload = function () {
  document.querySelectorAll("a").forEach((link) => {
    // do something with link
  });
};

Now with each link we have to check if they are internal or not. For this we can use the host attribute that every a tag has & compare it to the window.location.host, if they are the same the link is internal. We're also gonna add a data-internal or data-external attribute to the link as a way to separately style them later:

window.onload = function () {
  document.querySelectorAll("a").forEach((link) => {
    if (link.host === window.location.host) {
      link.setAttribute("data-internal", true);
    } else {
      link.setAttribute("data-external", true);
    }
  });
};

Now that we have this basic setup we need to actually intercept when an internal link is clicked and then use history.pushState() to add an entry to the browser history. But pushState() takes three arguments: state, title, & URL. In our case we'll just use our link's href as the route in our state object and also pass it as the title & URL. Here's how that looks:

window.onload = function () {
  document.querySelectorAll("a").forEach((link) => {
    if (link.host === window.location.host) {
      link.setAttribute("data-internal", true);

      link.addEventListener("click", (e) => {
        e.preventDefault();
        const destination = link.getAttribute("href");
        history.pushState({ route: destination }, destination, destination);
      });
    } else {
      link.setAttribute("data-external", true);
    }
  });
};

Quick note: Use link.getAttribute("href") instead of link.href to get the actual href provided to the DOM. For example an a tag like this: <a href="/foo">To foo</a> when asked directly for href would give http://localhost:5500/foo (or whatever domain it's currently hosted on) but getAttribute("href") would return "/foo".

Great now our links change the URL without a page refresh but our DOM isn't updating, the webpage looks exactly the same. So let's deal with that.

Updating the DOM

To update the DOM we actually need to get the new DOM. Since the page to which the link is pointing actually does exist, what we can do is use fetch() to get it's HTML content & then replace our current HTML with that. So let's make an async function called updateDOM to do this:

async function updateDom(path) {
  const res = await fetch(path);
  const data = await res.text();
  document.querySelector("html").innerHTML = data;
}

Pretty simple as you can see, when provided with a path like /about or /blog/awesome-post.html we'll use fetch to get a response & then use the .text() function to get it's plain text. Once we have that we just set our html elements innerHTML to be this text.

Now we need to call this function when our link is clicked:

window.onload = function () {
  document.querySelectorAll("a").forEach(link => {
    if (link.host === window.location.host) {
        link.setAttribute("data-internal", true);

        link.addEventListener("click", (e) => {
          e.preventDefault();
          const destination = link.getAttribute("href");
          history.pushState({ route: destination }, destination, destination);
          await updateDom(destination);
        });
      } else {
        link.setAttribute("data-external", true);
      }
  })
}

Great! Now you should've seen your link working. But this has a few issues. It'll only work on the first page. To fix this you need to import your script in all your html files & also we're gonna call updateLinks() as soon as we update the DOM. We also have to make sure that we scroll back to the top like a regular link otherwise we might confuse the user. So now our updateDom function is looking like this:

async function updateDom(path) {
  const res = await fetch(path);
  const data = await res.text();
  document.querySelector("html").innerHTML = data;

  updateLinks();
  window.scrollTo(0, 0);
}

Now all we're missing is the back and forward buttons. To deal with this we need to actually listen for a window event called onpopstate, this event is fired when the back or forward button is clicked & the important thing to note is that it's fired after the location is updated. Which means we can just update our DOM using window.location.pathname as our new path. So let's add that to our code:

window.onload = function () {
  {...}

  window.onpopstate = function () {
    updateDom(window.location.pathname);
  };
}

Great now everything works as expected. We've come a long way. But... we can still do some optimization. Now we're just updating the entire html even if a lot of it is the exact same. And while it won't have much difference for smaller websites, on a larger website this would be pretty jarring. Which is why we're gonna use a tiny (550byted minzipped) library called µdomdiff for this.

µdomdiff is just a single function and it takes 4 parameters (& a 5th optional one). Here's what it needs:

futureNodes = udomdiff(
  parent, // where changes happen
  [...currentNodes], // Array of current items/nodes
  [...futureNodes], // Array of future items/nodes (returned)
  get, // a callback to retrieve the node
  ****before // the (optional) anchored node to insertBefore
);

console.log("The new DOM is now:", futureNodes);

In our case the parent will be the <html> element, the currentNodes will be the html elements child nodes, the futureNodes will be our html which we received from fetching, & our callback can just be a simple return parameter function.

The only problem is that our fetched html is text & udomdiff expects it to be an array of nodes. So we're gonna use DOMParser and it's parseFromText() function to convert our text into DOM nodes. Then we're gonna use querySelector to get it's html element's child nodes. So let's start with that:

async function updateDom(path) {
  {...}

  const dataNodes = new DOMParser()
    .parseFromString(data, "text/html")
    .querySelector("html").childNodes;

  {...}
}

Now that we have that let's use udomdiff:

async function updateDom(path) {
  {...}

  const get = (o) => o; // Just returning the provided node back

  const parent = document.querySelector("html");
  const currentNodes = document.querySelector("html").childNodes;
  const dataNodes = new DOMParser()
    .parseFromString(data, "text/html")
    .querySelector("html").childNodes;

  udomdiff(
    parent, // where changes happen
    [...currentNodes], // Array of current items/nodes
    [...dataNodes], // Array of future items/nodes (returned)
    get // a callback to retrieve the node
  );

  {...}
}

And we're finally done! Smooth & instant navigation between your static pages with a tiny amount of JavaScript. If you're doing this a lot perhaps you should look into established libraries like TurboLinks but for simpler websites I haven't encountered any edge cases using this.

That's it for this post, hope you found it helpful. You can find the full source code in this GitHub Gist. Wanna say hi? I'm @kartikajitnair on twitter feel free to DM. That's all I have for now, stay safe!

Improve your web typography with a few solid tips

Kartik Nair — Mon, 25 May 2020 16:40:01 +0000

I try and make my websites look nice. I think the visual aspect of a website is very important especially to an average visitor. A regular person doesn't care about what architecture you're using to build your website, they care if it looks good and loads fast. And since typography is very important to a website's looks, today we'll be discussing a few ways you can immediately improve your web typography.

Typography is the base of all web design. Text is in my opinion the majority of a website's content (couldn't find any studies about this but I'm pretty sure this is true). So how do you make text look nice? There are a few things to consider:

Size (& the scaling in between different levels)
Spacing
Font choice

Size (& scaling)

The type scale is crucial so that a user knows what hierarchy you're trying to convey. You can find great ways to generate type scales online, I'm personally a fan of https://type-scale.com/ which let's you visually calculate a type scale for your website. Here's an example of a type scale (this particular one is taken from tailwind) implemented in CSS:

html,
body {
    font-size: 1rem;
}

h1 {
  font-size: 2.25rem;
}

h2 {
  font-size: 1.875rem;
}

h3 {
  font-size: 1.5rem;
}

h4 {
  font-size: 1.25rem;
}

h5 {
  font-size: 1.125rem;
}

h6 {
  font-size: 0.875rem;
}

This will immediately make a difference to your websites by clarifying how the hierarchy of content works. While this will look great on almost all devices we need to consider people on high resolution displays & small phones as well. For this I've started employing a few media queries to handle scaling all the type in my website responsively for them:

/* ↓ This one is for smaller phones ↓ */
@media (max-width: 350px) {
  html {
    font-size: 0.9rem;
  }
}

/* ↓ These are for high-res displays ↓ */
@media (min-width: 1900px) {
  html {
    font-size: 1.5rem;
  }
}

@media (min-width: 2500px) {
  html {
    font-size: 2rem;
  }
}

@media (min-width: 3000px) {
  html {
    font-size: 2.5rem;
  }
}

@media (min-width: 3400px) {
  html {
    font-size: 3rem;
  }
}

As you can see we're changing the size on the html tag which will affect what a rem means for everything else on your website, a great way to easily & responsively scale everything.

Spacing

Spacing is very very important, have a look at the 2 websites below, which one do you think is better designed?

Even though both of them use the same font and even the same type scale, the second one (in my opinion) objectively looks better. All it took was setting the correct line-height and making sure that the user doesn't have to track their eyes from one corner of the screen to the other. I usually accomplish this by wrapping all my text in a <main> tag and then size it accordingly:

html,
body {
    line-height: 1.5; // <- this will depend on your font
}

main {
  width: 50%;
  margin: 6% 25%;
}

@media (max-width: 768px) {
  main {
    width: 80%;
    margin: 15% 10%;
  }
}

@media (max-width: 350px) {
  main {
    width: 90%;
    margin: 15% 5%;
  }
}

Pretty simple in terms of CSS but has a huge impact on readability and pleasantness to look at.

Font choice

Choosing the right font for your website depends very heavily on the website and what it's purpose is. What matters most in font choice is that you make sure that it's legible. Since the purpose of text is to convey information (at least in the context of text heavy websites) using a font that isn't good at that wouldn't be very productive.

I leave it to you to make good choices in this area but if you're interested you can see some of my favourite open-source fonts below:

Parting words

That's all for this short article, I just wanted to share some easily implementable styling tips for web typography. I've compiled all of my basic typography styling into a simple starter CSS file (GitHub gist link) feel free to use it in any of your projects. Have a nice day & stay safe!

This article was originally published on my blog: https://kartikn.me/writing/improve-web-typography. Wanna say hi? Hit me up on twitter @kartikajitnair

Generating accessible color combinations for the web

Kartik Nair — Tue, 12 May 2020 10:57:31 +0000

Hey everyone! This is gonna be a pretty short post but I wanted to show you how easy it is to have the color scheme for your website be generated randomly on the client-side. It's a pretty interesting experience for the user but I don't think it makes sense for most websites, as most businesses (& even individuals) would want to stick to a more standard color scheme so they can stay consistent to their brand identity. However, if you find something cool to do with these accessible combos do share it with me I would love to see!

Before we get into it just wanted to let you know that this post was originally published on my blog, so feel free to check it out there.

Now let's get to the actual code. There are a few ways to do this, I recently found a tiny (less than 2kb) npm package called colors2k that offers this functionality but I also wanted to show you how it's possible to do this using only vanilla JS so let's start with the easy way first. For all these examples I'm using a regular HTML page being bundled using parcel and also pulling in a modified version of grotesk for basic styling.

Setup

For those not familiar this is how you create a new parcel project for the rest who want to skip directly to the combo generation click here:

mkdir accessible-combos
cd accessible-combos
npm init -y
npm i -D parcel-bundler

Let's create a src directory and add our HTML & JavaScript file. I'm using just regular HTML boilerplate, you've probably seen this a million times:

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>Accessible Combos</title>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <meta name="author" content="Kartik Nair" />
    <meta
      name="description"
      content="Generating accessible color combinations for the web"
    />
    <link href="./style.css" rel="stylesheet" />
  </head>
  <body>
    <main>
      <h1>Hello accessible combos</h1>
      <p>
        Lorem ipsum dolor sit amet consectetur adipisicing elit. Debitis minus
        sequi nesciunt, sapiente dignissimos ut, est magni, facilis repellat
        corrupti adipisci dicta ullam. Corrupti voluptates assumenda reiciendis
        quod placeat maxime.
      </p>
    </main>
    <script src="./index.js"></script>
  </body>
</html>

And then to your package.json you would add the following scripts:

"start": "parcel src/index.html",
"build": "parcel build src/index.html"

Generating the combos

Great we're all set up now we can actually install the package I told you about:

npm i colors2k

Now let's import it in our JS file and use it's contrast function:

import { getContrast } from "colors2k";

console.log(getContrast("#ffffff", "#000000");

As you can see that's pretty cool. But looping over the more than 16 million colors that hexadecimal provides would be pretty unnecessary and not that nice looking. Instead a better idea would be to find a list of colors that look nice and within that list find accessible combos. So that's what I did, and after a bit of searching I found two great options cloudflare designs color pallette & the best of from the color-names project both are still very large lists but the cloudflare one is significantly smaller so I'm going to go with that one but as you can see there are more options out there.

I created a colors.js file and exported the colors json from there, so now in my index file I can loop through each of them to get a combo that works (by works I mean a combo that is accessible according to WCAG standards, so a contrast ratio greater than 7.1). Once I get a working combo I'm creating a style element using those colors and appending it to the head of the document:

import { getContrast } from "color2k";
import { cloudflareColors } from "./colors";

let accessibleCombo = null;

while (!accessibleCombo) {
  let randomPair = [
    cloudflareColors[Math.floor(Math.random() * cloudflareColors.length)].hex,
    cloudflareColors[Math.floor(Math.random() * cloudflareColors.length)].hex,
  ];

  if (getContrast(randomPair[0], randomPair[1]) > 7.1)
    accessibleCombo = randomPair;
}

const newStyle = document.createElement("style");
newStyle.innerHTML = `
main {
  background-color: ${accessibleCombo[0]};
  color: ${accessibleCombo[1]};
}`;
document.head.appendChild(newStyle);

Pretty simple right? And the results are very pleasing to look at:

Learning how to do it ourselves

While using a library is awesome (especially a well made one) it's important that we understand how it works. So I decided that we could learn how to do this ourselves. The recommended method to get contrast ratio (by the WCAG at least) is to divide the relative luminance of the lighter color by the relative luminance of the darker color. What's a relative luminance you ask? Well it's the relative brightness of a color, basically how close it would be to black if the image was black & white (between 0 as pure white, which is not close at all and 1 which would be pure black).

So how do we calculate it then, well thankfully the WCAG has a guideline for that as well, the thing is to implement this formula you would have to have your color in RGB format so we need to implement a HEX → RGB conversion as well.

This is surprisingly easy to implement as all we need to do is split the string into groupings of 2s and then use the built in parseInt function to convert their radix:

const hexToRgb = (hexString) => {
  if (hexString.startsWith("#")) hexString = hexString.substr(1);
  return [
    parseInt(hexString.substring(0, 2), 16),
    parseInt(hexString.substring(2, 4), 16),
    parseInt(hexString.substring(4, 6), 16),
  ];
};

console.log(hexToRgb("#ffffff")); // [255, 255, 255]

Nice! That was pretty simple. Now let's implement the relative luminance formula using what WCAG gives us. This is the formula they have on their website:

So mapping this out would be like this. Take each value from our RGB array and divide it by 255 and then based on its size perform one of the two formulas given. Once we have the 3 values for each channel we'll do the final formula given at the top to get our luminance. Sounds good? Let's code it:

const relativeLuminance = (rgbArray) => {
  let [r, g, b] = rgbArray.map((channel) => {
    return channel / 255 <= 0.03928
      ? channel / 255 / 12.92
      : ((channel / 255 + 0.055) / 1.055) ** 2.4;
  });
  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
};

console.log(relativeLuminance(hexToRgb("#ffffff"))); // 1

We're very close to the result now. All we have to do is implement the final formula where we compare the luminance of the two colors. To be specific we have to check which one is the lighter and that has to be L1 in this formula: (L1 + 0.05) / (L2 + 0.05). Let's implement it:

const getContrast = (color1, color2) => {
  const luminance1 = relativeLuminance(hexToRgb(color1)),
    luminance2 = relativeLuminance(hexToRgb(color2));

  return luminance1 > luminance2
    ? (luminance1 + 0.05) / (luminance2 + 0.05)
    : (luminance2 + 0.05) / (luminance1 + 0.05);
};

And that's it we've done it! Here's the full code for our vanilla implementation that performs in the exact same way as using the colors2k library:

import { cloudflareColors } from "./colors";

const hexToRgb = (hexString) => {
  if (hexString.startsWith("#")) hexString = hexString.substr(1);
  return [
    parseInt(hexString.substring(0, 2), 16),
    parseInt(hexString.substring(2, 4), 16),
    parseInt(hexString.substring(4, 6), 16),
  ];
};

const relativeLuminance = (rgbArray) => {
  let [r, g, b] = rgbArray.map((channel) => {
    return channel / 255 <= 0.03928
      ? channel / 255 / 12.92
      : ((channel / 255 + 0.055) / 1.055) ** 2.4;
  });
  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
};

const getContrast = (color1, color2) => {
  const luminance1 = relativeLuminance(hexToRgb(color1)),
    luminance2 = relativeLuminance(hexToRgb(color2));

  return luminance1 > luminance2
    ? (luminance1 + 0.05) / (luminance2 + 0.05)
    : (luminance2 + 0.05) / (luminance1 + 0.05);
};

let accessibleCombo = null;

while (!accessibleCombo) {
  let randomPair = [
    cloudflareColors[Math.floor(Math.random() * cloudflareColors.length)].hex,
    cloudflareColors[Math.floor(Math.random() * cloudflareColors.length)].hex,
  ];

  if (getContrast(randomPair[0], randomPair[1]) > 7.1)
    accessibleCombo = randomPair;
}

const newStyle = document.createElement("style");
newStyle.innerHTML = `
main {
  background-color: ${accessibleCombo[0]};
  color: ${accessibleCombo[1]};
}
  `;
document.head.appendChild(newStyle);

Cool that was it for this post hope you find this little snippet useful & make something cool woth it. You can see it live at https://accessible-combos.now.sh or check out the code at https://github.com/kartiknair/accessible-combos. Thanks for reading, if you wanna say hello hit me up on twitter, I'm @kartikajitnair. Stay safe ✌.

Learn how to build a fast & responsive markdown editor with React, Firebase, & SWR

Kartik Nair — Sun, 10 May 2020 18:27:59 +0000

I've recently embarked on quite the arduous journey of building my own CMS from scratch. Why you ask? That's for a different post 😊. However while working on this project I discovered an amazing data fetching hook called useSWR created by the amazing people at Vercel, so I wanted to show you guys how SWR makes it so much easier to make fast and User-Friendly applications. It's surprisingly easy so let's get right into it. Since showing it to you with no context wouldn't be very interesting we're gonna build a markdown editor that uses Firebase for authentication and storing our data. So here we go...

What is SWR

SWR is a data fetching strategy standing for Stale While Revalidate. This is a pretty popular data fetching strategy but Vercel published an npm package with React hooks that make it easy to use this strategy in web applications. The basic idea of the useSWR hook can be explained by looking at an example:



import useSWR from "swr";

const App = () => {
  const { data, error } = useSWR("STRING_KEY", doSomethingWithKey);

  if (error) return <div>Error while loading data!</div>;
  if (!data) return <div>Loading...</div>;
  return <div>We have {data}!</div>;
};

As you can see the hook takes 2 arguments the first one is a string key that's supposed to be a unique identifier for the data usually this will be the URL of your API. And the the second argument is a function that returns data based on this key (usually some sort of fetcher function).

So now that we know the basics of SWR let's build an application with it. If you wanna skip ahead to a specific part check the Table of Contents below or if you wanna see the finished project then you can check it out live at https://typemd.now.sh or see the source code at https://github.com/kartiknair/typemd.

Prerequisites
Setup
Creating a Firebase App
The model
Configure Firebase in your code
Basic navigation
Setting up a Firestore database
Getting files from the database
Basic dashboard UI
The editor
Deleting files
Image uploads
General improvements
Conclusion

Also just wanted to say before we get into it that this post was originally published on my blog so feel free to check it out there: https://blog.kartikn.me/react-firebase-swr

Prerequisites

Make sure you have the latest (or somewhat recent) versions of Node and NPM installed, also have your favourite code editor on the ready we're gonna put it to lots of use today.

Setup

For our first step we're gonna use create-react-app to bootstrap a React project and also install a few dependencies:

firebase our "backend"
react-with-firebase-auth a HOC that makes authentication with firebase very easy
rich-markdown-editor is the markdown editor we'll use for this app. I chose this one specifically because it has a very friendly API to work and also has a very user-friendly design.
@reach/router as our client-side routing algorithm, you'll see why we'll need this very soon.

Run these commands to create the app and install said dependencies:



npx create-react-app markdown-editor

# Or on older versions of npm:
npm i -g create-react-app
create-react-app markdown-editor

cd markdown-editor
npm i firebase react-with-firebase-auth rich-markdown-editor @reach/router

I also uninstalled the testing libraries and testing specific code as those are beyond the scope of this post but you can keep them and use them as you like.

Creating a Firebase App

To be able to use Firebase in our web app we actually need to set up a Firebase project so let's do that. Head over to https://firebase.google.com and log in to your Google account. Then in the console create a new project:

I'm going to choose not to have analytics on but you can do so if you wish.

Now that we have our project created in the project click the little web icon:

And copy this configuration object it gives you and keep it wherever you like (don't worry too much about it you can come back and view it later in the dashboard):

We're also going to set up our authentication so head to the authentication section and choose whichever providers you would like to support and follow their instructions on how to set it up. The 'Google' provider works with 0 config so if you just want a quick start that's what I would recommend. I also followed the docs and enabled the 'GitHub' provider but that's up to you.

The model

Before we jump into the code let's structure the application in our head. We need mainly three different views: the 'Log In' view which the user will see if they are not logged in, the 'Dashboard' which will show a logged in user all their files, and finally the 'Editor' view which will be the view that the user will see when they are editing a file. Great now that we have that planned out in our head let's make it.

I personally don't like the way create-react-app so I'm gonna restructure the code a bit, but this is how I like to do it and you don't have to do it this way. It's well known in the React community that you can basically do whatever you want as long as you're comfortable with it, so do as you like but make sure to translate the paths that I'm using.

Configure Firebase in your code

Great now that we've done all our prep we can finally start working on the code. First let's set up firebase in our project, so you remember that configuration object now make a file in your project which exports that object out:



/* src/lib/firebaseConfig.js */

export default {
  apiKey: "YOUR_API_KEY",
  authDomain: "YOUR_AUTH_DOMAIN",
  databaseURL: "YOUR_DATABASE_URL",
  projectId: "YOUR_PROJECT_ID",
  storageBucket: "YOUR_STORAGE_BUCKET",
  messagingSenderId: "YOUR_SENDER_ID",
  appId: "YOUR_APP_ID",
};

You might be worried about having this hard coded in your code, but it isn't that much of an issue if somebody gets their hands on your configuration because we're gonna set up authentication rules on your database. If you're still worried you can add all these values to a '.env' file and import it in that way.

Now that we have this configuration we're gonna make another file where we initialize our firebase app using this config and then we'll export it out so we can reuse it in our code:



import * as firebase from "firebase/app";
import "firebase/auth";

import firebaseConfig from "lib/firebaseConfig";

// Check if we have already initialized an app
const firebaseApp = !firebase.apps.length
  ? firebase.initializeApp(firebaseConfig)
  : firebase.app();

export const firebaseAppAuth = firebaseApp.auth();

export const providers = {
  googleProvider: new firebase.auth.GoogleAuthProvider(),
  githubProvider: new firebase.auth.GithubAuthProvider(), // <- This one is optional
};

Great! Now that our firebase app is set up let's go back to the mental image we created of our app, you remember that?

Basic navigation

Well we're gonna implement that using reach-router and our firebase authentication HOC:



/* src/components/App/App.js */

import React from "react";
import { Router, navigate } from "@reach/router";

import withFirebaseAuth from "react-with-firebase-auth";
import { firebaseAppAuth, providers } from "lib/firebase";

import { Dashboard, Editor, SignIn } from "components";
import "./App.css";

const createComponentWithAuth = withFirebaseAuth({
  providers,
  firebaseAppAuth,
});

const App = ({ signInWithGoogle, signInWithGithub, signOut, user }) => {
  console.log(user);
  return (
    <>
      <header>
        <h2>TypeMD</h2>
        {user && (
          <div>
            <a
              href="#log-out"
              onClick={() => {
                signOut();
                navigate("/");
              }}
            >
              Log Out
            </a>
            <img alt="Profile" src={user.photoURL} />
          </div>
        )}
      </header>
      <Router>
        <SignIn
          path="/"
          user={user}
          signIns={{ signInWithGithub, signInWithGoogle }}
        />
        <Dashboard path="user/:userId" />
        <Editor path="user/:userId/editor/:fileId" />
      </Router>
    </>
  );
};

export default createComponentWithAuth(App);

Yep I know it's a lot of code, but bear with me. So the basic idea is that we have a constant Header component and then below that we have our different routes. Since we wrap our App component with the firebase authentication HOC we get access to a few props like the sign in, sign out methods and also the currently logged in user (if there is one). We pass the sign in methods to our SignIn component and then we pass the sign out method to our header where we have our logout button. So as you can see the code is pretty intuitive in its qualities.

Now let's see how we handle the user logging in on our Sign In page:



/* src/components/SignIn/SignIn.js */

import React from "react";
import { navigate } from "@reach/router";

const SignIn = ({ user, signIns: { signInWithGoogle, signInWithGithub } }) => {
  if (user) {
    navigate(`/user/${user.uid}`);
    return null;
  } else {
    return (
      <div className="sign-in-page">
        <h3>
          Welcome to TypeMD a simple &amp; beautiful online markdown editor
        </h3>
        <p>
          Sign in with your social accounts to have files that are synced
          accross devices
        </p>
        <div className="sign-in-buttons">
          <button onClick={signInWithGoogle}>Sign in with Google</button>
          <button onClick={signInWithGithub}>Sign in with GitHub</button>
        </div>
      </div>
    );
  }
};

export default SignIn;

As you can see those methods we passed down to it are being used when the buttons are clicked and then we check if there is a logged in user we redirect them to the dashboard using the navigate method that reach-router provides.

Setting up a Firestore database

Now that we have authentication set up we need to set up our database, so let's head to our firebase console again and let's make a firestore database. In your console click on database in the sidebar and choose 'Cloud Firestore' if it's not already selected. Then click start collection:

I'm going to name the collection 'users' because that's how we're going to manage our data:

For the first document I'm going to just add a test one because we're going to delete this right after:

Now let's delete the test document:

If you remember I told you before that it doesn't matter if your configuration object gets leaked that's because we're going to head to the 'rules' section and set up a rule so that an authenticated user can only access their file. The language is pretty self explanatory so here's the rule:



rules_version = '2';
service cloud.firestore {
    match /databases/{database}/documents {
        // Allow only authenticated content owners access
        match /users/{userId}/{documents=**} {
            allow read, write: if request.auth.uid == userId
        }
    }
}

This rule works because of the way we're going to structure our data. The way we do it is once the user logs in we check if they're id is in the database, if it is we get that users files subcollection and return that, if they're not in the database then we'll create an empty entry for them which they can add files to later. The authentication rule just makes sure that an authenticated user can only access their files and nobody else's.

Now if you remember our firebase.js file where we exported our firebase app and authentication providers, well in the same file add these two lines to make our database accessible by other files:



import "firebase/firestore";
export const db = firebaseApp.firestore();

Getting files from the database

Now we can import that in our dashboard and create a function wherein we'll check if a user of the given id exists in the database, if so we return their data, and if not we create it let's call it getUserData:



import { db } from "lib/firebase";

const getUserFiles = async (userId) => {
  const doc = await db.collection("users").doc(userId).get();

  if (doc.exists) {
    console.log("User found in database");
    const snapshot = await db
      .collection("users")
      .doc(doc.id)
      .collection("files")
      .get();

    let userFiles = [];
    snapshot.forEach((file) => {
      let { name, content } = file.data();
      userFiles.push({ id: file.id, name: name, content: content });
    });
    return userFiles;
  } else {
    console.log("User not found in database, creating new entry...");
    db.collection("users").doc(userId).set({});
    return [];
  }
};

As you can see from the above code firebase has done an amazing job at having readable queries which I appreciate a lot especially when debugging.

This is pretty great but we don't really have any files to look at. So let's also make a method to create a file based on a user ID and file name:



const createFile = async (userId, fileName) => {
  let res = await db.collection("users").doc(userId).collection("files").add({
    name: fileName,
    content: "",
  });
  return res;
};

Pretty simple right? In this function we're finding our user in the users collection and the in that user's files sub-collection we're adding a new file. Now we're using the add function instead of set as we were using before so that firebase can randomly generate the ID for our file. This allows users to have multiple files of the same name with no issues.

Basic Dahsboard UI

Now we can start with the UI for our Dashboard so let's just make a simple list where each element will be using reach-router's Link to navigate the user to the editor page:



/* src/components/Dashboard/Dashboard.js */

const Dashboard = ({ userId }) => {
  const [nameValue, setNameValue] = useState("");
  const { data, error } = useSWR(userId, getUserFiles);

  if (error) return <p>Error loading data!</p>;
  else if (!data) return <p>Loading...</p>;
  else {
    return (
      <div>
        <form
          onSubmit={(e) => {
            e.preventDefault();
            if (nameValue) {
              setNameValue("");
              createFile(userId, nameValue);
              mutate(userId);
            }
          }}
          className="new-file-form"
        >
          <input
            type="text"
            placeholder="Your new files name..."
            value={nameValue}
            onChange={(e) => setNameValue(e.target.value)}
          />
          <button type="submit" className="add-button">
            Create
          </button>
        </form>
        <ul className="files-list">
          {data.map((file) => {
            return (
              <li key={file.id} className="file">
                <Link to={`/user/${userId}/editor/${file.id}`} className="link">
                  {file.name}
                </Link>
              </li>
            );
          })}
        </ul>
      </div>
    );
  }
};

Again we have a lot of code but that's mostly just the UI. However this is the first time we're using the useSWR hook and we're passing it the user ID as a key and then for it's data fetching function we pass it the getUserData method we created before. Then we use the same pattern that I showed you in the first example to check for errors and loading and finally if we have the data we loop through and show it in a list. We're also using hooks to keep track of the create file input form but I'm hoping you're already familiar with how to use them.

This is great but right now our Links going to the editor are pretty useless because we don't have an Editor component yet so how bout we do that now.

The editor

As I mentioned earlier we're using an amazing open-source editor called rich-markdown-editor so we're going to import it and then use it's defaultValue prop to show us our saved content:



/* src/components/Editor/Editor.js */

import React, { useState, useEffect } from "react";
import useSWR, { mutate } from "swr";
import { db } from "lib/firebase";
import { Link, navigate } from "@reach/router";
import MarkdownEditor from "rich-markdown-editor";

const getFile = async (userId, fileId) => {
  const doc = await db
    .collection("users")
    .doc(userId)
    .collection("files")
    .doc(fileId)
    .get();

  return doc.data();
};

const Editor = ({ userId, fileId }) => {
  const { data: file, error } = useSWR([userId, fileId], getFile);
  const [value, setValue] = useState(null);

  useEffect(() => {
    if (file !== undefined && value === null) {
      console.log("Set initial content");
      setValue(file.content);
    }
  }, [file, value]);

  const saveChanges = () => {
    db.collection("users").doc(userId).collection("files").doc(fileId).update({
      content: value,
    });
    mutate([userId, fileId]);
  };

  if (error) return <p>We had an issue while getting the data</p>;
  else if (!file) return <p>Loading...</p>;
  else {
    return (
      <div>
        <header className="editor-header">
          <Link className="back-button" to={`/user/${userId}`}>
            &lt;
          </Link>
          <h3>{file.name}</h3>
          <button
            disabled={file.content === value}
            onClick={saveChanges}
            className="save-button"
          >
            Save Changes
          </button>
        </header>
        <div className="editor">
          <MarkdownEditor
            defaultValue={file.content}
            onChange={(getValue) => {
              setValue(getValue());
            }}
          />
        </div>
      </div>
    );
  }
};

export default Editor;

Just like before we're using the same pattern where we have a method that gets the data and then we have useSWR with our key. In this case we're using an array of keys so that we can pass down both the user ID and file's ID to the fetcher function (which is getFile() here). We're also using the useState() hooks to keep track of the editors state, usually we would update the value of the editor with our stateful value but we don't have to do that here. Once our data is available we just pass it as the defaultValue to our editor and then track changes using it's provided onChange method.

You may have noticed the useEffect() at the top of the function. We're using that to actually set the initial value of our stateful value variable this helps us keep track of whether the user has unsaved changes or not.

Look at us now! We have a basic but working editor, now where do we go from here? Well there's a lot (& I mean a lot) of stuff to add to this & I'll cover a few of those in the improvements section. But for now we have two more crucial features that we could add and one of them is a lot more difficult to implement than the other. So let's start with the easy one:

Deleting Files

A pretty small but important thing to add to our Dashboard component. For this we're going to use the ref.delete method that firebase provides, here's our deleteFile function:



const deleteFile = async (userId, fileId) => {
  let res = await db
    .collection("users")
    .doc(userId)
    .collection("files")
    .doc(fileId)
    .delete();
  return res;
};

Now we can actually call that when a button is pressed:



    {...}
      <button
        onClick={() => {
          deleteFile(userId, file.id).then(() => mutate(userId));
        }}
        className="delete-button"
      >
        x
      </button>
    {...}

Great! Now let's get to the more difficult feature:

Image uploads

The editor we're using, rich-markdown-editor has a prop called uploadImage which expects a promise that will resolve to string URL of the uploaded image. To this callback it'll provide the image as a JavaScript File object. For this we're going to have to setup a storage bucket in firebase. So let's head back to the console and click on Storage in the sidebar. Click the 'Get Started' button and create your bucket using whatever location you want. Once you're in we're again going to change our security rules but this time we'll allow reads from anyone but writes only from authenticated users. Here are the rules for that:



rules_version = '2';
service firebase.storage {
    match /b/{bucket}/o {
        match /users/{userId}/{allImages=**} {
            allow read;
            allow write: if request.auth.uid == userId;
        }
    }
}

Like we did previously with firestore we need to create a reference to our storage bucket using our initialized firebase app so let's go back to firebase.js and do that:



import "firebase/storage";
export const store = firebaseApp.storage();

Great! Now we can import this reference in our code and use it to read or write to the store. So let's make a function that takes a File object and uploads it to the store:



const uploadImage = async (file) => {
  const doc = await db
    .collection("users")
    .doc(userId)
    .collection("images")
    .add({
      name: file.name,
    });

  const uploadTask = await store
    .ref()
    .child(`users/${userId}/${doc.id}-${file.name}`)
    .put(file);

  return uploadTask.ref.getDownloadURL();
};

Ok so since firebase's storage offering doesn't have a way to upload files with a random unique name we're going to create a sub-collection for each user called images and then every time we upload an image we'll add it in there. After that completes we take that ID and add a hyphen and the original filename to it and then we upload it using the ref.put method that firebase storage provides. After the upload task completes we return it's URL using the getDownloadURL method.

Now all we need to do is provide this method as a prop to our editor:



{...}
    <MarkdownEditor
        defaultValue={file.content}
        onChange={(getValue) => {
        setValue(getValue());
        }}
        uploadImage={uploadImage}
    />
{...}

Great! Look at us we've come so far. We have a half-decent markdown editor on hand add a few hundred lines of CSS and you'll have a full-fledged side project. But there are a few things that we can add easily to improve the general user experience, so let's get to them.

General Improvements

So there are many things to improve but the first thing I wanted to handle was the fact that if you're not logged in & visit any of the pages it just errors out. So I added a useEffect hook where it'll redirect you back to the home page:



useEffect(() => {
  if (!user) {
    navigate("/");
  }
}, [user]);

Once that was out of the way I also wanted to give the user feedback when they had unsaved changes and tried to leave the page. This is accomplished using another useEffect hook so that we can add a listener to the beforeunload event:



const onUnload = (event) => {
  event.preventDefault();
  event.returnValue = "You have unsaved changes!";
  return "You have unsaved changes!";
};

useEffect(() => {
  if (file && !(file.content === value)) {
    console.log("Added listener");
    window.addEventListener("beforeunload", onUnload);
  } else {
    window.removeEventListener("beforeunload", onUnload);
  }

  return () => window.removeEventListener("beforeunload", onUnload);
});

Pretty simple but in my opinion makes a significant difference. I also added a toasts using the amazing react-toastify packages to let the user when their changes have been saved or else when an error occurs:



import { ToastContainer, toast } from "react-toastify";

const saveChanges = () => {
    {...}
    toast.success("🎉 Your changes have been saved!");
};

{...}
    <div>
        <div className="editor">
        <MarkdownEditor
            defaultValue={file.content}
            onChange={(getValue) => {
            setValue(getValue());
            }}
            uploadImage={uploadImage}
            onShowToast={(message) => toast(message)}
        />
        </div>
        <ToastContainer />
    </div>
{...}

And that's all for general tiny improvements, the toasts are perhaps a touch too much but I think they're pretty delightful (might remove it though).

Conclusion

So I hope you were able to learn how amazing this stack for web applications is. Using SWR & Firebase with React makes for an amazing developer experience and also (because of the caching) gives the users a blazing fast user experience. You can see the final result at https://typemd.now.sh & feel free to check out/fork the code from the GitHub repo. Thanks for reading till the end of this super long post, I've been using twitter a lot more recently so feel free to say hello over there: @nairkartik_. Stay safe ✌.

Finally built a portfolio/personal website. Can I get a review?

Kartik Nair — Sat, 02 May 2020 12:03:29 +0000

Hello everyone! I decided to put some time away this week and build a solid personal website and blog for myself and here's the final result: https://kartikn.me. It's built using Next.js and hosted on Vercel, the code for it is also open-source.

I just needed some advice because currently I'm a university student (in my first year) and I was considering getting a job over the summer break or working freelance. Would this be a good idea? Am I ready?

My new React workflow with Parcel

Kartik Nair — Fri, 03 Apr 2020 13:19:35 +0000

Note this post was originally posted on my blog

Hello everybody 👋, I hope you’re staying safe out there in these trying times. I haven’t written anything in a while due to this situation but I thought why not share my new react workflow since some people might find it interesting, so here we go.

I’ve almost always used create-react-app as my react starter, sometimes Gatsby or Next.js for Static Sites & Server Side Rendering respectively, but mostly create-react-app for all my Single Page Apps. However as some of you might know the internals of create-react-app are abstracted away using the react-scripts package. This helps beginners like me get easily started without having to worry about webpack. But I was curious on how it actually worked and decided to make a react application from scratch.

While learning about bundlers I discovered parcel a bundler that requires zero configuration and works right out of the box. This got me really excited and after a few steps I got parcel working with react as well, here’s how I set it up. Also make sure to stick around till the end to see a super easy way to get started using a tiny package I made.

Step 0

If you don't have node & npm installed already then go ahead and download both of their latest versions for your system from the previous links.

Step 1

Create a directory for your project, on Windows I used the following commands I'm sure you can translate them over to your OS.

mkdir react-with-parcel
cd react-with-parcel

Step 2

Initialize an npm project and download your dependencies with the following commands:

npm init -y
npm i -D parcel-bundler @babel/core @babel/preset-env @babel/preset-reactnpm i react react-dom

As you can see we initialize an npm project using npm init the -y flag is just there so it doesn't ask you the default questions. Then we install parcel-bundler and a few babel packages as dev dependencies (that's why the -D flag is used) and also react & react-dom as regular dependencies. I'm currently still using parcel v1 (i.e the parcel-bundler npm package not parcel) that's because parcel v2 is still in alpha and not yet stable. However once it is stable it promises some amazing features like out of the box support for jsx so we wouldn't even have to configure babel.

Step 3

Now that we have all our dependencies installed we can actually create our application. Parcel works on the principal of having one html file as it's entry point (you can have multiple as well) and then uses that to bundle all the assets. So let's create an index.html file. Personally I put this file in a src directory but if you want you can directly put it in the root directory of your project. However make sure to change the path in the following steps.

<!--The src/index.html file-->

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Parcel & React</title>
  </head>
  <body>
    <div id="root"></div>
    <script src="./index.js"></script>
  </body>
</html>

As you can see we create a div with the id of "root" and then use a script tag to link to our JavaScript file. So let's create that JavaScript file.

// The src/index.js file

import React from "react";
import ReactDom from "react-dom";
import "./index.css";

const App = () => <h1>Hello World</h1>;

ReactDom.render(<App />, document.getElementById("root"));

We've kept the file very simple but you can very easily import other components & css files either from your files or from npm packages. SInce I've imported "./index.css" let's go ahead & make that file:

/* The src/index.css file */

* {
  margin: 0;
  padding: 0;
  box-sizing: border-box;
}

html {
  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen,
    Ubuntu, Cantarell, "Open Sans", "Helvetica Neue", sans-serif;
}

code {
  font-family: "Courier New", Courier, monospace;
}

We've kept it very basic just some small resets and system fonts.

Step 4

We're almost done! Now go to your package.json and add the start & the build scripts. This is an example of how your package.json will look now:

{
  "name": "react-with-parcel",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "start": "parcel src/index.html",
    "build": "parcel build src/index.html"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "dependencies": {
    "react": "^16.13.1",
    "react-dom": "^16.13.1",
  },
  "devDependencies": {
    "@babel/core": "^7.9.0",
    "@babel/preset-env": "^7.9.0",
    "@babel/preset-react": "^7.9.4",
    "parcel-bundler": "^1.12.4"
  }
}

All we're doing is calling parcel & giving it the html file we want to use & for building a production build we call parcel build & again give it the html file. Parcel build will output to the dist directory in your project.

And you're done

That's it just open up a terminal & run npm start and a development server should start up on https://localhost:1234. Amazing right!

Making this even easier

Since I expect to be doing this many more times I decided to make a tiny npm package to bootstrap the project for me. So that it would be just as easy as create-react-app. And I'm finally done with the package I called it parcreate and you can run it in your terminals now.

# The recommended way: (so that you have the latest version)
npx parcreate my-apps-name

# The old fashioned way:
npm i -g parcreate
parcreate my-apps-name

Creating parcreate was a lot of fun and I will be adding more templates with additional features like scss very soon so keep a lookout.

You can find the github repo for parcreate here and please let me know if you face any issues running it as I've only tested it on windows yet. Thank you all for reading about my findings & be sure to stay safe. Bye!

P.S. I’m trying to be more active on social media & meet more people so drop me a message on my twitter (@nairkartik_).

How to build a simple static site generator using node.js

Kartik Nair — Tue, 10 Mar 2020 08:10:14 +0000

My blog (where this article was originally posted) is built using Gatsby.js an awesome static site generator for React (well it was built using Gatsby but I ended up switching to this project as you'll find out at the end). Gatsby was pretty easy to pick up and all I had to do was customize the gatsby-blog-starter to get something great. But I was curious how the generator so I decided to try and build a simple/barebones static site generator using nodejs. Feel free to follow along with the code on GitHub.

Why SSGs?

I love static site generators a lot because it allows you to use whatever heavy/bloated framework you want but the end result will still be just simple and light HTML, & CSS. This gives a sense of freedom which we wouldn't normally have if we were dealing with a create-react-app for example.

For this project here's the lighthouse score for the final result:

I know right! Pretty amazing. The only reason it didn't ace it was because of the heavy fonts but that's fine because they add enough aesthetic value for me to keep them.

Setup

So let's get started! Open up your command line and navigate to where you would like to make your project and then use the following commands to create a new nodejs project (these are for windows I'm sure you can translate them over to your OS).



mkdir node-ssg && cd node-ssg
npm init -y

Now we're gonna install some packages that are gonna make our life a hell of a lot easier while dealing with the data. The packages are: front-matter for extracting the yaml front matter from our posts, marked for converting markdown to html, and highlight.js for syntax highlighting in code. We can install all of these using the following command:



npm i front-matter marked highlight.js

Alright now we can start with our project.

The build script

Let's think about what we wanna do first of all. So we want a build script that takes all the markdown posts from the content directory and spits out static html files in the public directory.

First of all let's create the script that will run when we call build. We'll put all our source code in the src directory so go ahead and make that in the root of your project. Then open up the project in your favourite code editor (I'm using VS Code) and add in a JavaScript file called index.js. Now we can add our build script to our package.json simply calling using node to run our index.js file. Your package.json should now look like this:



{
  "name": "planar",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "build": "node ./src/index.js"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "dependencies": {
    "front-matter": "^3.1.0",
    "highlight.js": "^9.18.1",
    "marked": "^0.8.0"
  }
}

Great now we can call npm run build in our project and it'll run our index.js file. Only problem is that our file doesn't do anything yet.

For testing purposes I'm going to create a content folder with my own blog posts. Since my current blog is also built using a static site generator I can just copy my content folder from there.

Decisions to make

Alright there are many decisions you should make before starting for example how should posts be stored? Should they be stored in their own folder or just as .md file? Where do you store images? And a lot more.

But since this projects scope is not very large I'm gonna go with a very simple file tree. All posts will be stored in the content directory as markdown files (.md) & other resources (like images) can be stored in ./public/assets/. These decisions were made to make file reading and writing simpler for this specific scenario but you can always change them to whatever is better suited for your project.

The config.js file

We can put the decisions we made in a config.js file so we can access it from anywhere by just requiring it. I put them in a dev object because there are other properties which we will add later. So this is how it looks right now:



const config = {
  dev: {
    postsdir: "./content",
    outdir: "./public"
  }
};

module.exports = config;

Getting the posts

Alright let's start first of all with getting all the posts from the content directory. We can do this using the fs api that node.js gives us. So first of all we import fs and create an instance of it:



const fs = require("fs");

Now we can use the methods that fs provides in this syntax: fs.methodName(). For getting posts we can use the readdirSync() method that fs provides. So let's see how it would look if we just got all the posts and logged them to the console:



const config = require("./config");

const posts = fs
  .readdirSync(config.dev.postsdir)
  .map(post => post.slice(0, -3));

console.log(posts);

Now run npm run build in your console and you should see a list of posts if you did everything right. The reason we use slice() in the code is to get rid of the .md extension. You'll see why we have to do that later on.

Parsing post markdown

If you remember in the beginning we installed an npm package called front-matter. It helps us extract yaml front-matter from files. What is yaml front-matter? Well it's this amazing thing that lets you add extra yaml data to your files using --- before and after it to delimit it from the rest of the content. Here's an example of a blog post using yaml front-matter:



---
title: Post One
date: "2020-02-28T22:19:00Z"
description: My reasons for starting a blog.
---

# This is an amazing blog post.

Really it's just great

So now since we've gotten the posts in the previous step now we can parse them using front-matter. We're gonna put all of this post related code in posts.js so we have a cleaner working environment. So let's start off with getting the content from our files.

We can do that using the provided fs.readFile() method. Here's how it would look just logging the content of the file to the console:



console.log(fs.readFileSync("./foo.md"));

But since we want reusable code that we can use for every single post in a loop, we'll put it in a function called createPost(). This function will use front-matter to take the content of the file and give us an object. This object will have the front-matter properties we set in a property called attributes & the rest of the content will be in a property called body. We can use front-matter by creating an instance to it using require and then calling it on our data once we read it from the file.

Here's how that would look like:



const config = require("./config");
const fm = require("front-matter");
const marked = require("marked");

const createPost = postPath => {
  const data = fs.readFileSync(`${config.dev.postsdir}/${postPath}.md`, "utf8");
  const content = fm(data);
  content.body = marked(content.body);
  content.path = postPath;
  return content;
};

module.exports = createPost;

If you check out the code you'll see that I call marked on the body of our post. All this does is convert the markdown into HTML so we can easily display it in our website later. I've also added the path of the post as an extra property because we will need it later on.

Now let's use this method in index.js and just log the output:



const config = require("./config");
const createPost = require("./posts.js");

const posts = fs
  .readdirSync(config.dev.postsdir)
  .map(post => post.slice(0, -3))
  .map(post => postMethods.createPost(post));

console.log(posts);

Configuring marked and syntax highlighting

Since we would like to use highlight.js to highlight our code. We can do that using marked and it's configuration object. Make a file called marked.js and in that we'll create an instance of marked configure it and then export it. Here's how that looks:



const marked = require("marked");

marked.setOptions({
  renderer: new marked.Renderer(),
  highlight: function(code, language) {
    const hljs = require("highlight.js");
    const validLanguage = hljs.getLanguage(language) ? language : "plaintext";
    return hljs.highlight(validLanguage, code).value;
  },
  pedantic: false,
  gfm: true,
  breaks: false,
  sanitize: false,
  smartLists: true,
  smartypants: false,
  xhtml: false
});

module.exports = marked;

So now every time you use marked require it from this file directly.

Generating post HTML pages

Now we start with the actual page generation. To start of, we want it to create the public folder, if it doesn't exist already, we can do that using the fs.mkdirSync() and fs.existsSync() functions. Let's add that to our index.js file:



if (!fs.existsSync(config.dev.outdir)) fs.mkdirSync(config.dev.outdir);

Now in our posts.js file let us make a createPosts() function, that will create and write the HTML files to the public directory. But before that we need a helper function called posthtml that will take the post JSON object and return a complete HTML page that we can simply write to a file. We will use the power of template literals to make our life easier in this function here's how it looks:



const posthtml = data => `
<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <meta name="description" content="${data.attributes.description}" />
        <title>${data.attributes.title}</title>
    </head>
    <body>
        <header>
            <a href="/">Go back home</a>
        </header>
        <div class="content">
                <h1>${data.attributes.title}</h1>
            <p>${new Date(parseInt(data.attributes.date)).toDateString()}</p>
            <hr />
            ${data.body}
        </div>
    </body>
</html>
`;

The reason I create a new Date() when adding the date to the post is so that all the dates have a consistent format. This is quite an opinionated way of doing it as it requires the date provided in the front-matter to be a "number representing the milliseconds elapsed since the UNIX epoch". However I don't mind running a quick Date.now() in the browser dev tools to get that number before I post. You can change that in the code if you would like 🤷‍♀️.

Now we can create a function called createPosts() that'll take the output of the createPost() function and generate an HTML file. Here's how it looks:



const createPosts = posts => {
  posts.forEach(post => {
    if (!fs.existsSync(`${config.dev.outdir}/${post.path}`))
      fs.mkdirSync(`${config.dev.outdir}/${post.path}`);

    fs.writeFile(
      `${config.dev.outdir}/${post.path}/index.html`,
      posthtml(post),
      e => {
        if (e) throw e;
        console.log(`${post.path}/index.html was created successfully`);
      }
    );
  });
};

module.exports = {
  createPost: createPost,
  createPosts: createPosts
};

As you can see it doesn't generate a file called postname.html but rather it makes a directory called postname and then adds and index.html in that directory so that the path for that post in the browser will be yourwebsite/postname not yourwebsite/postname.html.

Now let's call it in index.js and see if it worked:



const fs = require("fs");
const postMethods = require("./posts");
const config = require("./config");

const posts = fs
  .readdirSync(config.dev.postsdir)
  .map(post => post.slice(0, -3))
  .map(post => postMethods.createPost(post));

if (!fs.existsSync(config.dev.outdir)) fs.mkdirSync(config.dev.outdir);

postMethods.createPosts(posts);

If everything worked right you should've seen a public directory pop up with a few directories in it (based on how many posts you had).

Author about section

This blog will also include a small about section in it's homepage for the author, so we need to add the info for that into our config.js file. So here's our revised config.js file:



const config = {
  blogName: "Blog",
  blogDescription: "Sharing what I learn as a web developer & designer",
  authorName: "Kartik Nair",
  authorDescription:
    "a web developer and designer making lot's of stuff in Dubai",
  authorTwitter: "https://twitter.com/kartiknair",

  dev: {
    postsdir: "./content",
    outdir: "./public"
  }
};

module.exports = config;

The homepage

The homepage will be the index.html file in the public directory. It should have a header with the blog's name and a small about section for the author. We can use template literals like we did before to generate the HTML for that. Let's call the function homepage() and put it in a file called homepage.js . Here's how that file looks now:



const homepage = posts => `
<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <meta name="description" content="${config.blogDescription}" />
        <title>${config.blogName}</title>
    </head>
    <body>
        <div class="grotesk">
            <header>
                <h1>${config.blogName}</h1>
                <p>—</p>
                <p>This blog is written by ${config.authorName}, ${
  config.authorDescription
}. To find out what he's up to <a href="${
  config.authorTwitter
}">follow him on twtter</a></p>
                <hr />
            </header>

            <div class="posts">
                ${posts
                  .map(
                    post => `<div class="post">
                    <h3><a href="./${post.path}">${
                      post.attributes.title
                    }</a></h3>
                        <small>${new Date(
                          parseInt(post.attributes.date)
                        ).toDateString()}</small>
                        <p>${post.attributes.description}</p>
                    </div>`
                  )
                  .join("")}
            </div>

            <footer>
                ${`<p>© ${new Date().getFullYear()} ${
                  config.authorName
                }, Find the code on <a href="github.com/kartiknair/blog">GitHub</a></p>`}
            </footer>
        </div>
    </body>
</html>
`;

Now we need to actually create the file so we can add this HTML to it. We can make that a function called addHomepage() and also add that to the same file. Here's how it looks:



const addHomePage = posts => {
  fs.writeFile(`${config.dev.outdir}/index.html`, homepage(posts), e => {
    if (e) throw e;
    console.log(`index.html was created successfully`);
  });
};

Now we can simply export it out using module.exports = addHomePage and call it in our index.js file. Here's our revised index.js file:



const fs = require("fs");
const postMethods = require("./posts");
const config = require("./config");
const addHomePage = require("./homepage");

const posts = fs
  .readdirSync(config.dev.postsdir)
  .map(post => post.slice(0, -3))
  .map(post => postMethods.createPost(post))
  .sort(function(a, b) {
    return b.attributes.date - a.attributes.date;
  });

if (!fs.existsSync(config.dev.outdir)) fs.mkdirSync(config.dev.outdir);

postMethods.createPosts(posts);
addHomePage(posts);

As you can see I also sorted the posts by latest date so that the latest post is first.

The assets directory

We can store any files that we don't want touched by the generator in ./public/assets. For example if you wanted to add styling to this blog you could add the following to your homepage function:



<link rel="stylesheet" href="./assets/main.css" />

and now you can style your blog as you like. Images also work in the same way, for example if in a post markdown file you wanted to add an image you could do the following:



Here's an image:
![Wow look at this beautiful thing](../assets/images/wow.png)

Making it look pretty

Ah! Now my favourite part, it's time to make it look nice. I don't know about you but looking at those default HTML styles was hurting me a lot. To make my life simple I'm just gonna plug grotesk into the project & customize it. Here's the ./public/assets/styles/main.css file:



:root {
  font-size: calc(0.75rem + 0.5vw);
}

.grotesk {
  width: 60%;
  margin: 5% 20% 0 20%;
}

@media (max-width: 500px) {
  .grotesk {
    width: 80%;
    margin: 8% 10% 0 10%;
  }
}

img {
  max-width: 100%;
}

As you can see I've decided to go with fluid type for this project. I also brought in grotesk.light.scss and customized the variables. Here's how the variables look now:



$bg: #1e3b5a;
$fg-body: #99b7c3;
$fg-headings: #c1d6df;

$hr-color: rgba(153, 183, 195, 0.2);

$a-color: #d8e9f0;

$pre-bg: rgba(153, 183, 195, 0.07);
$pre-color: $fg-body;

$inline-code-bg: rgba(153, 183, 195, 0.07);
$inline-code-color: #c1d6df;

$quote-bg: $bg;
$quote-border: #8a4baf;
$quote-color: #6a727c;

I also customized the fonts.scss file that came with grotesk. Here's how it looks like now:



@font-face {
  font-family: lyon;
  src: url("../fonts/LyonDisplay-Bold.otf");
  font-weight: 800;
}

@import url("https://fonts.googleapis.com/css2?family=EB+Garamond:wght@500&display=swap");

$font-fam-main: "EB Garamond", serif;
$font-fam-headings: lyon, serif;
$font-fam-mono: Menlo, Monaco, Consolas, "Liberation Mono", "Courier New",
  monospace;
$line-ht-main: 1.5;
$line-ht-mono: 1;

As you can see I've imported two fonts for this blog. Lyon Display which is locally hosted & EB Garamond which is a Google Font.

That's it for the styling. It ended up looking way better than I expected you can check it out live here, but if you don't wanna visit it live here's an image:

Hosting

I personally like using Zeit Now for hosting but some other free options I like as well are Netlify and GitHub Pages. Since now integrates so well with npm build scripts that output to a public directory, all I had to do was run now --prod in the root of the directory (when you run it the first time it'll ask you some configuration questions the default answer to all of them is fine). Now everytime I want to update my blog all I have to run is now --prod again and it'll update my blog and run npm run build by default.

Final Thoughts

Thanks for reading this very long article. I hope you learnt a little something about nodejs. I personally learnt a lot about the fs api and enjoyed making this a lot. I liked it so much that I actually ended up switching my personal blog from gatsby to this. That might be a bad decision but I can always work it out later. Just a reminder you can find all the source code on GitHub so feel free to fork it or open an issue if you find something wrong.

I'm gonna keep working on this to fine tune it to my needs, and maybe experiment with a few different things like maybe lit-html or mustache for templating. But for now that's it for this post, see you in another one very soon. Peace ✌

How I built 'grotesk' a react component (and css library) that makes web type simple

Kartik Nair — Thu, 27 Feb 2020 08:00:16 +0000

Hello everybody this is my first ever blog post so I would love to hear your critiques. Just leave a comment with any advice you have (writing style, grammar, future ideas, etc).

What is grotesk?

Grotesk is a css library and react component that aims to make web typography simple. The reason I built it is because I've noticed that I start almost every static website off with the same set of themes or typographic rules, so I decided to build a tiny library that I can just plug into my next project easily. Since I mostly only work on react applications and plain ol' static websites I made a react component and a css library.

Goals

The goal with grotesk was not to be an end all of styling it's supposed to be a very minimal stater that can support your regular styling. For a single theme the minified css file comes in at only 1.8kb which I think is quite amazing.

It also strives to make customization as easy as possible offering more than 15 different variables you can work with.

How it works

I built grotesk.css using scss for variables and customization (because of css custom properties' comparatively low browser support). This was the first project I used scss in and I have to say the workflow with the live sass compiler in VS Code is very smooth and the dev experience was very enjoyable.

Since this was my first ever npm package I decided to go with something simple for the react component so I decided to use create-react-library which made it extremely easy to build and publish the component. For the styling and customization I decided to go with emotion as I wanted something simple yet powerful that could be dynamically themed.

Customization

Customization was very simple to implement in the css library because all the user had to do was change the scss variables at the top of the file and the rest would be managed by the power of scss. For the react component however it was a bit more complex.

The way I decided to go about it was to allow the user to add an optional theme prop to their <Grotesk> component. It takes an object that allows them to change the variables and if any properties are excluded they revert to the default.

Here is an example theme:

const theme = {
    bg: '#ffffff',
    fgBody: '#2d3748',
    fgHeadings: '#000000',

    hrColor: 'rgba(0, 0, 0, 0.07)',

    linkColor: '#8a4baf',

    preBg: 'rgba(0, 0, 0, 0.04)',
    preColor: '#2d3748',

    inlineCodeBg: 'rgba(0, 0, 0, 0.04)',
    inlineCodeColor: 'hsl(0, 79 %, 63 %)',

    quoteBg: '#ffffff',
    quoteBorder: '#8a4baf',
    quoteColor: '#6a727c',

    fontFamMain: 'space-grotesk, sans-serif',
    fontFamMono: 'Menlo, Monaco, Consolas, "Liberation Mono", "Courier New" monospace',
    lineHtMain: '1.5',
    lineHtMono: '1'
}

grotesk vs grotesk.css

Which one is for you? I would personally recommend the css library for almost all people. Even if you are using a react project, for most cases the css library is good enough. The only cases where I would recommend the react component is when your project already uses emotion or if you are planning to do a lot of dynamic theming (like more than two themes).

My process

For the css library my process was very simple, all I did was first of all create the html file with all the content i wanted to style and then I started off working on grotesk.light.scss . Since I use VS code the compiling was very simple with the amazing Live Sass compiler plugin (highly recommend it).

For the react component however the process was a bit more complicated but as I mentioned above emotion and create-react-library really do help out, especially if you're a beginner like me.

Final notes

I'm sure there's probably some bugs in there that I haven't yet encountered and I might be doing many other things wrong but that's the reason I've open sourced the project. Just head over to github if you encounter any bugs and open an issue and I'll look into it asap. Also if you think you can improve grotesk just open a PR with your contribution and I'll add it in. Let's take full advantage of the power of open source guys.

P.S: I would love to add a "Websites that use grotesk" secotion to the README, so if you've made a website using grotesk or if you have any feature requests just DM me over at twitter ([at]nairkartik_), I would love to hear from you. Peace. ✌️