Streams?​

Stream is a confusing term and it is used in multiple situations. The stream I discuss in this post refers a stream of events which is usually implemented by Kafka where the order of events matters. in . Such implementation can be found in Event Sourcing pattern to de-couple services. In some simpler cases, a stream can be used to get updates of remote resources asynchronously instead of consuming remote endpoints synchronously to improve the resiliency.

Normally such patterns come with a cost. By consuming the stream, we no longer have the control of what and how we want to consume. Therefore, we need to handle errors in such a way that other events are not impact. In other words, we need a more complicated error handling mechanism than just retrying to call remote endpoints. In this post, I would like to introduce few approaches that I find effective and useful.

Error when Consuming Streams​

What is error when consuming? How does it happen?

Why we should handle error?​

How does it impact? => Why we should handle it? What is the problem hand handling it

How to handle errors?​

Errors can come from many cases, it could come from bad codes or some dependency errors like DB or networks. The easiest approach is to skip those errors if possible. However, most of the time, we need to handle the error gracefully.

In memory retry​

I would say this approach is quite straight forward. All we need is just an in-memory retry and good back-off mechanism.

Failure queue to offload​

How to implement?​

Pros?​

Cons?​

Summary​

TLDR; I'm happy with Gatsby. However NextJS gives me more control as well as more configurations to optimize the blog. The post here describes how I created a blog via NextJS which helped me to improve the speed of the site from 1.8s FCP to 1.6s FCP.

Why NextJS?​

Building a blog, I want it to be performant and blazing fast, and pre-rendered sites seems to be the best option out there. Pre-rendered sites allow browsers to render as early as possible. They then are hydrated to become SPA in order to inherit the smoother navigation any other cool stuff of SPA. Beside that, SEO is much more optimized with pre-rendered HTML sites.

JAMStack is popular due to those benefits. And in the JAMStack + React world, NextJS and GatsbyJS are the best options to pre-render or generate static sites. I chose NextJS for the reason that it allows me to customize for optimization and to learn. As a result, I was able to reduce the FP, FCP from 1.8s using Gatsby to 1.6s using NextJS with the same content & functionalities.

Pre-rendering​

JAMStack doesn't specify what technology it includes. I, therefore, find it better to share some context about pre-rendering and the stack that will be used before we continue.

Simply, pre-rendering is a mechanism where the site is rendered in advance which is different from SPA where browsers evaluate Javascript codes to build the web site at client site. In pre-rendered sites, browsers only need to hydrate it and turn it into a SPA; hence the initial loading time is faster. There are two forms of pre-rendering:

• Static Generation is the mechanism to generate sites in the form of HTML at build time and they will be served statically. Therefore, it can be easily scaled by CDN.
• Server-side rendering is the mechanism to generate sites in the form of HTML on the server side for each request. Therefore, it allows for more personalized content.

NextJS supports both. However, we will use static generation for blogging as we don't need to customize content for each user request.

Build a NextJS blog​

I've been writing via Markdown and I like it. Therefore, this blog will basically be started from a NextJS app with addition of rendering Markdown files.

Create a NextJS app​

Scaffolding a NextJS app is simple:

npm init next-app nextjs-blog
cd nextjs-blog

I select the default starter in the prompt screen so I can understand NextJS more by adding features.

I will starting with routing, NextJS has an opinionated implementation of it. Files in /pages folder will be converted into a route. In the default starter, /pages/index.js and /pages/api/hello.js will be translated into two routes:

• / for /pages/index.js
• /api/hello for /pages/api/hello.js

I don't need /api/hello so I will remove hello.js.

After that, I use yarn dev and head to localhost:3000 to make sure everything works. The website should be up and running at this point.

Render Markdown files​

I'm going to build two types of pages. One index page for listing blog posts and another for showing a blog post.

Page for a post​

First, I create blog/[slug].jsx, so NextJS will generate a route /blog/:slug:

const BlogPost = ({ post }) => {
  return (
    <main>
      <h1>{post.title}</h1>
      <article dangerouslySetInnerHTML={{ __html: post.html }} />
    </main>
  );
};

export default BlogPost;

export const getStaticProps = async ({ params }) => {
  const { getPostBySlug } = await import("../../lib/api");
  const post = await getPostBySlug(params.slug, ["title", "html"]);

  return {
    props: {
      post,
    },
  };
};

export const getStaticPaths = async () => {
  const { getPostSlugs } = await import("../../lib/api");
  const slugs = await getPostSlugs();

  return {
    paths: slugs.map((slug) => {
      return {
        params: {
          slug,
        },
      };
    }),
    fallback: false,
  };
};

Beside the React component BlogPost, I provide 2 exported functions: getStaticProps and getStaticPaths.

• getStaticProps provides props data for the page at build time. Thus, it allows the page to be rendered at build time. In the above example, getStaticProps provides title and html attributes from a markdown file so the page can be rendered.
• getStaticPaths specify the list of routes to be generated at build time. It's only required for dynamic-routed pages. In the above example, getStaticPaths provides an array of slugs which refer to markdown files.

