Working with Node.js and TypeScript is great, getting the build system setup is arguably less great, depending on what you're into. Here's a quick and dirty guide to aid in getting the build system setup, and get code distributed.

Initialize a new project

First we're going to need to setup the project, then install the necessary dependencies, etc, etc.

npm init -y
npm install typescript ts-node @types/node --save-dev
npx tsc --init

That last tsc command is used to create a tsconfig.json file to configure your TypeScript compiler. This should auto generate a tsconfig.json file with the essential default configurations. We'll need to add a few more to get this code ready for distribution.

Setup the compiler

Servers and Browsers generally don't recognize TypeScript by default. In most cases, we'll have to convert (compile) the TypeScript into a language that can be ran natively in those environments.

{
  "compilerOptions": {
    "target": "es5",
    "lib": ["esnext"],
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "strict": true,
    "forceConsistentCasingInFileNames": true,
    "module": "esnext",
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "declaration": true,
    "declarationDir": "./dist",
    "outDir": "./dist"
  },
  "include": ["src", "utils", "index.ts"]
}

Let's walk through this because even though it's dull as a old crayon, we need to understand. Not to mention you'll see this stuff everywhere in you're career on the front-end so it's best to familiarize yourself with it.

compilerOptions.target - Tells the compiler what standard the code should be compiled into. ECMAScript5 (es5) is pretty standard for older environments, you might also consider more modern options such as ECMAScript 11 (es2020) See a full list of options here.
compilerOptions.lib - Options used to specify which built-in JavaScript libraries to include for type checking and code completion. While we won't be diving into browser-side code here, it's worth mentioning some common options. Like most things, it's best to consult the official documentation to see what options apply best to your use-case.
- esnext: Includes types for the latest JavaScript features.
- dom: Contains types for the Document Object Model (DOM), typically used in web browsers.
- dom.iterable: Provides types for iterable DOM collections.

compilerOptions.esModuleInterop - This option enables compatibility (interoperability) between CommonJS (the traditional Node.js module system) and ES Modules (the newer standard). Useful for libraries that might be using different module systems, which is rather common in this awkward phase of JavaScript's life as a programming language. Checkout the docs here.

compilerOptions.allowSyntheticDefaultImports - Going to be similar to the esModuleInterop option referenced above. This option allows you to import modules using the default import syntax (import x from 'module') even if the module doesn't have an explicit default export. It's helpful for compatibility with older libraries.
compilerOptions.strict - You know.. the stricter version of JavaScript that you have no reason not to use.
compilerOptions.forceConsistentCasingInFileNames - This option enforces consistent casing in file names and import paths. This is a nice-to-have now feature, because some case-sensitive file systems (like Linux and macOS) will throw errors if file names/ import paths aren't valid, and theres a good chance you're going to be confused as to why it's happening.

compilerOptions.module - By using"esnext" you are using the latest module syntax (e.g., import and export). You may also consider using "commonjs" for broader compatibility if you're looking to target older Node.js versions.
compilerOptions.moduleResolution - Tells TypeScript to use Node.js's module resolution algorithm to find modules when importing them in your code
compilerOptions.resolveJsonModule - Enables TypeScript to interact with JSON file types.
compilerOptions.isolatedModules - This option is important for enabling some error-checking features during compilation. It's generally recommended to keep it enabled.
compilerOptions.declaration - This option instructs the compiler to generate type declaration files (.d.ts) alongside your compiled JavaScript. These files describe the types in your code and are useful when others want to use your code as a library.
compilerOptions.declarationDir - This option specifies the directory where the generated declaration files will be placed.
compilerOptions.outDir - This option specifies the output directory for your compiled JavaScript files.

That wasn't the most fun right, kind of like reading cooking instructions without actually cooking. Anyways, I feel like we're in a position where we can ethically keep it moving, so let's do that.

Setup the project structure

We'll just spin up a simple "Hello, World" to get started. Your directory should already have the package.json and the tsconfig.json files present, so next we'll want to create a new TypeScript file to write our code.

Create the src/hello.ts and src/index.ts files.

your-project/
├── src/
│   ├── hello.ts
│   └── index.ts 
├── tsconfig.json
└── package.json

Since the scope of this guide is more geared toward the configuration of a project, and less about the feature details, we won't do anything too crazy with the code we're exporting.

In the src/hello.ts file, create and export a simple function that returns a string as a value. We've just created a TypeScript module. 🎉

export function sayHello(name: string): string {
  return `Hello, ${name}!`;
}

and in the src/index.ts file, we can implement some logic to demonstrate how this code.

import { sayHello } from './hello'

console.log(sayHello('Fred'))

Like mentioned above, there's nothing too crazy here. Let's move onto the build phase.

Build and run

Let's build TypeScript, and inspect the output. Head over to the package.json file in the root of your project's directory and add the following script to build your code:

"scripts": {
  "build": "tsc"
}

To build and run your project, with following chain of commands

npm run build

If the command succeeds we should see a new directory created titled dist that should contains the JavaScript equivalent of the TypeScript code. Let's test it out.

node dist/index.js

If everything went as expected, we should have a "Hello, Fred!" printed to the console.

That's really all there is too it. You've successfully set up a TypeScript build system for Node.js, compiled your code, and ran it to get the desired output. From here, you can expand your project, add more modules, and explore the many powerful features of TypeScript.

TypeScript Builds for Node.js