DEV Community: Kevin

Building and deploying Gatsby sites with GitHub actions

Kevin — Tue, 15 Oct 2019 06:15:40 +0000

GitHub actions are currently in beta and I was one of the lucky folks to get beta access. For various reasons I've decided to switch the entire build process of my blog to GitHub actions - let's talk about the why and how to build and deploy Gatsby sites with actions.

Why tho?

In case you're just interested in the actual guide you can skip this section - but I'd like to explain why overhauling my build process - and this post - were never planned and why they were still mandatory.

There hasn't been a new post for more than month now. But not because I didn't write any new posts - in fact I even released some new posts - they just never saw the light of the world. What?!

Unlike many Gatsby sites I'm not hosted on Netlify, GitHub Pages or any other hosting option described in the official docs. My blog and all associated tools (commenting system, newsletter, etc.) are hosted on Uberspace. I really like them, due to their great support, a great pricing model which may can be adopted to your budget and the fact that I can access the server with SSH and can do a lot of stuff by myself. There's no fancy interface in terms of controlling your server, most things are done on your console - and I love it.

When I switched to Gatsby some work was required in terms of being able to rebuild my blog automatically whenever I publish a new post. This work included a webhook which triggered a simple shell script which rebuild and deployed my site everytime it was called. The shell script responsible for building and deploying the site was pretty simple:

#!/bin/bash

set -o errexit

cd ~/blog
rm -rf .cache

if ["$1" == "fully"]; then
  rm -rf node_modules
  git pull
  ~/.yarn/bin/yarn install --production=true --pure-lockfile
fi

~/bin/gatsby build
rm -rf ~/blog_backup
cp -R <path>/html ~/blog_backup
rsync -avu --delete ~/blog/public/ ~/html

Sometimes (mostly when adding new features) I needed to fully rebuild the blog, including getting the new source files from Git and installing new dependencies. Since this took a pretty long time it was optional and could be triggered via the optional fully parameter when executing the script.

This script was part of a chain of scripts which were executed whenever the webhook was called. The webhook itself called a script which piped the output of script above into a file which gets send me a mail whenever it's done. This way I could easily check if everything worked whenever a rebuild was triggered.

It's no fancy solution with live console outputs and things like that - but it work...ed.

The problem

One week after my post about tmux I wanted to release a new post. Most of the time it took around ten minutes after I hit the "Publish" button that the webhook is done and I get the mail which tells me that everything worked out well and my blog has been updated with the latest post.

Not this time.

After nearly an hour and still no mail I sshd into my server and checked what happened. The output of the last build was:

[<user>@<server> blog]$ ~/bin/gatsby build
success open and validate gatsby-configs - 1.622 s
success load plugins - 22.156 s
success onPreInit - 0.018 s
success delete html and css files from previous builds - 0.261 s
success initialize cache - 0.020 s
success copy gatsby files - 0.575 s
success onPreBootstrap - 0.098 s
success source and transform nodes - 0.861 s
success building schema - 1.085 s
success createPages - 0.284 s
success createPagesStatefully - 0.146 s
success onPreExtractQueries - 0.012 s
success update schema - 0.037 s
success extract queries from components - 0.432 s
success write out requires - 0.007 s
success write out redirect data - 0.003 s
success Build manifest and related icons - 0.921 s
success onPostBootstrap - 1.478 s
⠀
info bootstrap finished - 92.619 s
⠀
success run static queries - 0.036 s — 3/3 101.33 queries/second
⠼ Building production JavaScript and CSS bundles
Killed

Killed? I'm sorry, little one.

After some research I found out that Uberpsace kills processes which take more than 1.5 GB memory. Additional researched revealed that my build process takes up to 1.7 GB of memory at this point - which was the reason for it to get killed.

I contacted the Uberspace support and they suggested to use the --max-old-space-size=1024 flag to prevent Node from taking too much memory - but sadly that didn't work out. I get the point of a hoster being unable to provide an unending source of memory - but that was indeed a major issue; I couldn't change anything on my blog at this point.

I had to rethink my entire build process. I looked up different options like AWS, GitHub pages or even building locally and deploying via a container - but all of them had some downsides I wasn't comfortable with.

At some point I thought of using GitHub actions for building and deploying my blog to Uberspace. This would provide 2000 minutes of build time per month with up to 7 GB of RAM memory - that should definitely do the job.

After some work it was finally done: my blog is now built (and tested) on GitHub via actions and finally deployed to my Uberspace which means I can now return to writing content again. Hooray!

GitHub action

My GitHub action consists of a multi-step job which does everything from checkout out the repository to deploying the built site via Docker and rsnyc.

Let's take a look at the workflow (located in .github/workflows/workflow.yml):

name: Update blog

on: [push, repository_dispatch]

jobs:
  update:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v1

      - name: Set Node.js
        uses: actions/setup-node@master
        with:
          node-version: 10.x

      - name: Install dependencies
        run: yarn install --prod --pure-lockfile

      - name: Lint
        run: yarn run lint

      - name: Build
        run: yarn run build
        env:
          GHOST_API_URL: "https://ghost.nehalist.io"
          GHOST_CONTENT_API_KEY: ${{ secrets.ghost_content_api_key }}
          GATSBY_ENV: "prod"
          GATSBY_CARRAWAY_URL: "https://carraway.nehalist.io"
          GATSBY_COMMENTO_URL: "http://comments.nehalist.io"
          GA_TRACKING_ID: "UA-40873708-1"

      - name: Deploy
        run: docker-compose run deploy
        env:
          DEPLOY_KEY: ${{ secrets.deploy_key }}

The steps are fairly simple:

check out the repository
setup node at version 10.x
install dependencies via yarn
lint all files
build the site
deploy it via a custom container

The on keyword specifies whenever our action is triggered - in this case it's triggered on push and on repository_dispatch.

repository_dispatch may not be obvious at first glance; but it's for being able to call it externally (like an URL). This will become important for whenever a new post is published this webhook is called which will send a cURL request to GitHub and triggering the repository_dispatch event.

Important : The repository_dispatch is only triggered on the the master branch (which is not mentioned in the docs). Acquiring this knowledge took a serious amount of my lifetime.

The more interesting things are happening within the Build and Deploy step. But before taking a closer look at how they work let's briefly talk about secrets within actions.

Secrets

Secrets, like your SSH key or your API key, should never be stored within your repository. Instead you can use repository secrets (located in your repository settings in "Secrets").

These secrets will not be printed within your console output of your actions and are not readable by users at all once added. This is especially important when it comes to deploying via rsync: we're going to use a SSH key to access the server, hence it would be really bad if someone gets access to this secret.

There's no excuse not use secrets for things like this; even if your site is within a private repository where you're the only one to have access to like mine.

Building the site

