npm-to-esm

npm-to-esm is a utility for making ESM bundles out of npm-modules fetched off of the npm registry located at registry.npmjs.org.

Description

It does this by fetching a specified NPM-module from the registry to your file system, and using a specified entrypoint, it runs the contents of the module through a Rollup build that is setup and executed here, putting the resulting contents in an outputFile of your choice (or ./index.esm.js from where you are running it by default).

It has been tested using modules that are on CommonJS and ESM formats respectively. However, it should be considered a best-effort and it may not work for your use-case - this util is still very much a work in progress.

Getting started

To install the package from the NPM registry:

npm install -g @navikt/npm-to-esm

Usage example:

npm-to-esm --packageName @navikt/ds-react --packageVersion 0.14.3-beta.1 --entry ./esm/index.js

You may also require it from Node.js and provide options as an argument:

const npmToEsm = require('@navikt/npm-to-esm');

async function myFunction() {
    const rollupOutput = await npmToEsm({ 
        packageName: '@navikt/ds-react', 
        packageVersion: '0.16.8'
        // ... other options
    })
}

Options

| Option | Description | Required / Optional | Default value | Example | | --- | --- | --- | --- | --- | | --packageName <packageName> | The desired package from NPM registry | required | | | | --packageVersion <version> | Version of the desired package | required | | | | --entry <path to entrypoint> | Custom entrypoint to build from (relative to root of the specified package) | optional | | | | --includeDependencies | Whether or not to include dependencies of the package in the resulting ESM bundle | optional | | | | --importMap <path to file> | Path to a file containing an import map in valid JSON format. Uses this rollup-plugin to translate imports to use specified URLs instead (see example). Takes precedence over --includeDependencies for imports included in the import map. | optional | | { "react": "https://<my-cool-cdn>/react.esm.js" } | | --outputFile <path to file> | Where to output the finished bundle | optional | ./index.js | |

Replacing strings in output build

If you want to modify the output of the rollup build before writing the contents to a file, the rollup-build has been configured with usage of rollup's replace plugin, and providing a custom config object to this plugin is supported when using npm-to-esm from Node.js (please read the docs for @rollup/plugin-replace for how to configure it for your use case).

Example:

const npmToEsm = require('@navikt/npm-to-esm');

async function myFunction() {
    const rollupOutput = await npmToEsm({ 
        packageName: '@navikt/ds-react', 
        packageVersion: '0.16.8'
        replaceConfig: {
            delimiters: ['', ''],
            values: {
                'process.env.NODE_ENV': JSON.stringify('production'),
                'import { myNamedExport }': 'import myDefaultExport' 
            }
        }
    })
}

Please note: The replace plugin does have a default configuration set up in the rollup build, regardless of whether npm-to-esm is being used from Node.js or CLI.

Currently, it is configured with this by default:

{
    preventAssignment: true,
    'process.env.NODE_ENV': JSON.stringify('production'),
};

Contact

Questions regarding the code may be asked as issues to this GitHub repository.

For NAV-employees

Interne henvendelser kan sendes via Slack i kanalen #personbruker-teknisk.