For the implementation of api.js, you can check out this file. It can be implemented by using remark and remark-html to parse the Markdown files.

Page for listing posts​

Creating the listing is very similar. I add blog/index.jsx so NextJS will generate the route /blog for listing posts.

const BlogIndex = ({ posts }) => {
  return (
    <main>
      <ul>
        {posts.map((post) => (
          <li>
            <a href={`/blog/${post.slug}`}>{post.title}</a>
          </li>
        ))}
      </ul>
    </main>
  );
};

export default BlogIndex;

export const getStaticProps = async ({ params }) => {
  const { getAllPosts } = await import("../../lib/api");
  const posts = await getAllPosts(["title", "slug"]);

  return {
    props: {
      posts,
    },
  };
};

getStaticPops here provides the props data for the build time which is the list of posts. I don't need to implement getStaticPaths for this file as the route is not dynamic.

Up until now, I already have basic functionalities of a blog. Next steps, we will discuss optimizations to improve the loading time.

Optimization​

There are two optimizations I would like to implement here:

• Images lazy loading improves the initial loading time.
• Tweaking webpack improves code splitting, hence initial loading time.

Images lazy loading​

The idea of images lazy loading is quite simple. We will put a placeholder in the image first and we only load the full image when it's visible on the screen. In order to generate the placeholder, I use a Webpack loader which is image-trace-loader. The loader will load an image as an object with two fields like:

import { src, trace } from "./image.png";

In it, trace is a svg data and it will be used as the placeholder. src is the original source of the image. My webpack configuration will be like:

config.module.rules.push({
  test: /\.(jpg|jpeg|png|svg|webp|gif|ico)$/,
  use: [
    "image-trace-loader",
    {
      loader: "file-loader",
      options: {
        outputPath: `${options.isServer ? "../" : ""}static/images/`,
        publicPath: "/_next/static/images",
      },
    },
    {
      loader: "image-webpack-loader",
      options: {
        disable: options.dev,
      },
    },
  ],
});

file-loader copies images to static folder and image-webpack-load optimizes images.

However, this is not enough as I need to process the markdown file to modify image components:

const resolve = require.context("../content", true, /\.jpg$/, "lazy");

const remarkImages = (): Attacher => {
  return (): Transformer => {
    return (tree: Node, file: VFile, next) => {
      const nodes: Node[] = [];
      visit(tree, "image", (node: Node) => {
        nodes.push(node);
      });

      Promise.all(
        nodes.map(async (node) => {
          const alt = node.alt ? `alt="${node.alt}"` : "";
          const result = await resolve(<string>node.url);
          const rawHtml = `<img class="lazy" src="${result.trace}" data-src="${result.src}" ${alt}>`;
          node.type = "html";
          node.value = rawHtml;
        }),
      )
        .then(() => next && next(null, tree, file))
        .catch((err) => {
          next && next(err, tree, file);
        });
    };
  };
};

The transformer will add lazy class to images and put the placeholder into src. Meanwhile, the original source is placed under data-src.

Beside, we need some Javascript codes to handle those lazy images after they are mounted. You can take a look at an example below:

React.useEffect(() => {
  const handleRouteChange = () => {
    const lazyImages = [].slice.call(document.querySelectorAll("img.lazy"));

    if ("IntersectionObserver" in window) {
      const lazyImageObserver = new IntersectionObserver(function (entries) {
        entries.forEach(function (entry) {
          if (entry.isIntersecting) {
            const lazyImage = entry.target as HTMLImageElement;
            lazyImage.src = lazyImage.dataset.src as string;
            lazyImage.classList.remove("lazy");
            lazyImageObserver.unobserve(lazyImage);
          }
        });
      });

      lazyImages.forEach(function (lazyImage) {
        lazyImageObserver.observe(lazyImage);
      });
    } else {
      // Possibly fall back to a more compatible method here
      lazyImages.forEach(function (lazyImage: HTMLImageElement) {
        lazyImage.src = lazyImage.dataset.src as string;
        lazyImage.classList.remove("lazy");
      });
    }
  };

  handleRouteChange();
  Router.events.on("routeChangeComplete", handleRouteChange);
  return () => {
    Router.events.off("routeChangeComplete", handleRouteChange);
  };
}, []);

There are few things regarding above codes:

• The code scans all images with the lazy class and utilizes IntersectionObserver api to load images whenever it's on the screen.
• useEffect is used to hook the mounted event and we will process lazy images whenever there is a route change.
• If the api is not available, it fallbacks to the default behaviour which means all images are loaded.
• For convenience, I add the code directly to pages/_app.js so it will impacts all pages.

Tweaking Webpack​