Let's take a closer look at the building step:

      - name: Build
        run: yarn run build
        env:
          GHOST_API_URL: "https://ghost.nehalist.io"
          GHOST_CONTENT_API_KEY: ${{ secrets.ghost_content_api_key }}
          GATSBY_ENV: "prod"
          GATSBY_CARRAWAY_URL: "https://carraway.nehalist.io"
          GATSBY_COMMENTO_URL: "https://comments.nehalist.io"
          GA_TRACKING_ID: "UA-40873708-1"

My site uses a bunch of environment variables (via process.env.<variable>) - since I use different sources for prod and dev environment - which can easily be set via the env key within a workflow step.

To access secrets within env variables you can simply use ${{ secrets.<your-secret> }}.

Deploying the site

The more interesting part is how the site is deployed. Our step within our workflow is pretty simple:

      - name: Deploy
        run: docker-compose run deploy
        if: github.ref == 'refs/heads/master'
        env:
          DEPLOY_KEY: ${{ secrets.deploy_key }}

This step is only executed when we're on master

But as you can see within the run key we're not just calling a simple command but use docker-compose to run our very own docker container to deploy. So let's break that down to see what's going on here!

You might want to get rid of the if clause and deploy different refs to different locations; but this would definitely gone beyond the scope of this post.

Docker

The first thing we need to take a look at is our docker-compose.yml file:

version: '3'

services:
  deploy:
    image: "instrumentisto/rsync-ssh"
    volumes:
      - .:/home/site
    working_dir: /home/site
    environment:
      deploy_key: $DEPLOY_KEY
    command: sh scripts/deploy.sh

You can probably do all the docker things without docker-compose - but I'm used to it and basically always using docker with Docker Compose.

The image we're going to use for our deployment is instrumentisto/rsync-ssh which provides a small container with rsync installed.

In case you don't know rsync: it basically just synchronizes files. In our case: it syncs the public directory from our built Gatsby site on GitHub to our very own server where the site will be hosted.

The volumes and working_dir are just where our site will be mounted within the container.

The more interesting part at this point are environment and command. The used environment variables come from GitHub itself where deploy_key is what we got from our workflow.yml. Before taking a look at the script called within command let's talk about SSH keys.

SSH Keys

As mentioned earlier we're going to make use of SSH keys for deployment.

What we're going to do is to generate an SSH key pair (consisting of private and public) key. The public key will be added to our server, while the private key will be used within our docker container for rsync. Since we never want to reveal the private key to someone we're going to use GitHub secrets for this.

Let's start with generating our keys:

ssh-keygen -t rsa -b 4096 -C "<your mail>"

This will generate a public and private ssh key. Since these keys won't be used directly by you (and gets deleted after we're done) it might be useful to put them somewhere else than your default SSH directory to prevent messing up with your existing SSH keys.

