This plugin traces and copies only the node_modules that are actually required at runtime for your built output — powered by @vercel/nft.

Bundling external dependencies can sometimes fail or cause issues, especially when modules rely on relative paths, native bindings, or dynamic imports.

To solve this, the plugin analyzes your build output, traces its runtime dependencies, and copies a tree-shaken, deduplicated, and runtime-only subset of node_modules into dist/node_modules. The result is a minimal, self-contained distribution directory that just works.

Originally extracted from Nitro and used for optimizing nf3 package dist itself!

import { traceNodeModules } from "nf3";

await traceNodeModules(["./index.mjs"], {
  //   outDir: "dist",
  // chmod: 0o755,
  // writePackageJson: true,
  // traceAlias: {},
  // hooks: {},
  // nft: {}, // https://github.com/vercel/nft#options
});

import { externals } from "nf3/plugin";

export default {
  plugins: [
    externals({
      // rootDir: ".",
      // conditions: ["node", "import", "default"],
      // include: [/^@my-scope\//],
      // exclude: ["fsevents"],
      // traceInclude: ["some-lib"],
      // trace: {
      //   fullTraceInclude: ["some-lib"],
      // }
    }),
  ],
};

By default, only files detected by @vercel/nft are included in the output. Some packages may require all their files to be present at runtime (e.g., packages with dynamic requires or asset files).

Use fullTraceInclude to specify package names that should have all files copied to the output:

rollupNodeFileTrace({
  trace: {
    fullTraceInclude: ["some-package", "@scope/another-package"],
  },
});

After the Rollup plugin traces the required files, traceNodeModules processes them into an optimized node_modules output.

Each phase can be extended through hooks:

rollupNodeFileTrace({
  hooks: {
    traceStart: (files) => {},
    traceResult: (result) => {},
    tracedFiles: (files) => {},
    tracedPackages: (packages) => {},
  },
});

Before writing files, you can transform some of them.

Example:

import { minify } from "oxc-minify";

rollupNodeFileTrace({
  transform: [
    {
      filter: (id) => /\.[mc]?js$/.test(id),
      handler: (code, id) => minify(id, code, {}).code,
    },
  ],
});

NF3 exports a list of known packages that include native code and require platform-specific builds.

These packages cannot be bundled and should be traced as external dependencies most of the time and often need tracing.

import { NodeNativePackages } from "nf3/db";

NF3 also exports a list of packages that must be externalized rather than bundled, due to bundler compatibility issues with their module format or dynamic imports.

import { NonBundleablePackages } from "nf3/db";

Published under the MIT license.