NextJS introduced granular chunking which helps to reduce the size of the initial bundle in most cases. However, in a simple blog, I find it more efficient to pack all common modules into one bundle instead of splitting them. Therefore, I just need to disable that option from NextJS. The change is quite simple:

 {
    experimental: {
      granularChunks: false,
    },
  }

I then use Lighthouse to examine the loading time. Without it, we do not know whether an optimization is effective or not. You can try multiple configurations for the best result.

Summary​

NextJS is not just a simple SSR framework. Instead, it is actually a powerful framework by making things so easy to create a static website with getStaticProps. However, Hot Reload does not work well at the moment due to this issue. I hope that the development team will improve it in the near future.

One more thing, getStaticProps can be called multiple times for a same Markdown file and it can be optimized. I have done it by writing a Webpack loader to load those files to leverage Webpack caching mechanism. Also, Webpack loaders are much more reusable, it helps me save amount of working when playing with other frameworks like NuxtJS.

References​

Last but not least, here are some links for reference if you want to dig deeper:

• Github codes: https://github.com/bongnv/nextjs-blog-example
• Dynamic routes with NextJS: https://nextjs.org/learn/basics/dynamic-routes
• Creating NextJS app: https://nextjs.org/learn/basics/create-nextjs-app
• JAMStack: https://jamstack.org

This is more like a note on how I debloated my Huawei P30 Pro than a technical post. It also worked for Mate 20 so I assume it works for Mate & P series and probably Honor series.

Before we start, please make sure that the device is connected to your laptop/computer. You can run the below command to verify it:

adb devices

It should list your device to the screen. To make the post short, installing ADB or connecting phones to computers would be out of topic here.

After connecting the phone to the laptop, I run this command to list all packages:

	adb shell 'pm list packages -f' | sed -e 's/.*=//' | sort

Reading through that together with this guide, I get some packages to disable. I choose to disable over to uninstall as it allows me to enable packages later if something goes wrong. Here are some commands to disable them:

adb shell pm disable-user --user 0 com.huawei.intelligent
adb shell pm disable-user --user 0 com.huawei.search
adb shell pm disable-user --user 0 com.huawei.hitouch
adb shell pm disable-user --user 0 com.huawei.hicard
adb shell pm disable-user --user 0 com.huawei.browser
adb shell pm disable-user --user 0 com.huawei.hifolder
adb shell pm disable-user --user 0 com.huawei.KoBackup
adb shell pm disable-user --user 0 com.huawei.hiaction
adb shell pm disable-user --user 0 com.huawei.vassistant

You can enable back those packages by using App section in Settings.

A bit off topic, this is for those who also want to get rid of some icons like NFC. I enable NFC all the time, it is redundant to show the icon in the status bar. Luckily, there is a way to do that with Huawei devices:

adb shell settings put secure icon_blacklist nfc,eyes_protect

This command requires a restart to take effect.

A dark theme is a cool feature to have for a website. It was designed to reduce the luminance emitted by device screens and to improve visual ergonomics by reducing eye strain. However, it is perhaps the most complicated part of building my blog. I, therefore, feel that it would be helpful to write down my experience when implementing the feature.

Requirements​

I have been viewing a couple of blogs with dark theme support. The feature can be easily noticed by a switch to turn the dark theme on or off. Some of them even enable the dark theme as soon as I visit the site based on my machine setting. They are also able to store my preference so the website can render the proper theme when I revisit it. Given that, I decided to implement the feature for my blog. It should:

• Have a switch to turn the dark theme on or off.
• Store user preferences so the blog can show properly next time when the user visits.

That sounds simple, right? No, it's not at least for me.

Building layout​

Adding a switch​

This is the easiest part so I started with it first. Thanks to react-feather, I have two cool icons: and . Next, I create a wrapper of them to reuse it in both the desktop navigation menu and the mobile navigation menu:

const DarkModeSwitcher: FC = () => {
  const [darkMode, setDarkMode] = React.useState(false);
  const handleClick = (): void => {
    const newMode = !darkMode;
    setDarkMode(newMode);
  };

  return (
    <button onClick={handleClick}>
      {darkMode ? <Moon className="moon hidden" /> : <Sun className="sun" />}
    </button>
  );
};

export default DarkModeSwitcher;

This simple component uses the function useState which is a React Hook to change the icon back and forth when a user clicks. For the functionality to change the color theme, we will add later.

Adding CSS​

My website uses TailwindCSS which has no support for dark themes out of the box. Therefore, I need to create a CSS file to have different color schemes for light and dark variants. The vars.css would look like:

:root {
  --color-background: theme("colors.gray.100");
  --color-foreground: theme("colors.gray.900");
  --color-primary: theme("colors.indigo.600");
  --color-surface: theme("colors.gray.200");
  --color-inline-surface: theme("colors.gray.300");
  --color-divider: theme("colors.gray.300");
  --color-red: theme("colors.red.700");
  --color-pink: theme("colors.pink.700");
  --color-green: theme("colors.green.700");
  --color-gray: theme("colors.gray.700");
  --color-orange: theme("colors.orange.700");
  --color-blue: theme("colors.blue.700");
  --color-yellow: theme("colors.yellow.700");
}

