jaydenseric/find-unused-exports

A Node.js CLI and equivalent JS API to find unused ECMAScript module exports in a project.

find-unused-exports

A Node.js CLI and equivalent JS API to find unused ECMAScript module exports in a project.

To achieve this the whole project is analyzed at once, something ESLint can’t do as it lints files in isolation.

• The npx find-unused-exports script is handy for finding redundant code to remove in legacy projects.
• Use the CLI command find-unused-exports in package test scripts, so that CI can prevent the addition of redundant code.

Installation

To install find-unused-exports with npm, run:

npm install find-unused-exports --save-dev

Then, either use the CLI command find-unused-exports or import and use the function findUnusedExports.

Ignoring unused exports

.gitignore files are used to ignore whole files or directories. This is useful for ignoring:

• Third party modules, e.g. node_modules.
• Compiled files, e.g. .next or dist.

Special comments can be used anywhere in a module to ignore all or specific unused exports. This is useful for ignoring intentionally unused exports intended to be imported from external code, e.g.

• For published packages, the public exports.
• For Next.js projects, the default exports in pages directory modules.

Examples

How to ignore all unused exports:

// ignore unused exports
export const a = true;
export default true;

How to ignore specific unused exports:

// ignore unused exports b, default
export const a = true;
export const b = true;
export default true;

Multiple comments can be used:

// ignore unused exports a
export const a = true;

// ignore unused exports b
export const b = true;

Comments are case-insensitive, except for the export names:

// iGnOrE UnUsEd eXpOrTs default

Line or block comments can be used:

/* ignore unused exports */

Requirements

Supported runtime environments:

• Node.js versions ^18.18.0 || ^20.9.0 || >=22.0.0.

Projects must configure TypeScript to use types from the ECMAScript modules that have a // @ts-check comment:

• compilerOptions.allowJs should be true.
• compilerOptions.maxNodeModuleJsDepth should be reasonably large, e.g. 10.
• compilerOptions.module should be "node16" or "nodenext".

CLI

Command find-unused-exports

Finds unused ECMAScript module exports in a project. If some are found, it reports them to stderr and exits with a 1 error status. .gitignore files are used to ignore files.

It implements the function findUnusedExports.

Arguments

Argument	Default	Description
--module-glob	"**/{!(*.d).mts,!(*.d).cts,!(*.d).ts,*.{mjs,cjs,js,jsx,tsx}}"	Module file glob pattern.
--resolve-file-extensions		File extensions (without the leading ., multiple separated with , in preference order) to automatically resolve in extensionless import specifiers. Import specifier file extensions are mandatory in Node.js; if your project resolves extensionless imports at build time (e.g. Next.js, via webpack) mjs,js might be appropriate.
--resolve-index-files		Should directory index files be automatically resolved in extensionless import specifiers. Node.js doesn’t do this by default; if your project resolves extensionless imports at build time (e.g. Next.js, via webpack) this argument might be appropriate. This argument only works if the argument --resolve-file-extensions is used.

Examples

Using npx in a standard Node.js project:

npx find-unused-exports

Using npx in a typical webpack project that has ESM in .js files, extensionless import specifiers, and index.js files:

npx find-unused-exports --module-glob "**/*.js" --resolve-file-extensions js --resolve-index-files

package.json scripts for a project that also uses eslint and prettier:

{
  "scripts": {
    "eslint": "eslint .",
    "prettier": "prettier -c .",
    "find-unused-exports": "find-unused-exports",
    "test": "npm run eslint && npm run prettier && npm run find-unused-exports",
    "prepublishOnly": "npm test"
  }
}

Exports

The npm package find-unused-exports features optimal JavaScript module design. It doesn’t have a main index module, so use deep imports from the ECMAScript modules that are exported via the package.json field exports:

• findUnusedExports.mjs

find-unused-exports's Issues

Respect `.gitignore` files above the CWD

Hi!

I tried to run this and got:

Error running find-unused-exports:

  SyntaxError: /home/userA/code/projectA/server/node_modules/mkdirp/bin/cmd.js: 'return' outside of function. (13:4)

    11 | if (argv.help) {
    12 |     fs.createReadStream(__dirname + '/usage.txt').pipe(process.stdout);
  > 13 |     return;
       |     ^
    14 | }

Support import maps

Support for aliases would make this tool useful in my project.

Possible false positive bug with destructured named exports

Reproduction: https://github.com/dburles/find-unused-exports-issue

I found that exporting named exports in this way results in a false positive with no exports named:

index.js
  
1 unused export in 1 module.

Error running find-unused-exports

Error -
jest-eslint.config.js: preset-react-app: Error in options
Required env missing. Specify env either using NODE_ENV environment variable or 'env' option. Valid values for env are [development,production,test]

Is there a way to set global ignore unused values? (default)

We use export default for a number of our functions (apparently 137 of them), and I was wondering if there was a way to set up global ignore values?

Either through the CLI: find-unused-exports --ignore-unused default or via a config file?