archive/rsnext
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
rsnext/errors/import-esm-externals.md
Tobias Koppers 7a8da9741d
add support for esm externals (#27069) 
add `experimental.esmExternals: boolean | 'loose'` config option

remove `output.environment` configuration in favor of `target`

|                          | `esmExternals: false` (default) | `esmExternals: 'loose'` | `esmExternals: true` |
| ------------------------ | ------------------------------- | ----------------------- | -------------------- |
| import cjs package       | `require()`                     | `require()`             | `require()`          |
| require cjs package      | `require()`                     | `require()`             | `require()`          |
| import mixed package     | `require()` ***                 | `import()`              | `import()`           |
| require mixed package    | `require()`                     | `require()`             | `require()`          |
| import pure esm package  | `import()`                      | `import()`              | `import()`           |
| require pure esm package | Error **                        | `import()` *            | Error **             |
| import pure cjs package  | `require()`                     | `require()`             | Resolving error      |
| require pure cjs package | `require()`                     | `require()`             | `require()`          |

cjs package: Offers only CJS implementation (may not even have an `exports` field)
mixed package: Offers CJS and ESM implementation via `exports` field
pure esm package: Only offers an ESM implementation (may not even have an `exports` field)
pure cjs package: CommonJs package that prevents importing via `exports` field when `import` is used.

`*` This case will behave a bit unexpected for now, since `require` will return a Promise. So that need to be awaited. This will be fixed once the whole next.js bundle is ESM. It didn't work at all before this PR.
`**` This is a new Error when trying to require an esm package.
`***` For mixed packages we prefer the CommonJS variant to avoid a breaking change.

## Feature

- [ ] Implements an existing feature request or RFC. Make sure the feature request has been accepted for implementation before opening a PR.
- [ ] Related issues linked using `fixes #number`
- [x] Integration tests added
- [ ] Documentation added
- [ ] Telemetry added. In case of a feature if it's used or not.
- [x] Errors have helpful link attached, see `contributing.md`

## Documentation / Examples

- [ ] Make sure the linting passes
2021-07-10 16:49:02 +00:00

759 B
Raw Blame History

ESM packages need to be imported

Why This Error Occurred

Packages in node_modules that are published as EcmaScript Module, need to be imported via import ... from 'package' or import('package').

You get this error when using a different way to reference the package, e. g. require().

Possible Ways to Fix It

  1. Use import or import() to reference the package instead. (Recommended)

  2. If you are already using import, make sure that this is not changed by a transpiler, e. g. TypeScript or Babel.

  3. Switch to loose mode (experimental.esmExternals: 'loose'), which tries to automatically correct this error.

Useful Links