html[lights-out] {
  --color-background: theme("colors.gray.900");
  --color-foreground: theme("colors.gray.100");
  --color-primary: theme("colors.indigo.400");
  --color-surface: theme("colors.gray.800");
  --color-inline-surface: theme("colors.gray.700");
  --color-divider: theme("colors.gray.700");
  --color-red: theme("colors.red.300");
  --color-pink: theme("colors.pink.300");
  --color-green: theme("colors.green.300");
  --color-gray: theme("colors.gray.300");
  --color-orange: theme("colors.orange.300");
  --color-blue: theme("colors.blue.300");
  --color-yellow: theme("colors.yellow.300");
}

It has a light color scheme by default and a dark color scheme with the attribute lights-out. It means we only need to toggle the HTML attribute to switch from light theme and dark theme. To present the idea in codes, only one line of codes in the function DarkModeSwitcher is needed. It is like below:

const LIGHTS_OUT = "lights-out";

const handleClick = (): void => {
  const newMode = !darkMode;
  document.documentElement.toggleAttribute(LIGHTS_OUT, newMode); // new codes
  setDarkMode(newMode);
};

Having those variables is not enough, we need to use them in our codes. Here is an example of how to use them:

* {
  background-color: var(--color-background);
  color: var(--color-foreground);
}

For those who may wonder, I use the default color palette from TailwindCSS. Also, I use light gray and dark gray instead of white and black to reduce eye strain following this guideline.

Storing user preference​

For storage solution, I use localStorage because of its simplicity. Then there are two problem left which are storing to localStorage and loading from localStorage.

Storing to localStorage​

This is the easier part. I only need to add one line of codes to the function handleClick:

window.localStorage.setItem(LIGHTS_OUT, mode ? "true" : "false");

Every time users click on the switch, we store the preference to localStorage.

Loading from localStorage​

Loading is trickier. Initially, I thought we only need these lines in the component constructor:

const DarkModeSwitcher: FC = () => {
  const storedDarkMode = window.localStorage.getItem(LIGHTS_OUT) === "true"; // new codes
  const [darkMode, setDarkMode] = React.useState(storedDarkMode);
  // other codes
};

Then I realized that gatsby build would fail because window is not available when Gatsby render sites on the server side aka SSR. We could move client-only codes to componentDidMount by using the useEffect hook. However, it would lead to a flickering issue for those we use dark theme because the site is loaded with light theme initially and it changes to dark right after being rendered.

React Context then came into the picture. It allows us to have client-only codes in gatsby-browser.js and sends the data deep down to our DarkModeSwitcher. In detail, I will start with a new Context object to store whether it's in dark mode or not. I add src/context/theme-mode.tsx like:

import React from "react";

const LIGHTS_OUT = "lights-out";

const getInitialDarkMode = (): boolean => {
  const darkMode = window.localStorage.getItem(LIGHTS_OUT);
  return darkMode === "true";
};

const defaultContext = {
  darkMode: false,
  setDarkMode: (_: boolean): void => {},
};

export const ThemeContext = React.createContext(defaultContext);

interface ThemeProviderProps {
  children: React.ReactNode;
}

export const ThemeProvider: React.FC<ThemeProviderProps> = ({
  children,
}: ThemeProviderProps) => {
  const [darkMode, setDarkModeState] = React.useState(getInitialDarkMode());

  const setDarkMode = (mode: boolean): void => {
    setDarkModeState(mode);
    document.documentElement.toggleAttribute(LIGHTS_OUT, mode);
    window.localStorage.setItem(LIGHTS_OUT, mode ? "true" : "false");
  };

  return (
    <ThemeContext.Provider value={{ darkMode, setDarkMode }}>
      {children}
    </ThemeContext.Provider>
  );
};

The Logic is very similar to our DarkModeSwitcher component. However, it introduces getInitialDarkMode to load information from localStorage and it uses that value as the initial state.

As we can get dark mode information from React Context, DarkModeSwitcher becomes simpler:

const DarkModeSwitcher: FC = () => {
  const { darkMode, setDarkMode } = React.useContext(ThemeContext);
  const handleClick = (): void => {
    setDarkMode(!darkMode);
  };

  return (
    <button className="focus:outline-none" onClick={handleClick}>
      {darkMode ? <Moon /> : <Sun />}
    </button>
  );
};

In order for DarkModeSwitcher to load the data from ThemeContext, I need to wrap the application inside the Context Provider which means adding below lines to gatsby-browser.js:

export const wrapRootElement = ({ element }) => (
  <ThemeProvider>{element}</ThemeProvider>
);

wrapRootElement.propTypes = {
  element: PropTypes.node.isRequired,
};

To wrap it up, the website at this stage should have a button to switch from dark theme to light and vice versa. It is also able to store and load user preferences to and from localStorage for next visits.

