Repo guidance: Package export best practices

WARNING

This page is a work in progress.

Include ES modules

When publishing a package, include ES module format JS output, ideally instead of CommonJS. Lean more about module formats

At minimum your package.json should include a module property pointing to your ESM, but using exports maps is even better. Note that if your code includes any state or singletons and you need to include multiple module formats, there are some subtleties to setting this up.

Use recommended TypeScript settings

Assuming you use TypeScript to build your project, you should use the isolatedModules setting in your tsconfig.json. This enforces that your code can be transpiled in isolation and prohibits patterns that break that, such as exporting types from other libraries without using export type syntax, or using const enum.

See the recommended settings page for more.

Avoid export *, especially from another package

Re-exporting the entirety of another package (export * from "some-pkg") creates an unpredictable API surface and other problems. It's better to be explicit about exports to prevent accidents like exporting the same name when dependencies conflict.

In some cases, it can be okay to use export * from "./local-path", but this has its own pitfalls, especially in inner index files.

Use exports maps, especially for multiple entries

Define explicit entries using the exports map in package.json for predictable consumption, and to enable multiple entry points without arbitrary deep imports. Once a package defines an exports map, attempts at importing other paths will fail at runtime (and should fail at compile/bundle time, though implementations vary).

Exports maps also allow specifying multiple module formats depending on the context of the import using conditions, such as "require" for CJS and "import" for ESM. See the link above for full details.

Use local stubs for async imports

When lazily importing from another package, prefer a local stub that re-exports needed symbols. See Use async import stubs.

Exporting images

Cloudpack supports importing images (.jpg | .png | .svg) from within a package or across package boundaries.

Exporting localized resources

TODO