· hands on

Write a simple TypeScript script with ESM

I recently wrote a small TypeScript script to generate a Markdown file with a sluggified filename. Since we're now in the era of modern ECMAScript Modules (ESM), I wanted to use this new module system in my TypeScript code. Here's how I did it.

I installed ts-node so I could run my script in a Node.js environment from the command line. The great thing about ts-node is that it works well with ESM. It comes with a binary called ts-node-esm that supports loading ECMAScript modules when you run TypeScript code.

Contents

Making TypeScript Work with ESM

Once you've installed ts-node with npm install, you can immediately direct it to your script by:

npx ts-node-esm src/main.ts

Please note that we are using ts-node-esm instead of ts-node to leverage its ESM loading capabilities.

This requires marking your Node.js package as an ECMAScript module. You can achieve this by using specific file extensions (as discussed later in the article) or by setting "type": "module" in your package.json file.

Additionally, ensure your tsconfig.json file has the module option set to Node16 (for module resolution introduced in Node v16) or NodeNext (for experimental module resolution).

Handling File and Folder Paths

In the world of ESM, the usual __filename and __dirname constants are not available. So, I found a way to mimic this by using the import.meta property:

import path from 'node:path';
import url from 'node:url';
 
const __filename = url.fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

Using New File Extensions

TypeScript lets you pick different file extensions to tell whether you're using ES modules (.mts) or CommonJS modules (.cts).

If you only need to run a single script with the ES module syntax, I recommend using the .mts extension. It's great in scenarios where you don't want to set up your whole project to use ES modules.

Demo Code

Here's the complete script I developed:

src/new-post.mts
import GithubSlugger from 'github-slugger';
import fs from 'node:fs';
import path from 'node:path';
import url from 'node:url';
 
const __filename = url.fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);
 
const args = process.argv.slice(2);
const title = args[0];
const slugger = new GithubSlugger();
const slug = slugger.slug(title);
const filePath = path.join(__dirname, 'content', 'blog', `${slug}.md`);
 
console.log(`Creating file "${filePath}"...`);
fs.writeFileSync(filePath, '', 'utf8');
console.log(`Created file "${filePath}".`);

It can be executed as follows:

npx ts-node-esm src/new-post.mts "My Post Title"

Fixing ERR_UNKNOWN_FILE_EXTENSION

There is the possibility that this error occurs when using Node.js v20 with ESM and ts-node. In such cases, we have to use the following command:

tsc --noEmit && node --no-warnings=ExperimentalWarning --loader ts-node/esm/transpile-only src/new-post.mts "My Post Title"

Read more about it here.

Video Tutorial

For a full explanation, check out the video I made here:

Back to Blog