https://github.com/ai/dual-publish

Publish JS project as dual ES modules and CommonJS package to npm
https://github.com/ai/dual-publish

Last synced: about 2 months ago
JSON representation

Publish JS project as dual ES modules and CommonJS package to npm

• Host: GitHub
• URL: https://github.com/ai/dual-publish
• Owner: ai
• License: mit
• Created: 2020-02-15T20:14:15.000Z (over 4 years ago)
• Default Branch: main
• Last Pushed: 2024-06-18T08:08:54.000Z (3 months ago)
• Last Synced: 2024-07-24T08:11:45.221Z (2 months ago)
• Language: JavaScript
• Homepage:
• Size: 1.84 MB
• Stars: 186
• Watchers: 3
• Forks: 11
• Open Issues: 2
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • License: LICENSE

Awesome Lists containing this project

• awesome-list - dual-publish
• awesome-node-esm - dual-publish - publish JS project as dual ES modules and CommonJS package to npm (Tools)

README

        
# Dual Publish

Publish JS project as dual ES modules and CommonJS package to npm.

* Tested on [projects] with **16M downloads per month**.

* [CI tests] with it works with **Node.js**, **browsers**, **React Native**,

  **bundlers** (webpack, Parcel, Rollup, or esbuild) and **CDNs** (like jspm).

* Does not change **line numbers in stacktrace** and keep sources **readable**.

* **No build step.** No need for separated `src/` and `dist/` dirs in repository.

  You will be able to test branch by installing version from GitHub like

  `npm i example@you/example#fix`.

* **Multiple files support**. Your user will be able to import separated files

  
like `import { nanoid } from 'nanoid/async'`.

* Cleans npm package from development configs [before publishing].

* Supports `process.env.NODE_ENV` for development checks, which you want

  to remove in production JS bundle.

You write CommonJS in your npm library sources:

```js

// index.js

module.exports = { lib }

```

`npx dual-publish` compiles your library during publishing to npm:

```js

// index.js

export { lib }

// index.cjs

module.exports = { lib }

// package.json

{

  …

  "type": "module",

  "module": "index.js",

  "main": "index.cjs",

  "exports": {

    "require": "./index.cjs",

    "import": "./index.js"

  }

}

```

Now your library can be imported natively as ESM or CommonJS:

```js

// CommonJS

let { lib } = require('lib')

// ESM in Node.js, webpack, Parcel, and Rollup

import { lib } from 'lib'

// ESM in browser

import { lib } from 'https://cdn.jsdelivr.net/npm/lib/index.js'

```

[before publishing]: https://github.com/shashkovdanil/clean-publish/

[CI tests]: https://github.com/ai/dual-publish/blob/master/test/index.test.js

[projects]: https://github.com/search?l=JSON&q=%22dual-publish%22&type=Code



  



## Limits

* We recommend to avoid default export because of [bug in webpack].

* Every JS file should be in own dir. `lib/index.js` instead of `lib.js`.

  We need it to put `package.json` with `module`.

[bug in webpack]: https://github.com/webpack/webpack/issues/6584

## Usage

1. Take a normal CommonJS project with `require()` and `module.exports =`.

2. Because of [bug in webpack] we recommend to use only named exports:

   ```js

   const NAME = 'a'

   function change {

     …

   }

   module.exports = { NAME, change }

   ```

3. Move all files into separated dirs. Rename `lib.js` to `lib/index.js`.

   Old `require('./lib')` will work.

4. Add `dual-publish` to the project:

   ```sh

   npm i --save-dev dual-publish

   ```

5. Test the result by calling `npx dual-publish --check`.

   It will create a folder in your project with converted files.

   Review them manually.

6. Publish your project with `npx dual-publish` instead of `npm publish`.

   ```sh

   npx dual-publish

   ```