Flickering on the first load​

Before going into the issue, here is how I tested the Gatsby site before production:

yarn build && yarn serve

Basically, it builds the site with production options and serves it under the default port 9000. Heading to http://localhost:9000, testing around, I found that the site flicker from the light theme to the dark theme on the first load. The reason is that the site was built without user's preferences and its default theme is the light theme. After loading from localStorage, it changes to the dark theme; hence, we see the site changes from the light theme to the dark theme very quickly.

My fix would require some knowledge of Gatsby. The idea is to add a piece of script on top of pre-rendered HTML codes so it is guaranteed to run before rendering the site. The script loads data from localStorage and updates the HTML attribute to ensure the site is rendered with the proper theme. In order to achieve this, I use the API onRenderBody in gatsby-ssr.js. The codes would look like:

export const onRenderBody = ({ setHeadComponents }) => {
  const script = `
  const LIGHTS_OUT = "lights-out";
  const darkMode = window.localStorage.getItem(LIGHTS_OUT) === "true";
  document.documentElement.toggleAttribute(LIGHTS_OUT, darkMode);
  `;
  return setHeadComponents([
    <script
      key={`dark-mode-script`}
      dangerouslySetInnerHTML={{ __html: script }}
    />,
  ]);
};

Until now, the solution is complete. There is a switcher in order to turn the dark mode on and off. And the site is loaded with saved preferences in local storage for next visit. And most importantly, there is no flickering between the light theme and the dark them when users open the site.

Reactive CSS​

The above solution works perfectly; however, I still find it a bit complicated and requires some knowledge on React & Gatsby. It motivated me to look for a simpler approach which is called Reactive CSS. Per my understanding, it means CSS is reactive so instead of maintain a React state, we use CSS to render the switcher:

return (
  <button onClick={handleClick} aria-label="Dark Mode">
    <Moon className="moon" />
    <Sun className="sun" />
  </button>
);

and its style is defined in css file:

html[lights-out] .sun {
  display: none;
}

html[lights-out] .moon {
  display: block;
}

.moon {
  display: none;
}

As a result, Moon icon or Sun icon will be displayed based on whether there is a lights-out attribute in the root html or not. We no longer need ThemeContext nor the api wrapRootElement in gatsby-browser.js. Moreover, DarkModeSwitcher no longer requires an internal state, and it instead loads and updates the html attribute directly:

const DarkModeSwitcher: FC = () => {
  const handleClick = (): void => {
    const newMode = document.documentElement.toggleAttribute(LIGHTS_OUT);
    window.localStorage.setItem(LIGHTS_OUT, newMode ? "true" : "false");
  };
  return <button>/* codes */</button>;
};

Codes now become much shorter, hence, easier to maintain.

Summary​

To summarize, two solutions were described in this post:

• One solution with complicated techniques in React, Gatsby including: useEffect hooks, ThemeContext or wrapRootElement api in gatsby-browser.js.
• Another simpler solution with mostly CSS.

Both require to inject a piece of scripts before the body to select the proper theme for users. And if you want extend it to select the dark mode based on the user's preferred color scheme, you can add these lines:

const mql = window.matchMedia('(prefers-color-scheme: dark)');
const darkMode = mql.matches === true;

For an example of codes for dark themes, you can check out here https://github.com/bongnv/gatsby-dark-theme.

For myself, I learned a lot while implementing the dark theme. I eventually realize that I wouldn't need that knowledge because there is a simpler approach that requires CSS mostly. Such things happen normally, right? We often over-engineering a problem and it's why I believe we should always look for the best solution possible.

I would like to give credit to these posts that helped me to build my dark theme:

• https://joshwcomeau.com/gatsby/dark-mode/
• https://www.gatsbyjs.org/blog/2019-01-31-using-react-context-api-with-gatsby/
• https://github.com/mrcrmn/docc

Enjoy blogging!

Coming from Golang background, writing codes without type is somehow uncomfortable. Therefore, I was looking for TypeScript support in Gatsby to accommodate that and gatsby-plugin-typescript is one of them. However, without core integration, the plugin has a couple of limitations like this issue. Fortunately, Gatsby is recently developing native support for Typescript (link) to allow us to enable TypeScript easier without a plugin.

Create a new site​

Firstly, make sure gatsby-cli is installed or we can use this quick command to install it:

yarn global add gatsby-cli

Then create a new website by the bellowing command and follow the instruction

gatsby new gatsby-site

Just to ensure that the site is created successfully:

cd gatsby-site
gatsby develop

With the above command, Gatsby will start a hot-reloading development environment that is accessible by default at http://localhost:8000.

Add type checking​

You may notice that page-2.tsx is created with the default stater which means TypeScript is natively supported by Gatsby. However, there is still no type checking yet. We will implement it by installing these packages:

yarn add -D typescript @types/node @types/react @types/react-dom @types/react-helmet

