Docker Node Template

Docker Node Template is a template repository for developing Docker Containers that run a NodeJS service.

Many times, I have needed to create a NodeJS service that can be easily ran via a Docker Container. After maybe the 5th time creating an entire development pipeline from scratch, I decided to create this template repo.

Goals

I wanted this template to be easy to use, with as much pre-configured as possible. I also wanted hot-reloading with in-container development.

Features

• Typescript support
• Hot-Reloading in development
• Development inside a docker-container (similar to production environment)
• GitHub Actions to compile and upload containers to registry (Dockerhub and GitHub)
• linux/amd64 and linux/arm64 default targets
• pnpm for NodeJS package management

Developmental Benifits

Hot-Reloading

ESBuild is used to compile Typescript files and to watch for file changes and reload. This makes if very easy and fast to develop; each time a file is modified, the entire stack is reloaded.

Additionally, files are ‘compressed’ to one output file, where possible, even during the hot-reloading development phase. This means that the code being written is being ran in the same format it will be ran in the production environment.

ESBuild packages files together pretty darn fast. In my usage of this template, I haven’t noticed the compile-time during development.

In-Container Development

One of the primary benefits of Docker Containers (or containerization in general, for that matter), is that is runs the same on whatever machine it is deployed to.

The issue is that these benefits only work inside the container, and developing a NodeJS service on your local machine might not run exactly the same inside a container. This template removes this issue by having the developmental code ran inside the container as it is edited, with full hot-reloading support.

Connecting the Container and Dev Code

During development, a dev container is created and ran, with a mount node_modules and the top-level directory. This means that as files are edited, the container ‘sees’ those same edits. ESBuild is ran inside the container and watches for file changes, enabling hot-reloading.

Usage

Besides the usual NodeJS and Typescript developmental steps, the dev environment must be built:

# Start dev environment and hot-reload with ESBuild
make dev

To create a local export of the container that will be uploaded to the container registries, run the following command:

# Build the full image and host it locally
make create-local && make local

This will create and run the container locally.

Repo Configuration

GitHub Actions are used to build the source code into containers and push those containers to Dockerhub and the GitHub registry (ghcr.io). Additionally, the Dockerhub readme and description is copied from the repo.

In order to facilitate these functions, multiple repo variables must be set. See documentation for more details.