@digitak/tsc-esm

I don't recommend anymore to use this package.

Since TS 4.7 it is now possible to set the moduleResolution field to node16 or nodeNext which enforces the use of the .js extension at the end of the imports.

Previously, Typescript allowed to not add the imported file extension if it was a Typescript or Javascript file. This behavior was opposed to the recent developments of Ecmascript. Browsers, Node and Deno all needed the .js extension.

I first developped tsc-esm as a patch to the tsc compiler that would add the .js extension. But this technique has drawbacks. For example, it cannot deal with Typescript aliases. I strongly encourage to follow the Ecmascript guidelines and the recent Typescript extension, that is to use Typescript@^4.7 and to set the moduleResolution field to node16 or nodeNext in tsconfig.json.

tsc-esm is a small wrapper library can be used to replace Typescript's tsc compilation command when generating modern Javascript with ES6 modules.

The problem

In order to use ES6 modules either in a browser, a Node (with "type": "module") or a Deno environment, a ".js" extension is mandatory at the end of each import statement.

For example, you can do:

import foo from './foo.js'

but you cannot do:

import foo from './foo'

However Typescript compiler do understand the latter case and it's even recommended to use it. Some linters will complain if you add the unnecessary ".js" or ".ts" extension.

In the same way, Typescript can understant when you a /foo/index.ts directory structure, you can do

import foo from '/foo'

and Typescript will understand you need to import the index.ts file.

That's actually great... Until you want to compile your Typescript code to modern Javascript with ES6 modules. As it is explained well enough in this long issue: provide a way to add the '.js' file extension to the end of module specifiers, the Typescript team considers that since users can manually add themselves a ".js" extension to all their imports, this is not an issue.

In my opinion it is still an issue because:

• valid Typescript code can be compiled with no errors and still generate invalid Javascript (and all platforms disagree it is invalid: Browser, Node and Deno),
• even if it works, it is semantically incorrect to write import foo from "/foo/index.js" when your directory structure is /foo/index.ts, because you are explicitly importing to a file that does not exist yet (it will exist after compilation).

The solution

Use tsc-esm instead of tsc.

tsc-esm works in two simple steps:

• it calls tsc,
• it uses the grubber library to safely parse the generated javascript files and patch the import expressions.

It is highly recommended that you have a tsconfig.json configuration file in your root project with either compilerOptions.outDir or include option set ; otherwise all .js files in your project will be scanned and transformed.

CLI

Global installation

npm i -g @digitak/tsc-esm
tsc-esm

Local installation

npm i -g @digitak/tsc-esm

Then add a script in your package.json:

{
   "scripts": {
      "build": "tsc-esm"
   }
}

Then you can run:

npm run build

API

import { build } from '@digitak/tsc-esm'

build()

Or:

import { compile, patch } from '@digitak/tsc-esm'

compile()
patch()

Aliases

You can pass aliases to the build or the patch functions to control how some paths should be transformed or not:

function build(aliases?: Array<AliasResolver>): void
function patch(aliases?: Array<AliasResolver>): void

type AliasResolver = {
   find: RegExp; // the path to match
   replacement: string | null; // the replacement value
};

The function String::replace is used internally so you can replace your path using special patterns like $1or $&.

If the replacement value is null, the path will be left untransformed.

It can be useful when working when libraries that don't have clean type definitions.

If you have a chokidar dependency for example you might need to tell tsc-esc to not patch this specific import:

build([
   { find: /^chokidar$/, replacement: null },
])

Then all import chokidar from 'chokidar' statements will be left unchanged, otherwise it would have been transformed into import chokidar from 'chokidar/index.js' which is not typed.