Next, we need to add tsconfig.json. My laziness guided me to copy the file from this file in gatsby repo:

{
  "include": ["./src/**/*"],
  "compilerOptions": {
    "target": "esnext",
    "module": "esnext",
    "lib": ["dom", "es2017"],
    // "allowJs": true,
    // "checkJs": true,
    "jsx": "react",
    "strict": true,
    "esModuleInterop": true,
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "noEmit": true,
    "skipLibCheck": true
  }
}

To verify it, I run tsc --noEmit. Sadly, I got this error and the reason is that the gatsby module is not resolved properly:

~/projects/gatsby-site % tsc --noEmit
src/pages/page-2.tsx:3:33 - error TS2307: Cannot find module 'gatsby'.

3 import { PageProps, Link } from "gatsby"
                                  ~~~~~~~~

src/pages/page-2.tsx:5:20 - error TS7016: Could not find a declaration file for module '../components/layout'. '/Users/van.bong/projects/gatsby-site/src/components/layout.js' implicitly has an 'any' type.

5 import Layout from "../components/layout"
                     ~~~~~~~~~~~~~~~~~~~~~~

src/pages/page-2.tsx:6:17 - error TS7016: Could not find a declaration file for module '../components/seo'. '/Users/van.bong/projects/gatsby-site/src/components/seo.js' implicitly has an 'any' type.

6 import SEO from "../components/seo"
                  ~~~~~~~~~~~~~~~~~~~


Found 3 errors.

Checking node_modules/gatsby, it does define types in index.d.ts so the configuration is missing something. Actually, the fix is quite simple, I just add "moduleResolution": "node", to complierOptions in tsconfig.json.

Now, run tsc --noEmit again, gatsby module is resolved but there are some errors with importing layout.js and seo.js. It is totally fine, we will re-write those files in TypeScript.

For convenience, I added a script in package.json like "type-check": "tsc --noEmit", to have yarn type-check command.

Rewrite codes in TypeScript​

Type checking will fail because some components are not declared with types. We can fix it by simply rewriting those files in TypeScript, defining props and declaring types. Let's take seo.js as an example. I first rename the file to seo.tsx for the sake of convention, then adding types for props:

interface SEOProps {
  description?: string;
  lang?: string;
  title: string;
  meta?: Array<any>;
}

And add default values:

const SEO: React.FC<SEOProps> = ({
  description = "",
  lang = "",
  meta = [],
  title,
}) => {
  // some codes here
};

The type error should be gone if we run yarn type-check again.

Summary​

We have added type checking for the Gatsby default starter without any additional plugins thanks to the recent TypeScript support from Gatsby team. For your reference, all the codes are pushed to https://github.com/bongnv/gatsby-typescript-starter.

Furthermore, due to the strong integration with TypeScript, VSCode should work nicely with the project including type checking as well as intellisense.

If your project happens to use eslint, you can add these packages for TypeScript support:

yarn add -D @typescript-eslint/eslint-plugin @typescript-eslint/parser

and you might need to exclude some TypeScript rules from your js files in .eslintrc.js like I did:

{
  overrides: [
    {
      files: ["*.js"],
      rules: {
        "@typescript-eslint/explicit-function-return-type": "off",
      },
    },
  ],
}

Follow this issue for latest updates for TypeScript from Gatsby team and enjoy type checking when creating your great website!

I have been writing a coupe of NPM packages recently and publishing those NPM packages was quite manual and repetitive. Including bumping versions, changelog and Github releases, the amount of manual work will cost plenty of time. It could easily take up to 30 minutes to have a nicely published NPM package. I then googled the problem and found sementic-release. The tool is very handy as it provides a bunch of cool features due to its plugins system.

semantic-release supports CI workflow as well as local workflow; however, I only used it with a local workflow.

Installation​

In order to start using semantic-release, you will need to setup both NPM token as well as Github token in environment variables. I store them in one of my dotfiles for convenience. An example of my .localrc:

export GH_TOKEN=someveryrandomgithubtoken
export NPM_TOKEN=anothersuperrandomnpmtoken

If you not sure how to generate those tokens, semantic-release-cli can help to generate them in few minutes and initialize configurations for a project. I used it in my first project to get tokens and to be familiar with the tool. I then no longer use it as it keeps asking passwords and MFA token which is inconvenient:

yarn global add semantic-release-cli
semantic-release-cli setup

semantic-release-cli basically adds semantic-release as a development dependency and a couple of configs to package.json.

If GH_TOKEN and NPM_TOKEN are configured, it might be faster to add semantic-release manually:

npm install --save-dev semantic-release

I updated scripts in package.json for convenience:

{
  "scripts": {
    "release": "semantic-release"
  }
}

So I only need yarn release to access its commands.

Configurations​

I use release.config.js for storing configurations. By default, the configuration should be like this:

module.exports = {
  plugins: [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/npm",
    "@semantic-release/github",
  ],
};

