2024-02-25

Setting up a Typescript-based Node project: the basics

tl;dr: This is the simplest way I know of setting up a Node projeect using Typescript from scratch.

My weapon of choice for most development these days is Node, and because my formative code years were spent fighting with type-safe languages, I prefer Typescript to vanilla Javascript.

I start a lot more projects that I finish, but despite the number of times I’ve set things up from scratch, I always end up forgetting some step some point along the way. The point of this post is a note-to-self with a process to follow; and maybe an aide-memoire for others.

There’s a cloneable repo containing this setup on Github.

The process

There are three stages:

1. Basic directory and Git things
2. Node and Typescript
3. Wiring it all up

Strictly speaking, step 3 isn’t essential, but it’s nice to make sure things work.

Directory and Git things

1. Create a directory for the project:

mkdir template-node-project
cd template-node-project

2. Initialise Git

git init

3. Add a .gitignore for later:

touch .gitignore

4. Add a README for later:

touch README.md

Setup the Node project

1. Initialise the Node project:

npm init -y

2. This will create a package.json file that contains default settings for things like the project name, version, license and so on. You can edit these as needed later.

Set up Typescript

1. Install Typescript, the Node dependencies, and the Node types:

npm i -D typescript ts-node @types/node

2. Initialise Typescript:

npx tsc --init

4. Add an .env file:

touch .env

5. Add a placeholder environment variable in the .env file:

GREETING=world

6. Update the package.json file to add a couple of extra settings:

• Add an engines section

{
  "engines": {
    "node": ">=20.6.0"
  },
  "name": "template-node-project",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "build": "tsc",
    "dev": "node --env-file=.env --watch -r ts-node/register src/index.ts",
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

• this defines:
  • uses tsc as the compiler
  • loads the .env file to set environment variables
  • runs the Node process in ‘watch’ mode, so code changes are automatically reloaded
  • runs the index.ts file

Add in some boilerplace code

1. Create a src directory for the source files:

mkdir src
cd src

2. Create an index.ts file:

mkdir src
touch ./src/index.ts

3. Add a basic ‘hello, world’ function to index.ts:

function helloWorld(): void {
  console.log(`Hello, ${process.env.GREETING}!`);
}

helloWorld();

Run the Node process

The Node process can be run with npm run dev

This picks up the script that was setup in the package.json file earlier - if everything’s configued correctly you’ll see the process fire up and run the helloWorld function:

npm run dev

> template-node-project@0.0.1 dev
> node --env-file=.env --watch -r ts-node/register src/index.ts

(node:98297) ExperimentalWarning: Watch mode is an experimental feature and might change at any time
(Use `node --trace-warnings ...` to show where the warning was created)
Hello, world!
Completed running 'src/index.ts'