package-json-exports

A file based package.json exports generator depending on fast-glob.

Installation

1pnpm i -D package-json-exports

Concepts

As a library maintainer, maintaining exports in the package.json file can be challenging when there are many files in the package, especially if we choose to provide individual files for certain reasons, instead of bundling them into a single file. Keeping the exports up-to-date manually when the files change is error-prone and time-consuming. This library solves this issue by generating exports automatically based on the files in the package. It can be integrated into the build process and used with rules to generate exports with ease.

Usage

1import { generateExports } from "package-json-exports";
2
3const packageJson = JSON.parse(await fs.readFile("package.json", "utf-8"));
4packageJson.main = "./index.js";
5packageJson.module = "./esm/index.js";
6packageJson.types = "./index.d.ts";
7packageJson.exports = await generateExports(options);
8
9await fs.writeFile("package.json", JSON.stringify(packageJson, null, 2));

Recipes

The exports in this library's package.json follows DAISHI KATO's How Jotai Specifies Package Entry Points, and here is the generating script: scripts/generatePackageJson.ts.

Options

rules

• Type: Rule[]

The rules to generate the exports.

Each rule is applied in order, and later rules override previous ones.

Each rule only executes fast-glob once. To improve performance, try to use fewer rules.

rules.pattern

• Type: string

The matching pattern for fast-glob.

rules.exports

• Type: (matchedFilePath: string) => condition[]

You can return an array of conditions. A condition is an array of the property path from exports. For example, if you want to generate:

1{
2  "exports": {
3    "foo": {
4      "bar": "./src/index.js"
5    }
6  }
7}

the condition should be ["foo", "bar"].

You can return several conditions:

1{
2  exports: (matchedFilePath) => {
3    return [
4      ["foo", "bar"],
5      ["foo", "baz"],
6    ];
7  },
8}

The result will be:

1{
2  "exports": {
3    "foo": {
4      "bar": "./src/index.js",
5      "baz": "./src/index.js"
6    }
7  }
8}

You can also return [] to ignore the file.

Notice that the matchedFilePath is always starts with ./.

rules.fastGlobOptions

• Type: FastGlob.Options

This option is passed to fast-glob when matching the files. It's useful when you want to ignore some files.

defaultConditionKey

• Type: string
• Default: undefined

The default condition key to use when conditions conflict.

For example if there are files:

src/index.js

And the rules are:

1[
2  {
3    pattern: "**/*.js",
4    exports: (matchedFilePath) => {
5      return [[generateExports.pathCondition(matchedFilePath), "require"]];
6    },
7  },
8  {
9    pattern: "**/*",
10    exports: (matchedFilePath) => {
11      return [[generateExports.pathCondition(matchedFilePath)]];
12    },
13  },
14];

The result will be:

1{
2  "exports": {
3    "./src/index.js": {
4      "require": "./src/index.js",
5      "default": "./src/index.js"
6    }
7  }
8}

Without setting defaultConditionKey, it throws an error when conditions conflict.

fastGlobOptions

• Type: FastGlob.Options

You can set the cwd and ignore options here. dot option is set to true by default. You can override it by setting it to false.

simplify

• Type: boolean
• Default: false

Simplify the exports. It will replace the object with only one property with the value of the property recursively.

For example, if the exports was:

1{
2  "exports": {
3    "./src/index.js": {
4      "browser": {
5        "import": "./src/index.js"
6      }
7    },
8    "./src/foo.js": {
9      "require": "./src/foo.js",
10      "default": "./src/foo.js"
11    }
12  }
13}

It will be simplified to:

1{
2  "exports": {
3    "./src/index.js": "./src/index.js",
4    "./src/foo.js": {
5      "require": "./src/foo.js",
6      "default": "./src/foo.js"
7    }
8  }
9}

If the exports was:

1{
2  "exports": {
3    "node": {
4      "production": {
5        "import": "./dist/index.js"
6      }
7    }
8  }
9}

It will be simplified to:

1{
2  "exports": "./dist/index.js"
3}

Utilities

generateExports.normalizePath

• Type: (path: string) => string

This function can be used to normalize the path with leading ./.

For example:

1generateExports.pathCondition("foo"); // ➡️ "./foo"
2generateExports.pathCondition("./foo"); // ➡️ "./foo"
3generateExports.pathCondition("./foo.js"); // ➡️ "./foo.js"

generateExports.removeExtension

• Type: (path: string, extname?: string) => string

This function can be used to remove the extension name.

For example:

1generateExports.pathCondition("foo"); // ➡️ "foo"
2generateExports.pathCondition("./foo"); // ➡️ "./foo"
3generateExports.pathCondition("./foo.js"); // ➡️ "./foo"
4generateExports.pathCondition("./foo/bar.js"); // ➡️ "./foo/bar"

generateExports.pathCondition

• Type: (path: string, extname?: string) => string

pathCondition is a combination of normalizePath and removeExtension. This function can be used to generate either the path condition. It will remove the extension name and add ./ if the path doesn't start with ./.

For example:

1generateExports.pathCondition("foo"); // ➡️ "./foo"
2generateExports.pathCondition("./foo"); // ➡️ "./foo"
3generateExports.pathCondition("./foo.js"); // ➡️ "./foo"
4generateExports.pathCondition("./foo.js", ".js"); // ➡️ "./foo"
5generateExports.pathCondition("./foo.d.ts"); // ➡️ "./foo.d"
6generateExports.pathCondition("./foo.d.ts", ".d.ts"); // ➡️ "./foo"

To Learn More

• publint - A tool to lint your package.json.
• package.json exports

License

ViPro ©️ MIT