With the default configurations, semantic-release will analyze commits using Angular conventions to generate release notes. It then publishes to NPM repository and publishes a new release in Github. It also update package.json for the new package version but committing it. Therefore, an additional plugin is required in order to push the change to Github.

As I also want to generate CHANGELOG and commit the change to my repository automatically, I added two more plugins:

yarn add -D @semantic-release/changelog @semantic-release/git

and in release.config.js:

module.exports = {
  plugins: [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/changelog",
    "@semantic-release/npm",
    "@semantic-release/github",
    "@semantic-release/git",
  ],
};

The two new plugins will generate CHANGELOG.md and push it together with package.json to github. You can read more about them in:

• https://github.com/semantic-release/git
• https://github.com/semantic-release/changelog

Release​

After all of those configurations, Release is super simple. After saving your changes to the repository, you can run:

yarn release -d

to review your release notes. After verifying, you can use the following command to publish:

yarn release --no-ci

Then a new version of your package will be published to NPM and Github.

CI​

I didn't set up a CI as one-command release is more than enough for me. If you want to get of your hands free, you can try with Github Actions via this document. Another cool thing about semantic-release is that it can analyze the commit history to decide to change the version accordingly. Basically, everything can be automated.

I was using Gridsome to write this blog from Markdown contents. However, the transformer-remark plugin which transforms a Markdown content to a HTML content doesn't have the functionality to generate an excerpt automatically from the content itself. It requires the excerpt field to be filled manually in front matter. Plus I wanted it so bad that I couldn't wait for the PR to be merged and published to the npm repository. I then decided to create a patch for it so I can have the feature in my own blog as early as possible.

At first, I was thinking of publishing my own package which is a clone of transformer-remark plus the patch. The document is pretty straightforward and I actually used it. However I soon realized that:

• It requires couple of steps to publish to npm.
• We need to maintain the version of the package for new changes.
• It would spam npm with unnecessary content if I keep doing it for every customization.

Later I found out that npm and yarn support to install a package from a git repository. It is so simple that you only need to:

• Patch the change & push it to your own git repository (I would do the same thing for all of my codes).
• Use the npm or yarn command like below to install it:

yarn add https://github.com/bongnv/transformer-remark
// or
npm install https://github.com/bongnv/transformer-remark

As the repository is a public one, any CI should have no problem to install the package from it. You won't need to register for a npm account nor to maintain a version of your package.

It's cool, right? I also happen to learn that beside git repository we can add from a local directory. We can also use yarn link or npm link to link a local fork of the package for testing purpose.

Updated (2020-04-30):

It turned out that vue-router couldn't handle the hash from the URL due to encoding issue and some weird behaviour in their scrolling logic. A more elegant fix is to override the scrollBehavior function in main.js like:

  router.options.scrollBehavior = (to, _from, savedPosition) => {
    if (savedPosition) {
      return savedPosition;
    }

    if (to.hash) {
      return {
        selector: decodeURI(to.hash),
        offset: { x: 0, y: 80 },
      };
    }

    return { x: 0, y: 0 };
  };

With this fix, we can discard all below fixes.

Original:

While I was adding a sidebar for my blog with GridSome, I realized that headings wasn't clickable. It's supposed to move the screen to the heading. I was wondering whether it's a wrong link, so I checked the source codes. However they were generated properly:

<a
  href="#the-issue"
  class="relative flex items-center py-1 text-sm transition transform hover:translate-x-1 font-bold text-primary"
  >The issue</a
>

Clicking #the-issue should scroll the page to that heading.

scrollIntoView doesn't work properly​

After googling, it looks like vue-router doesn't work well with scrollTo and sticky div element (link). And I use sticky for my sidebar. Luckily there is a comment to hack around the issue. A guy suggested to add these lines to use scrollIntoView instead of scrollTo:

router.afterEach((to, from) => {
  document.getElementById("app").scrollIntoView();
});

Thus, I've added these lines to my main.js:

router.afterEach((to) => {
  const id = decodeURI(to.hash).slice(1);
  if (id.length !== 0) {
    const el = document.getElementById(id);
    if (el) {
      el.scrollIntoView();
    }
  }
});

These codes find the element by ID and then scroll the page into it.

Open a link with hash​

The above solution works for most cases except when you open the site via the link with heading anchor for the first time. In order to be able scroll to heading I added:

  mounted() {
    this.$nextTick(() => {
      this.initObserver();
      const id = this.$route.hash.slice(1);
      if (id.length !== 0) {
        const el = document.getElementById(id);
        if (el) {
          el.scrollIntoView();
        }
      }
    });
  },

anchor with Vietnamese headings​

You may wonder why that I uses decodeURI to get the decoded heading anchor. By vue-router's implementation, hash param in the url is encoded for URI safe. Therefore, it has to be decoded to allow getElementById find the element properly.

