tsc-esm is a small wrapper library can be used to replace Typescript's tsc
compilation command when generating modern Javascript with ES6 modules.
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).
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.
npm i -g @digitak/tsc-esm
tsc-esm
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
import { build } from '@digitak/tsc-esm'
build() // takes no argument