If everything worked out you should have two files: id_rsa and id_rsa.pub (or whatever you've called them). id_rsa is your private key, id_rsa.pub is your public key. First let's add your the public key to our server;

Copy the content of your public key, id_rsa.pub, file (e.g. via xclip -sel clip id_rsa.pub) and add it to your servers authorized_keys file (which - in my case - is located in /home/$USER/.ssh).

Afterwards copy the content of your private key, id_rsa, to your GitHub secrets.

This key will be used within the Docker container to access your server.

Deploy script

The last file we need to take a look at is the deploy.sh file which is called by our Docker container within our workflow:

#!/bin/sh

# Instantly exists our script whenever an error occurs
set -e

# Pipe our environmental SSH key variable into a file
mkdir -p $HOME/.ssh
echo "${deploy_key}" > $HOME/.ssh/deploy_key
chmod 600 $HOME/.ssh/deploy_key # SSH keys need to be readonly

# Where to deploy our site on our server
target="~/html"

# The actual rsync
sh -c "rsync -azh -e 'ssh -i $HOME/.ssh/deploy_key -o StrictHostKeyChecking=no' public/* --rsync-path='mkdir -p ${target} && rsync' <user>@<server>:${target}"

# Remove our deploy_key again since it's no longer needed
rm $HOME/.ssh/deploy_key

The rsync command might seem a bit wild at first;

-azh is for using archive mode (-a), compress data during transfer (-z), preserve hard links (-h). See here for all arguments.
-e is for setting up the ssh command (to use our deploy_key and to not do strict host key checking which would prompt us if we're going to trust the server).
--rsync-path is a neat little trick to create missing parent directories (see this post).

Now every time your GitHub action is executed your blog is directly deployed to your hoster. One last thing we're still missing is creating a webhook to trigger our action whenever a new post is published.

Triggering the action from outside

Triggering the action from outside is actually done by making use of the repository_dispatch event.

Don't forget: the repository_dispatch event only works on the master branch!

The easiest way to trigger the action is by cURL:

curl -v -X POST -u "<username>:<access-token>" -H "Accept: application/vnd.github.everest-preview+json" -H "Content-Type: application/json" --data '{"event_type":"update"}' https://api.github.com/repos/<username>/<repo-name>/dispatches

If - and you definitely should - you're using two factor authentication you're going to need a personal access token with repo permissions.

Calling this command will trigger our action and our site to be rebuilt and deployed.

If you're using Ghost you can't just execute cURL commands after a post is published - but instead send a POST request to a user defined URL. In this case it's pretty simple to write a very small PHP script which executes the cURL command and triggers the action;

<?php

$key = $_GET['key'];

if ($key !== 'f4aOLlmN3') {
    exit('Nope.');
}

$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://api.github.com/repos/<username>/<repository>/dispatches');
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($curl, CURLOPT_HTTPHEADER, [
    'Authorization: token <access-token>',
    'Accept: application/vnd.github.everest-preview+json',
    'User-Agent: <username>',
]);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode([
    'event_type' => 'update'
]));

$content = curl_exec($curl);
curl_close($curl);

// we could var_dump($content) here or whatever

Don't forget to replace all placeholders within this script

The first thing you've probably noticed is the $key part; this is just to prevent that the hook can be triggered by anyone. It's very simple way of protecting your script. This script can only be called via webhook.php?key=f4aOLlmN3 - everything else will not trigger the action.

Everything else is basic PHP cURL insanity. The header includes your access token and sets the User-Agent to your username which is required by GitHub.

Now you can setup your CMS to send a request to this script (don't forget the key in the URL!) and your action will be triggered.

Conclusion

If everything is configured properly your site now gets build on GitHub and is deployed to your server afterwards. This is fancy and cool, isn't it?!

Since GitHub actions are still in beta things might change in the future - but the basic concept of this post should always work and should give way more room in terms of building capacities.

If you liked this post feel free to leave a ❤, follow me on Twitter and subscribe to my newsletter. This post was originally published at nehalist.io.

Adding Commento to React Apps (like Gatsby)

Kevin — Mon, 02 Sep 2019 06:10:06 +0000

Since I've recently replaced Disqus with Commento I thought it'd be a good idea to share how to embed a different commenting system - in our case Commento - into your Gatsby site (or React app in general).

Zero dependency component

Disqus has an official package for embedding it into React applications which I used to add Disqus to my blog. For Commento I wanted to get rid of the additional dependency; additional dependencies increase maintenance and always come with a certain amount of risk. It's not that relying on open source is a bad idea - it's just that sometimes adding a package for small things is just excessive exaggeration and not worth the price.

So I've implemented a very small component myself which is responsible for embedding Commento with less than 40 lines of code.

Since most commenting systems work the same way (by embedding a simple JavaScript file into your page) this approach should work for other systems like Isso, Schnack, Remark42, etc. too (with small adjustments).

It's a functional component which makes use of the useEffect hook to embed Commento on the desired pages. Additionally it uses two helper functions (borrowed from disqus-react) to add and remove scripts from our page.

The entire implementation is fairly easy:

import React, {useEffect} from 'react';

// Helper to add scripts to our page
const insertScript = (src, id, parentElement) => {
  const script = window.document.createElement('script');
  script.async = true;
  script.src = src;
  script.id = id;
  parentElement.appendChild(script);

  return script;
};

// Helper to remove scripts from our page
const removeScript = (id, parentElement) => {
  const script = window.document.getElementById(id);
  if (script) {
    parentElement.removeChild(script);
  }
};

// The actual component
const Commento = ({id}) => {
  useEffect(() => {
    // If there's no window there's nothing to do for us
    if (! window) {
      return;
    }
    const document = window.document;
    // In case our #commento container exists we can add our commento script
    if (document.getElementById('commento')) {
      insertScript(`<your commento url>/js/commento.js`, `commento-script`, document.body);
    }

    // Cleanup; remove the script from the page
    return () => removeScript(`commento-script`, document.body);
  }, [id]);

  return <div id={`commento`} />
};

export default Commento;

Don't forget to replace your commento url with the proper URL.

Done. That was easy.

The Commento script gets added to our page as soon as the associated container (which id equals commento) is found and is re-rendered as soon as the id prop (which should be the post or page id) changes (see optimizing performance by skipping effects for further information).

We can now add comments to all pages by simply adding the <Commento id={uniquePostId} /> component to wherever we want to have comments.

If you liked this post feel free to leave a ❤, follow me on Twitter and subscribe to my newsletter. This post was originally published at nehalist.io on September 2, 2019.

Software development blogging: analytics, revenue, content and more

Kevin — Tue, 20 Aug 2019 13:10:10 +0000

My blog is online for four years this summer - time to share some numbers and thoughts about it.

Preface

Before diving right into numbers we need to keep some things in mind:

I've neglected my blog multiple times. That's something I'm not proud of - but it's important to know for this post. In four years I've only published around 50 posts.
This post will only be about the nehalist.io domain which was registered in September 2014.

This post should give you an insight in "how my blog is doing in terms of being programming blog".

Analytics

Let's start with some numbers from my Analytics account. So far my blog has attracted nearly 600.000 users and generated almost 1 million pageviews.

High bounce rates are pretty normal for a blog which mainly provide guides. People search for a problem, find the blog post, read the post and leave.

Site content

The fact that my most popular content are guides is not really surprising - my guides about uploading files in Angular and working with models in Angular generate around 40% of my entire traffic.

These two guides (both published in September 2017) were the first posts that really lifted up my numbers; while being at around 20 to 50 visits per day before publishing them I went to more than a hundred visits per day after Google has done its magic and indexed the posts.

It's wasn't pure luck that these posts took off; I had to deal with the problems described in these posts back then and didn't found a neat solution to neither of them online. Knowing that there's no resources on a specific topic really helped these posts to attract many visitors.

Acquisition

Stats taken for July 2018 to July 2019

Knowing how people come to your blog is a pretty important factor. In my case - where most of my posts are guides which help people with specific problems - it's no wonder that most of my traffic comes from organic search:

Ad revenue

An easy way to get money out of your blog is to run ads. In my case I wanted to cover the expenses required for this blog (around 30 bucks per month).

AdSense

I ran AdSense from October 2018 until July 2019. During that time I had approx. 300.000 page views which generated ~430€:

On average I earned nearly 50€ per month this way.

Carbon Ads

With my redesign released in July 2019 I switched to Carbon Ads.

As shown in the image I've earned 45 bucks so far with Carbon (within nearly 2 months).

You might wonder why the average revenue decreased since I've switched to Carbon; but it's important to keep in mind that I was way more aggressive with AdSense. I ran in-article ads, in-feed ads and one ad in the sidebar while, since I've switched to Carbon, I'm running only one ad per page.

AdSense or Carbon Ads?

Ultimately this section leads to one question: should you use AdSense or Carbon Ads?

Getting approved for AdSense is definitely easier, since Carbon Ads is invite-only. Everything else depends on what you're looking for:

AdSense allows for greater revenue due to the fact of having multiple ads on your page.
Carbon Ads look decent. It's not that typical "LOOK AT ME, I'M AN AD!!" appearance - it's a discreet look which doesn't bother the reader at all.
Carbon Ads are target at designers and developers.

Since I run ads to cover my blog expenses I could definitely live with a few bucks less every month. In return I've increased readers experience a lot and ads shown are targeted specifically to the people who read my blog - and I guess that's a fair trade.

Content

One of the biggest challenges I face on my blog is creating proper content. Does anyone care about how create a reading progress bar in React? Is anyone interested in the numbers shown in this post? Does the world need another post about optimizing TypeScript applications?

These questions went constantly through my head - and still do. But for me personally I found an easy answer: as long as I enjoy writing these things and they do fit in the scheme of my blog (which is tech / programming related-stuff) they're totally fine to write.

Some posts, like my post about Dependency Injection in TypeScript was written because I had absolutely no idea what to write that day. And even after I published it I was certain: no one would care about how DI works under the hood. I enjoyed creating it but I didn't think that anyone would care about such a topic. But guess what? That's the 5th most read post on my blog.

On the other hand my post about Selenium testing was the opposite: I was sure that this post is the next big post which generates at least the traffic my Angular posts do. Some days after publishing I realized: well, that's not the case. It's gotten little to no feedback and it's read very rarely until this very day.

But, for me, the point is: it doesn't matter that much. I enjoyed writing them.

I liked to get a better understanding of these things - no matter how "well" the post did. And that's, at least for me, the point of blogging: as long as you enjoy what you do there's nothing bad about it - even if your post might not generate the numbers you expect.

The only rule I try to follow when it comes to content is:

You're writing for your readers, not yourself.

I could probably write a lot about my car, my cat, my most recent holiday, etc. - but that's not the point of this blog. People come here to read about tech - so that's what I want to deliver.

Finding topics

Some time ago I had a hard time to find proper topics to write about.

If you've got an idea to write about the first thing you're likely going to do is to research the topic. Often times I find many results dealing with the same topic that I question myself "is it really worth writing about?". But the answer is quite simple: everyone's got their own style, every programmer knows different things - even though they may partially overlap when it comes to their content. I like to think of this in a pretty simple way: many things out there are unique in the way they're conveyed, not in what they are. Facebook was created after social networks already existed, Fortnite established while PUBG was already the alpha battle royale with insane numbers, Vue was created after React and so on. Often times things that come later aren't worse, they're sometimes even better because you may profit from the earlier acquired knowledge.

Your next post probably won't be the next multi billion dollar thing - but I guess you get the point; just because there's a post about a topic shouldn't prevent you from writing about the same topic. Flavored with your own knowledge and writing style your post will still be unique.

Another thing which helps me a lot is maintaining a content idea list. Everytime my brain has an idea I write it down - this way I come to 2 - 3 ideas per day. Some of them might never become a post - but whenever I want to write a post and have no idea at that moment I can just take a look at my smart list and pick a topic.

Content distribution

Writing is pretty much worthless without being read.

Somehow people need to get informed that you've done a thing. I've settled down with immediately sharing my posts on Twitter.

Some posts (mostly guides) are also shared on Reddit. Sharing on Reddit is a great way of getting readers - but also has to be taken with care. Reddit has tight restrictions on self-promotion - so don't exaggerate or you'll get banned.

If you want to share your posts on Reddit while considering a "good time to share" take a look at Later for Reddit which tells you when posting is more likely to get attention.

Posts I really think are worthy are shared on Hacker News. So far none of my posts have made it to the front page and were lost on page 2+ within a few minutes. It's really hard to make it there - but in case you're able to do it your traffic is likely to explode.

I only crosspost my content on Medium. The main reason for this is that I've been invited to two big publications where I reach more readers for every post. Crossposts are not posted immediately after publishing the initial post and instead are released one or two days later to keep the momentum of the post for at least some days.

(Obviously I'm also crossposting on dev.to too; but this post was written before that)

Conclusion

If you think about starting a programming blog you need to keep some things in mind:

if you mainly post guides to specific problems it's likely that your bounce rates will be pretty high.
write what you enjoy and want to write about (while keeping your readers in mind)
having a content distribution strategy definitely helps in reaching more people and growing your brand.
ads may cover the expenses of your blog - but it's unlikely to get rich just from ads (except you have an insane amount of visitors every day). If you want to make money from your programming blog it might be more financially profitable to create paid courses or offer some kind of software-as-a-service.
don't think too much about if something is worthy writing about. There'll be posts which will receive a more positive feedback, while others are barely noticed. Some posts will be better than others. Maybe this one is better - maybe it's not. If you've enjoyed creating them and maybe even learned something everything's fine.

If you liked this post feel free to leave a ❤, follow me on Twitter and subscribe to my newsletter. This post was originally published at nehalist.io on August 13, 2019.

Software Spotlight: Husky, git hooks made easy

Kevin — Tue, 13 Aug 2019 06:35:27 +0000

I stumble upon great open source libraries or tools nearly every day - some of them having thousands of stars of GitHub and I've still never heard of them. I guess the fact that there are more than 100 million repositories just on GitHub somehow explains that.

Nevertheless, I've always liked to do some kind of series on my blog - and I guess showing some of my findings is a pretty good way to do so - especially since some of them have become an important element of my very own workflow.

So here's the first (of hopefully many!) software spotlight, featuring Husky by typicode, an open source library to ease the process of creating git hooks.

Husky, Git hooks made easy

Husky is a simple tool which makes it possible to easily create git hooks in your package.json.

Repository
More than 15.000 stars on GitHub
Used by more than 160.000 repositories on GitHub (e.g. by webpack, babel, Next.js, create-react-app, ...)
More than 1.5 million downloads per week

What it does

Instead of manually creating git hooks within your .git directory Husky allows you to simply add your hooks within your package.json, e.g.:

{
  ...,
  "husky": {
    "hooks": {
      "pre-push": "npm test"
    }
  }
}

This would execute npm test before every git push and if npm test fails the push will not be executed.

Sometimes you might want to skip hooks (e.g. when working on a WIP branch) - this can easily be done by adding the --no-verify flag to your git command.

Hooks created by Husky are removed when Husky is uninstalled.

How it works

Under the hood Husky just creates normal git hooks when it's installed. If you take a look at in your .git/hooks/pre-pull for example you'll find a generated file by Husky:

#!/bin/sh
# husky

# Hook created by Husky
# Version: 3.0.1
# At: 8/2/2019, 9:53:34 AM
# See: https://github.com/typicode/husky#readme

# From
# Directory: /<your-project>/node_modules/husky
# Homepage: https://github.com/typicode/husky#readme

scriptPath="node_modules/husky/run.js"
hookName=`basename "$0"`
gitParams="$*"

[...]

This generated files are responsible for executing proper hooks (in this case: pre-push) for the executed command (in this case: git push).

As mentioned above these files are removed when Husky is removed.

Why to use it

One could say that a proper CI setup would probably do the same as Husky - which I partially agree with. But there's one thing which lead us (which means the company I work for) to use Husky, even if our CI setup runs all tests, linting and related stuff: our CI takes a pretty long time to get done. One build takes between 30 and 60 minutes - and you don't want to wait that long to get a notification which tells you essentially:

Your build failed because you've forgotten a space. Noob.

Our pre-push hook just runs npm run lint (which lints all .ts and .scss files) to prevent exactly such cases. npm test takes a bit too much time for a git hook which is why we've gone just for the linting.

An additional advantage is that it makes it very easy to share git hooks within your team without having to change any git configuration.

5 TypeScript tips to improve your architecture

Kevin — Tue, 06 Aug 2019 06:19:48 +0000

Even though I work pretty much everyday with TypeScript there's something new I learn about frequently. I really enjoy working with it and try to get the most out of it whenever possible - and there's one thing for sure: TypeScript can do a lot of things.

So here are some things I've learned through time which helped me to improve my applications and - ultimately - become a better TypeScript developer.

Utility types

TypeScript provides some useful types right out of the box - they're called utility types and can be found here.

One of my personal favorites is the Readonly<T> type makes all properties of T readonly, making it easy to help you to maintain immutability.

Another handy type is Required<T> which makes all properties required.

There's even more with things like Pick<T, K> which creates a type of picked properties from another type, NonNullable<T> which removes null and undefined from properties, Exclude<T, U> which removes properties from a type and even more - go check them out, they're really useful.

Use unknown instead of any

A lot of times if you don't have exact type information you might just go for any. And that was actually totally fine - until TypeScript 3.0 introduced the new unknown type, the "type-safe counterpart of any" (as described by TypeScript).

Just like the any type you can assign whatever you want to the unknown type - but you can't do _any_thing with it like the any type allows for:

const imUnknown: unknown = "hello there";
const imAny: any = "hello there";

imUnknown.toUpperCase(); // error: object is of type "unknown"
imAny.toUpperCase(); // totally fine

Hence unknown prevents calling any method on it due to its unknown nature. Additionally assigning unknown types to other types is not possible either:

let a: unknown = "hello world";
let b: string;

b = a; // error: a is unknown hence it's not possible to assign it to `string`

Often times the variable you just declared any is actually unknown - which prevents faulty assignments or calling methods on it without knowing what methods are provided by it.

See here for further information regarding the unknown type.

Lookup types

Lookup types are a neat way to help you finding what you're looking for. Let's assume you've got an object with a dynamic number of properties and want to get a specific property out of it - it's highly likely to do it the following way:

const persons = {
  john: { surname: 'Doe' },
  bob: { surname: 'The builder' }
};

persons.john; // equals { surname: 'Doe' }

But there's one problem: what if the john property does not exist? Your application is likely to tragically die - but that could have been prevented by TypeScript!

By implementing a very small helper we're able to prevent this:

function getProperty<T, K extends keyof T>(obj: T, key: K) {
    return obj[key]; // Inferred type is T[K]
}

By using this helper we can assure that the property exists when using it:

function getProperty<T, K extends keyof T>(obj: T, key: K) {
    return obj[key]; // Inferred type is T[K]
}

const persons = {
    john: { surname: 'Doe' },
    bob: { surname: 'The builder' }
};

getProperty(persons, 'bob');
getProperty(persons, 'john');
getProperty(persons, 'someoneelse'); // Error: Argument of type "someonelse" is not assignable to parameter of type "bob" | "john"

It may be common to take use of that within classes which makes the obj param obsolete. It might be implemented as a getter for getting a specific item where we want to know which elements are available. In this case we're going to use a fairly uncommon syntax which:

class PersonList {
  persons = {
    john: { surname: 'Doe' },
    bob: { surname: 'The Builder' }
  }

  getPerson(name: keyof PersonList['persons']) {
    return this.persons[name];
  }
}

keyof PersonList['persons'] is something you probably don't see everyday.

Which would cause calling personList.getPerson('john') to be perfectly fine, while personList.getPerson('jane') would fail since there's no jane key available.

Extending third-party libraries

If you've ever wanted to extend a third party library but were limited by the public API of that library module augmentation is what you're looking for. But when do you want that?

Let's say we've got an Angular application and we want to name our routes. The Angular Route interface doesn't provide a name property by default - that's were module augmentation comes in handy.

By creating a typings.d.ts in the root of our Angular project we can simply tell TypeScript that we want to have an additional, optional property which stores the name:

import {Route} from '@angular/router';

declare module '@angular/router' {
  interface Route {
    name?: string;
  }
}

It's important to import from @angular/router so that TypeScript registers the remaining properties.

Now we can simply add a name to our routes:

const routes: Routes = [
  {
    path: '',
    name: 'theMightyDashboard',
    component: DashboardComponent
  },
];

Which - for example - can be used within our components by injecting ActivatedRoute:

constructor(private route: ActivatedRoute) {
  console.log(route.routeConfig.name); // logs `theMightyDashboard`!
}

ES types

Often times I see TypeScript code where most things are properly typed, except native ES elements. Think of something like Maps, Promises, Arrays and all that kind of stuff. But TypeScript provide types for these objects right out of the box;

Maps for example do provide generics to define the contents of our map. So instead of

const map = new Map();
map.set('name', 'John Doe');

We can improve this by specifying the types of our map key and value:

const map: Map<string, string> = new Map();
map.set('name', 'John Doe');

This prevents us from accidentally adding a type which is not allowed:

const map: Map<string, string> = new Map();
map.set('name', 123); // error: 123 is not a string

The same applies to Set:

const set: Set<number> = new Set();
set.add(123); // Ok!
set.add('whatever'); // Type error

Or native arrays:

const elements: Array<{ name: string }> = [];
elements.push({ name: 'John Doe' }); // Ok!
elements.push('John Doe'); // Type error

If you want to take a look at all types available see the official typings for ES5 and ES6 (or all the other specs)

Anything else?

As said in the beginning TypeScript can do so many things that it can get difficult to stay up to date at sometimes. If there's something you really like about TypeScript which you don't see everyday please let me know in the comments!

If you liked this post feel free to leave a ❤, follow me on Twitter and subscribe to my newsletter. This post was originally published at nehalist.io on August 06, 2019.

Creating a reading progress bar in React

Kevin — Tue, 09 Jul 2019 06:36:33 +0000

Reading progress bars, like the one you can find on my blog at the top of single posts, are a nice little addition to give detailed information about how far the reader has progressed on the current post. The scrolling bar is not really meaningful in this regard; it includes your entire page, which means that your header, comments, footer, etc. are part of the indication.

Creating a reading progress bar which tells you the actual progress of just the current post content in React is quite easy - especially with hooks, which make our component even smaller.

The ReadingProgress component

Our ReadingProgress component will do the following things:

make use of the useState hook which will be responsible for reading and setting our reading progress
make use of the useEffect hook which will be responsible for handling the scroll event and properly update our progress bar on scroll
return the reading progress bar with the proper width

So let's dive right into the implementation:

const ReadingProgress = ({ target }) => {
  const [readingProgress, setReadingProgress] = useState(0);

  return <div className={`reading-progress-bar`} style={{width: `${readingProgress}%` }} />
};

This is the foundation for our component. readingProgress will be used as width (in percent) for our progress bar. The only prop for our component is target, which will be a reference to our DOM container of the post - more on that in a few moments.

First let's implement our listener, which will update our progress bar on scroll events:

const scrollListener = () => {
    if (!target.current) {
      return;
    }

    const element = target.current;
    const totalHeight = element.clientHeight - element.offsetTop;
    const windowScrollTop = window.pageYOffset || document.documentElement.scrollTop || document.body.scrollTop || 0;

    if (windowScrollTop === 0) {
      return setReadingProgress(0);
    }

    if (windowScrollTop > totalHeight) {
      return setReadingProgress(100);
    }

    console.log(windowScrollTop);

    setReadingProgress((windowScrollTop / totalHeight) * 100);
  };

Will be placed within our ReadingProgress component.

windowScrollTop tries a bunch of different values which fixes undefined values for some browsers (e.g. Safari).

There's one problem with this implementation: 100% reading progress is only achieved if we've scrolled past our target. That's pretty unlikely to be true (except you scroll one line after finished reading one line, which would make you really weird) - so we need to slightly adjust how our reading progress is calculated:

const totalHeight = element.clientHeight - element.offsetTop - window.innerHeight;

This should yield to a more accurate result in terms of when the bar should show finished.

Next we'll put our listener into a useEffect hook, which makes our entire component to look like this:

const ReadingProgress = ({ target }) => {
  const [readingProgress, setReadingProgress] = useState(0);
  const scrollListener = () => {
    if (!target.current) {
      return;
    }

    const element = target.current;
    const totalHeight = element.clientHeight - element.offsetTop - (window.innerHeight);
    const windowScrollTop = window.pageYOffset || document.documentElement.scrollTop || document.body.scrollTop || 0;

    if (windowScrollTop === 0) {
      return setReadingProgress(0);
    }

    if (windowScrollTop > totalHeight) {
      return setReadingProgress(100);
    }

    setReadingProgress((windowScrollTop / totalHeight) * 100);
  };

  useEffect(() => {
    window.addEventListener("scroll", scrollListener);
    return () => window.removeEventListener("scroll", scrollListener);
  });

  return <div className={`reading-progress-bar`} style={{width: `${readingProgress}%`}} />;
};

The returned function from our useEffect hook is basically just what happens when the component is unmounted (see Effects with Cleanup in the docs).

Last but not least we need to use our component somewhere. At this point we'll need create a ref on our target container and simply pass this to our ReadingProgress component:

function App() {
  const target = React.createRef();
  return (
    <>
      <ReadingProgress target={target} />
      <div className={`post`} ref={target}>post content</div>
    </>
  );
}

See the docs for further information about createRef

Now your reading progress bar should work perfectly fine - except that you can't see it because it has no height. Fix this by adding some CSS:

.reading-progress-bar {
  position: sticky;
  height: 5px;
  top: 0;
  background-color: #ff0000;
}

Done! Now your readers no longer get lost in the sheer unending length of your posts and always know when it'll be over.

To see a fully working example you can take a look at this code pen:

Third party packages

There are some third party packages out there which handle this exact problem. As far as I've found out most of them are outdated and/or no longer maintained - but what's even more relevant at this point: do you really need a third party dependency for a really simple component with around 30 lines of code? Well, honestly, I don't think so.

Conclusion

As you've seen implementing a reading progress bar in React is pretty easy. Thanks to hooks we can implement this component as a very small function component with little to no overhead.

If you liked this post feel free to leave a ❤, follow me on Twitter and subscribe to my newsletter. This post was originally published on nehalist.io.

Routing with TypeScript decorators for node applications

Kevin — Tue, 02 Apr 2019 10:54:58 +0000

Decorators can be a useful tool when writing TypeScript applications. One way I like to use them for is for creating node-based MVC web application where decorators provide a convenient tool for routing. Think of something like this:

@Controller('/user')
class UserController {
    @Route('/')
    public index() {
        // return proper response
    }

    @Route('/:name')
    public details() {
        // return proper response
    }
}

This would provide routes prefixed with /user, while /user may lead to a user overview and /user/:name lead to user details. This concept may look familiar if you're used to Symfony Routing or NestJS Controllers.

Introduction

In this post we're going to build an Express application with TypeScript using ts-node (which makes it possible to run TypeScript applications without having to compile our .ts files manually).

You could use any underlying framework you want, e.g. koa, hapi or even your very own http server implementation. Differences should only occur when actually registering route, everything else should remain the same. The only reason why I've chosen express is because I have the most experience with it - but feel free to use whatever you want.

In case you're looking for a TL;DR: you can find the entire source code for this post on GitHub.

Architecture

There are different ways to implement routing capabilities with TypeScript. But before diving right into the implementation it's important to keep some things in mind.

The first important information is:

Decorators are called when a class is declared, not when it's instantiated.

So when decorating our method we do not have an instantiated object to work on inside our decorator. Instead we just have a class declaration which we can use. See here for detailed information about decorator evaluation order.

Since decorators are just functions they have their own scope. This becomes a bit problematic as soon as we realize that route registration for express takes place outside decorators:

One way to get our routes from the decorator to our express application would be introducing a registry class which would be filled by our decorator and read at some later point when registering our routes.

But there's an easier way to do this which involves the reflect-metadata library (which you're likely already using if you're dealing with decorators). Instead of using a separate layer (in form of a registry) we could simply attach routes to our controller metadata:

We simply save routes to our controller metadata. Later, when registering our routes in our express application, we already need to load our controllers - and that's where we simply read our route metadata and register them properly.

Knowing all of these things let's start implementing our routing decorators!

Express application

First of all we need to create our express application. In our first iteration we'll just serve a default route to test if everything works:

// index.ts

import 'reflect-metadata';
import {Request, Response} from 'express';

const app = express();

app.get('/', (req: Request, res: Response) => {
  res.send('Hello there!');
});

app.listen(3000, () => {
  console.log('Started express on port 3000');
});

reflect-metadata only needs to be imported once per application, hence here's a good place to do so.

Start your server with ts-node index.ts and head over to localhost:3000 to be friendly greeted by Obi-Wan.

Controller decorator

This decorator will be attached to our controllers and contain the prefix for this controller:

// Decorator/Controller.ts

export const Controller = (prefix: string = ''): ClassDecorator => {
  return (target: any) => {
    Reflect.defineMetadata('prefix', prefix, target);

    // Since routes are set by our methods this should almost never be true (except the controller has no methods)
    if (! Reflect.hasMetadata('routes', target)) {
      Reflect.defineMetadata('routes', [], target);
    }
  };
};

A pretty simple class decorator which sets the prefix metadata on the controller and, in case no routes metadata has been found, sets it to an empty array. As stated in the comments routes should almost never be undefined, except our controller has no decorated methods.

Route decorator

It would be convienient to have a decorator for every HTTP verb, like @Get, @Post, etc.. For the sake of simplicity we're only implement the @Get decorator:

// Decorator/Get.ts

import {RouteDefinition} from '..';

export const Get = (path: string): MethodDecorator => {
  // `target` equals our class, `propertyKey` equals our decorated method name
  return (target, propertyKey: string): void => {
    // In case this is the first route to be registered the `routes` metadata is likely to be undefined at this point.
    // To prevent any further validation simply set it to an empty array here.
    if (! Reflect.hasMetadata('routes', target.constructor)) {
      Reflect.defineMetadata('routes', [], target.constructor);
    }

    // Get the routes stored so far, extend it by the new route and re-set the metadata.
    const routes = Reflect.getMetadata('routes', target.constructor) as Array<RouteDefinition>;

    routes.push({
      requestMethod: 'get',
      path,
      methodName: propertyKey
    });
    Reflect.defineMetadata('routes', routes, target.constructor);
  };
};

Important: It's important to set our target target.constructor and not just target to properly handle metadata.

Again, a pretty simple decorator which extends the stored routes on the controller by a new route. RouteDefinition is an interface which defines the shape of our routes:

// Model/RouteDefinition.ts

export interface RouteDefinition {
  // Path to our route
  path: string;
  // HTTP Request method (get, post, ...)
  requestMethod: 'get' | 'post' | 'delete' | 'options' | 'put';
  // Method name within our class responsible for this route
  methodName: string;
}

Tip: In case you'd like to add some middleware before controllers it'd be a good idea to store it within the RouteDefinition.

Now we've got both of our required decorators and can get back to our express application to register our routes.

Registering routes

Before registering our routes to our express application let's implement a controller with our new decorators:

// UserController.ts

import {Controller} from '../src';
import {Get} from '../src';
import {Request, Response} from 'express';

@Controller('/user')
export default class UserController {
  @Get('/')
  public index(req: Request, res: Response) {
    return res.send('User overview');
  }

  @Get('/:name')
  public details(req: Request, res: Response) {
    return res.send(`You are looking at the profile of ${req.params.name}`);
  }
}

Heading to /user should show a "User overview" message and /user/foobar should show a "You are looking at the profile of foobar"message.

But before this fully works we need to tell express about our routes - so let's get back to our index.ts:

import 'reflect-metadata';
import * as express from 'express';
import UserController from './example/UserController';
import {RouteDefinition} from './src';

const app = express();

app.get('/', (req: express.Request, res: express.Response) => {
  res.send('Hello there!');
});

// Iterate over all our controllers and register our routes
[
  UserController
].forEach(controller => {
  // This is our instantiated class
  const instance = new controller();
  // The prefix saved to our controller
  const prefix = Reflect.getMetadata('prefix', controller);
  // Our `routes` array containing all our routes for this controller
  const routes: Array<RouteDefinition> = Reflect.getMetadata('routes', controller);

  // Iterate over all routes and register them to our express application 
  routes.forEach(route => {
    // It would be a good idea at this point to substitute the `app[route.requestMethod]` with a `switch/case` statement
    // since we can't be sure about the availability of methods on our `app` object. But for the sake of simplicity
    // this should be enough for now.
    app[route.requestMethod](prefix + route.path, (req: express.Request, res: express.Response) => {
      // Execute our method for this path and pass our express request and response object.
      instance[route.methodName](req, res);
    });
  });
});

app.listen(3000, () => {
  console.log('Started express on port 3000');
});

And voilà, that's it. We now can navigate to /user or /user/<name> and get proper responses from our express application. Wohoo!

Advancing this approach

This is a very basic approach which contains lots of room for improvement when it comes to the actual implementation. Here are some thoughts on improving this implementation:

Instantiation

Our controller is naively instantiated with new controller(). But what if our controller does have some constructor arguments?

This would be a perfect use case to apply some dependency injection as described in a former post which would be plugged in right at where our controller is instantiated.

Return values

I'm not a huge fan of res.send() - instead it would be pretty convinient if responses could be simple objects which reflects their content (think of something like return new JsonResponse(/* ... */)). This could easily be done by implementing such response objects and return them from our methods - later, when registering our routes, the callback would still send our response:

app[route.requestMethod](prefix + route.path, (req: express.Request, res: express.Response) => {
  const response = instance[route.methodName](req, res);
  res.send(response.getContent()); // where `getContent` returns the actual response content
});

This would require additional validation of our return value, especially to prevent express being stuck due to the lack of a next() call (which is covered by send but needs to be called manually if you don't utilise send).

Conclusion

As you've just seen it's pretty simple to handle routing via TypeScript decorators without having too much magic going on or having to install frameworks or any additional libraries.

As always the entire source code (including tests) for this post can be found on GitHub.

If you liked this post feel free to leave a ❤, follow me on Twitter and subscribe to my newsletter. This post was originally published at nehalist.io on April 2, 2019.

Dependency Injection in TypeScript

Kevin — Mon, 05 Feb 2018 01:16:47 +0000

One thing I really like about mature frameworks is that they all implement some kind of dependency injection. Recently I've played around with this technology in TypeScript to get a better understanding of how it works beneath the surface.

What is dependency injection (DI)?

In case you have no idea what DI is, I highly recommend to get in touch with it. Since this post should not be about the What? but more about the How? let's try to keep this as simple possible at this point:

Dependency injection is a technique whereby one object supplies the dependencies of another object.

Quote from Wiki

What does that mean? Instead of manually constructing your objects some piece (often called Injector) of your software is responsible for constructing objects.

Imagine the following code:

class Foo {
}

class Bar {
  foo: Foo;

  constructor() {
    this.foo = new Foo();
  }
}

class Foobar {
  foo: Foo;
  bar: Bar;

  constructor() {
    this.foo = new Foo();
    this.bar = new Bar();
  }
}

This is bad for multiple reasons like having direct and non-exchangable dependencies between classes, testing would be really hard, following your code becomes really hard, re-usability of components becomes harder, etc.. Dependency Injection on the other hand injects dependencies into your constructor, making all these bad things obsolet:

class Foo {
}

class Bar {
  constructor(foo: Foo) {
  }
}

class Foobar {
  constructor(foo: Foo, bar: Bar) {
  }
}

Better.

To get an instance of Foobar you'd need to construct it the following way:

const foobar = new Foobar(new Foo(), new Bar(new Foo()));

Not cool.

By using an Injector, which is responsible for creating objects, you can simply do something like:

const foobar = Injector.resolve<Foobar>(Foobar); // returns an instance of Foobar, with all injected dependencies

Better.

There are numerous resons about why you should dependency injection, including testability, maintainability, readability, etc.. Again, if you don't know about it yet, it's past time to learn something essential.

Dependency injection in TypeScript

This post will be about the implementation of our very own (and very basic) Injector. In case you're just looking for some existing solution to get DI in your project you should take a look at InversifyJS, a pretty neat IoC container for TypeScript.

What we're going to do in this post is we'll implement our very own Injector class, which is able to resolve instances by injecting all necessary dependencies. For this we'll implement a @Service decorator (you might know this as @Injectable if you're used to Angular) which defines our services and the actual Injector which will resolve instances.

Before diving right into the implementation there might be some things you should know about TypeScript and DI:

Reflection and decorators

We're going to use the reflect-metadata package to get reflection capabilities at runtime. With this package it's possible to get information about how a class is implemented - an example:

const Service = () : ClassDecorator => {
  return target => {
    console.log(Reflect.getMetadata('design:paramtypes', target));
  };
};

class Bar {}

@Service()
class Foo {
  constructor(bar: Bar, baz: string) {}
}

This would log:

[[Function: Bar], [Function: String] ]

Hence we do know about the required dependencies to inject. In case you're confused why Bar is a Function here: I'm going to cover this in the next section.

Important : it's important to note that classes without decorators do not have any metadata. This seems like a design choice of reflect-metadata, though I'm not certain about the reasoning behind it.

The type of `target`

One thing I was pretty confused about at first was the type of target of my Service decorator. Function seemed odd, since it's obviously an object instead of a function. But that's because of how JavaScript works; classes are just special functions:

class Foo {
    constructor() {
        // the constructor
    }
    bar() {
        // a method
    }
}

Becomes

var Foo = /** @class */ (function () {
    function Foo() {
        // the constructor
    }
    Foo.prototype.bar = function () {
        // a method
    };
    return Foo;
}());

After compilation.

But Function is nothing we'd want to use for a type, since it's way too generic. Since we're not dealing with an actual instance at this point we need a type which describes what type we get after invoking our target with new:

interface Type<T> {
  new(...args: any[]): T;
}

Type<T> is able to tell us what an object is instances of - or in other words: what are we getting when we call it with new. Looking back at our @Service decorator the actual type would be:

const Service = () : ClassDecorator => {
  return target => {
    // `target` in this case is `Type<Foo>`, not `Foo`
  };
};

One thing which bothered me here was ClassDecorator, which looks like this:

declare type ClassDecorator = <TFunction extends Function>(target: TFunction) => TFunction | void;

That's unfortunate, since we now do know the type of our object. To get a more flexible and generic type for class decorators:

export type GenericClassDecorator<T> = (target: T) => void;

Interfaces are gone after compilation

Since interfaces are not part of JavaScript they simply disappear after your TypeScript is compiled. Nothing new, but that means we can't use interfaces for dependency injection. An example:

interface LoggerInterface {
  write(message: string);
}

class Server {
  constructor(logger: LoggerInterface) {
    this.logger.write('Service called');
  }
}

There'll be no way for our Injector to know what to inject here, since the interface is gone at runtime.

That's actually a pity, because it means we always have to type-hint our real classes instead of interfaces. Especially when it comes to testing this may be become really unforunate.

There are workarounds, e.g. using classes instead of interfaces (which feels pretty weird and takes away the meaningfulness of interfaces) or something like

interface LoggerInterface {
  kind: 'logger';
}

class FileLogger implements LoggerInterface {
  kind: 'logger';
}

But I really don't like this approach, since its redundant and pretty ugly.

Circular dependencies causes trouble

In case you're trying to do something like:

@Service()
class Bar {
  constructor(foo: Foo) {}
}

@Service()
class Foo {
  constructor(bar: Bar) {}
}

You'll get a ReferenceError, telling you:

ReferenceError: Foo is not defined

The reason for this is quite obvious: Foo doesn't exist at the time TypeScript tries to get information on Bar.

I don't want to go into detail here, but one possible workaround would be implementing something like Angulars forwardRef.

Implementing our very own Injector

Okay, enough theory. Let's implement a very basic Injector class.

We're going to use all the things we've learned from above, starting with our @Service decorator.

The `@Service` decorator

We're going to decorate all services, otherwise they wouldn't emit meta data (making it impossible to inject dependencies).

// ServiceDecorator.ts

const Service = () : GenericClassDecorator<Type<object>> => {
  return (target: Type<object>) => {
    // do something with `target`, e.g. some kind of validation or passing it to the Injector and store them
  };
};

The `Injector`

The injector is capable of resolving requested instances. It may have additional capabilities like storing resolved instances (I like to call them shared instances), but for the sake of simplicity we're gonna implement it as simple as possible for now.

// Injector.ts

export const Injector = new class {
  // Injector implementation
};

The reason for exporting a constant instead of a class (like export class Injector [...]) is that our Injector is a singleton. Otherwise we'd never get the same instance of our Injector, meaning everytime you import the Injector you'll get an instance of it which has no services registered. (Like every singleton this has some downsides, especially when it comes to testing.)

The next thing we need to implement is a method for resolving our instances:

// Injector.ts

export const Injector = new class {
  // resolving instances
  resolve<T>(target: Type<any>): T {
    // tokens are required dependencies, while injections are resolved tokens from the Injector
    let tokens = Reflect.getMetadata('design:paramtypes', target) || [],
        injections = tokens.map(token => Injector.resolve<any>(token));

    return new target(...injections);
  }
};

That's it. Our Injector is now able to resolve requested instances. Let's get back to our (now slightly extended) example at the beginning and resolve it via the Injector:

@Service()
class Foo {
  doFooStuff() {
    console.log('foo');
  }
}

@Service()
class Bar {
  constructor(public foo: Foo) {
  }

  doBarStuff() {
    console.log('bar');
  }
}

@Service()
class Foobar {
  constructor(public foo: Foo, public bar: Bar) {
  }
}

const foobar = Injector.resolve<Foobar>(Foobar);
foobar.bar.doBarStuff();
foobar.foo.doFooStuff();
foobar.bar.foo.doFooStuff();

Console output:

bar
foo
foo

Meaning that our Injector successfully injected all dependencies. Wohoo!

Conclusion

Dependency injection is a powerful tool you should definitely utilise. This post is about how DI works and should give you a glimpse of how to implement your very own injector.

There are still many things to do. To name a few things:

error handling
handle circular dependencies
store resolved instances
ability to inject more than constructor tokens
etc.

But basically this is how an injector could work.

And, as always, the entire code (including examples and tests) can be found on GitHub.

If you liked this post feel free to leave a ❤, follow me on Twitter and subscribe to my newsletter. This post was originally published at nehalist.io on February 5, 2018.

DEV Community: Kevin

Building and deploying Gatsby sites with GitHub actions

Why tho?

The problem

GitHub action

Secrets

Building the site

Deploying the site

Docker

SSH Keys

Deploy script

Triggering the action from outside

Conclusion

Adding Commento to React Apps (like Gatsby)

Zero dependency component

Software development blogging: analytics, revenue, content and more

Preface

Analytics

Site content

Acquisition

Ad revenue

AdSense

Carbon Ads

AdSense or Carbon Ads?

Content

Finding topics

Content distribution

Conclusion

Software Spotlight: Husky, git hooks made easy

Husky, Git hooks made easy

What it does

How it works

Why to use it

5 TypeScript tips to improve your architecture

Utility types

Use unknown instead of any

Lookup types

Extending third-party libraries

ES types

Anything else?

Creating a reading progress bar in React

The ReadingProgress component

Third party packages

Conclusion

Routing with TypeScript decorators for node applications

Introduction

Architecture

Express application

Controller decorator

Route decorator

Registering routes

Advancing this approach

Instantiation

Return values

Conclusion

Dependency Injection in TypeScript

What is dependency injection (DI)?

Dependency injection in TypeScript

Reflection and decorators

The type of target

Interfaces are gone after compilation

Circular dependencies causes trouble

Implementing our very own Injector

The @Service decorator

The Injector

Conclusion

The type of `target`

The `@Service` decorator

The `Injector`