TLDR; This article guides you not only how to create your blog but also how to continuously deploy with Github Actions. Even you are completely new to static site generators, it is very easy to get started with.

Why VuePress?​

When it comes to blogging, there are millions of ways to create one. So why did I choose VuePress?

Frankly, there was no particular reason for me to start with VuePress over other static site generators like Gatsby or Hugo. It's mainly because of that I was learning VueJS. After using it, I would say VuePress is worth trying. Like VueJS, its tooling is friendly and the documentation is awesome.

Getting started with VuePress​

Installation​

Let's start with installing vuepress and the blog theme @vuepress/theme-blog:

mkdir my-blog && cd my-blog
yarn add vuepress @vuepress/theme-blog -D

• vuepress is a minimalistic static site generator.
• @vuepress/theme-blog provides blog plugin as well as the default blog theme for VuePress.

Configuration​

VuePress configuration file is .vuepress/config.js. Its parameters are well documented here. However, for the sake of simplicity, we begin with:

module.exports = {
  title: "My blog",
  description: "This is another blog.",
};

VuePress also provides some commands to make things easy:

• vuepress dev starts the blog locally for testing & debugging
• vuepress build generates static sites in .vuepress/dist for deployment

I'll add them to package.json for convenience:

{
  ...
  "scripts": {
    ...
    "dev": "vuepress dev", // starts a development server with automatic reload.
    "build": "vuepress build" // builds your website.
  }
}

You can check more commands in its documentation.

Cool, now you can run yarn dev and head to localhost:8080 to see your blog!

You should see the 404 page as there is no content yet.

Home page​

VuePress uses Markdown for preparing content. For example, README.md will automatically be converted into index.html. I'll add these few lines to README.md as an example for the home page:

---
title: About
---
<h1> Hi world! </h1>

This is my blog.

The section between --- at the beginning of the Markdown file is called Frontmatter. There are other parameters like date or tags.

Theming​

The default theme looks pretty and it works well for me. I'm going to use it for this blog which is @vuepress/blog. Applying a theme is as simple as one line change in config.js:

module.exports = {
  ...
  theme: "@vuepress/blog" // @vuepress/theme-blog also works
}

You can find more themes from here.

Blog posts​

Conventions is the key, blog posts will be placed inside _posts and we will have the following directories structure:

my-blog
├── _posts
│   └── 2020-04-29-hello-world.md
├── .vuepress
│   └── config.js
├── README.md
└── package.json

No one would stop you from having your own structure; however you will need to experiment it on your own. I'm starting the very first entry for this blog:

---
title: The first entry
date: 2020-04-29
---
This is my first blog entry.

VuePress then will generate the post in localhost:8080/post/2020/04/29/hello-world.html and the index page in localhost:8080/.

Ops, my home page is overriden!

No problem, we can move the index page to a different path (/posts/) by adding these lines to config.js:

module.exports = {
  ...
  themeConfig: {
    directories: [
      {
        // Unique ID of current classification
        id: "post",
        // Target directory
        dirname: "_posts",
        // Path of the `entry page` (or `list page`)
        path: "/posts/",
      }
    ],
    nav: [
      {
        text: "Blog",
        link: "/posts/",
      },
    ],
  }
}

• directories allows to configure document classifiers. So you can add writing or photography there.
• nav is for the navigation bar. I prefer simplicity so Blog is enough for me.

Deployment with Github Actions​

Deployment​

Thanks to Github, CD (aka continuous delivery) is now a no-brainer task. Everything you need is just to create .github/workflows/deploy.yml with these lines:

name: Deploy
on:
  push:
    branches:
      - master
jobs:
  build-and-deploy:
    name: Build and Deploy
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v2

      - name: Install and Build
        run: yarn && yarn build

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: .vuepress/dist

And push it to your repository, mine is https://github.com/bongnv/my-blog. Deployment will be triggered for every push to master.

Don't forget to add .gitignore to exclude some generated files from your repository. Your commands should be like:

echo "node_modules" >> .gitignore
echo "dist" >> .gitignore
git init
git add .
git commit -m "first commit"
git remote add origin [email protected]:bongnv/my-blog.git
git push -u origin master

Base path​

In my case, the blog URL is https://bongnv.github.io/my-blog. However, it shows 404 because the base path by default is root (/). Adding this line to config.js will make it work:

module.exports = {
  ...
  base: "/my-blog/"
}

Your local blog will become localhost:8080/my-blog instead.

Summary​

Those are simplified steps to blog with VuePress, it should give you a simple blog to start writing. There are many things to explore deeper like Vue components inside Markdown, the plugins system. You could check out:

• The official blog plugin
• VuePress documentation
• Awesome VuePress

Today, I have just found this way to share my html document in the fastest way. Honestly, it's pretty fun to serve a http static server in your current directory by only one line of code. Here is what I used:

Python 2.x:

$ python -m SimpleHTTPServer 8080

Note that the server will be available at http://localhost:8080.

Want more? Click here