Numerous Packages Multiply

    @digitak/tsc-esm
    TypeScript icon, indicating that this package has built-in type declarations

    3.1.4 • Public • Published

    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:

    1. 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),
    2. 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:

    1. it calls tsc,
    2. 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.

    Install

    npm i @digitak/tsc-esm

    DownloadsWeekly Downloads

    2,821

    Version

    3.1.4

    License

    MIT

    Unpacked Size

    16.1 kB

    Total Files

    11

    Last publish

    Collaborators

    • gin-quin