{"id":13561601,"url":"https://github.com/Septh/rollup-plugin-node-externals","last_synced_at":"2025-04-03T17:31:09.294Z","repository":{"id":55923373,"uuid":"167889480","full_name":"Septh/rollup-plugin-node-externals","owner":"Septh","description":"A Rollup/Vite plugin that automatically declares NodeJS built-in modules and npm dependencies as 'external'","archived":false,"fork":false,"pushed_at":"2024-12-15T03:54:55.000Z","size":580,"stargazers_count":88,"open_issues_count":1,"forks_count":5,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-28T16:51:40.061Z","etag":null,"topics":["external","module","node","plugin","rollup"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Septh.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":null,"patreon":"Septh","open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"lfx_crowdfunding":null,"custom":["https://paypal.me/septh07"]}},"created_at":"2019-01-28T02:57:04.000Z","updated_at":"2025-01-30T17:10:41.000Z","dependencies_parsed_at":"2024-01-16T18:59:43.615Z","dependency_job_id":"5ec36a32-336a-49b2-b05c-a8e9c5653b85","html_url":"https://github.com/Septh/rollup-plugin-node-externals","commit_stats":{"total_commits":97,"total_committers":5,"mean_commits":19.4,"dds":0.6082474226804124,"last_synced_commit":"c8bd534d1a9ef73d6bf6213118f648e6e8a1365a"},"previous_names":[],"tags_count":35,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Septh%2Frollup-plugin-node-externals","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Septh%2Frollup-plugin-node-externals/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Septh%2Frollup-plugin-node-externals/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Septh%2Frollup-plugin-node-externals/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Septh","download_url":"https://codeload.github.com/Septh/rollup-plugin-node-externals/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246947829,"owners_count":20859322,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["external","module","node","plugin","rollup"],"created_at":"2024-08-01T13:00:58.997Z","updated_at":"2025-04-03T17:31:09.288Z","avatar_url":"https://github.com/Septh.png","language":"TypeScript","funding_links":["https://patreon.com/Septh","https://paypal.me/septh07"],"categories":["TypeScript"],"sub_categories":[],"readme":"\u003cp\u003e\r\n\r\n![NPM Version](https://img.shields.io/npm/v/rollup-plugin-node-externals?label=latest)\r\n![Rollup 4.0](https://img.shields.io/badge/Rollup-%3E%3D4.0.0-orange)\r\n![Vite 5.0](https://img.shields.io/badge/Vite-%3E%3D5.0.0-purple)\r\n![NPM Downloads](https://img.shields.io/npm/dm/rollup-plugin-node-externals)\r\n![NPM License](https://img.shields.io/npm/l/rollup-plugin-node-externals)\r\n\r\n\u003c/p\u003e\r\n\r\n# rollup-plugin-node-externals\r\nA Rollup/Vite plugin that automatically declares NodeJS built-in modules as `external`. Also handles npm dependencies, devDependencies, peerDependencies and optionalDependencies.\r\n\r\nWorks in npm/yarn/pnpm/lerna monorepos too!\r\n\r\n\r\n## Why you need this\r\n\u003cdetails\u003e\u003csummary\u003e(click to read)\u003c/summary\u003e\r\n\r\nBy default, Rollup doesn't know a thing about NodeJS, so trying to bundle simple things like `import path from 'node:path'` in your code generates an `Unresolved dependencies` warning.\r\n\r\nThe solution here is quite simple: you must tell Rollup that the `node:path` module is in fact _external_. This way, Rollup won't try to bundle it in and rather leave the `import` statement as is (or translate it to a `require()` call if bundling for CommonJS).\r\n\r\nHowever, this must be done for each and every NodeJS built-in you happen to use in your program: `node:path`, `node:os`, `node:fs`, `node:url`, etc., which can quickly become cumbersome when done manually.\r\n\r\nSo the primary goal of this plugin is simply to automatically declare all NodeJS built-in modules as external.\r\n\r\nAs an added bonus, this plugin will also allow you to declare your dependencies (as per your local or monorepo `package.json` file(s)) as external.\r\n\u003c/details\u003e\r\n\r\n## Requirements\r\n- Rollup \u003e= 4 or Vite \u003e= 5\r\n- NodeJS \u003e= 21\r\n\r\n\r\n## Installation\r\nUse your favorite package manager. Mine is [npm](https://www.npmjs.com).\r\n\r\n```sh\r\nnpm install --save-dev rollup-plugin-node-externals\r\n```\r\n\r\n\r\n## Usage\r\n\r\n### Import\r\nThe plugin is available both as the default export and as a named export:\r\n\r\n```js\r\nimport nodeExternals from 'rollup-plugin-node-externals'\r\n```\r\n\r\nand\r\n\r\n```js\r\nimport { nodeExternals } from 'rollup-plugin-node-externals'\r\n```\r\n\r\nwill both work.\r\n\r\n\r\n### Options\r\nYou generally want to have your **runtime dependencies** (those that will be imported/required at runtime) listed under `dependencies` in `package.json`, and your **development dependencies** (those that should be bundled in by Rollup) listed under `devDependencies`.\r\n\r\nIf you follow this simple rule, then the default settings are just what you need:\r\n\r\n```js\r\n// rollup.config.js\r\n\r\nexport default {\r\n  ...\r\n  plugins: [\r\n    nodeExternals(),\r\n  ]\r\n}\r\n```\r\n\r\nThis will bundle your `devDependencies` in while leaving your `dependencies`, `peerDependencies` and `optionalDependencies` external.\r\n\r\nShould the defaults not suit your case, here is the full list of options.\r\n\r\n```typescript\r\nimport nodeExternals from 'rollup-plugin-node-externals'\r\n\r\nexport default {\r\n  ...\r\n  plugins: [\r\n    nodeExternals({\r\n\r\n      // Make node builtins external. Default: true.\r\n      builtins?: boolean\r\n\r\n      // node: prefix handing for importing Node builtins. Default: 'add'.\r\n      builtinsPrefix?: 'add' | 'strip' | 'ignore'\r\n\r\n      // The path(s) to your package.json. See below for default.\r\n      packagePath?: string | string[]\r\n\r\n      // Make pkg.dependencies external. Default: true.\r\n      deps?: boolean\r\n\r\n      // Make pkg.devDependencies external. Default: false.\r\n      devDeps?: boolean\r\n\r\n      // Make pkg.peerDependencies external. Default: true.\r\n      peerDeps?: boolean\r\n\r\n      // Make pkg.optionalDependencies external. Default: true.\r\n      optDeps?: boolean\r\n\r\n      // Modules to force include in externals. Default: [].\r\n      include?: string | RegExp | (string | RegExp)[]\r\n\r\n      // Modules to force exclude from externals. Default: [].\r\n      exclude?: string | RegExp | (string | RegExp)[]\r\n    })\r\n  ]\r\n}\r\n```\r\n\r\n#### builtins?: boolean = true\r\nSet the `builtins` option to `false` if you'd like to use some shims/polyfills for those. You'll most certainly need [an other plugin](https://github.com/ionic-team/rollup-plugin-node-polyfills) as well.\r\n\r\n#### builtinsPrefix?: 'add' | 'strip' | 'ignore' = 'add'\r\nHow to handle the `node:` scheme used in recent versions of Node (i.e., `import path from 'node:path'`).\r\n- If `add` (the default, recommended), the `node:` scheme is always added. In effect, this dedupes your imports of Node builtins by homogenizing their names to their schemed version.\r\n- If `strip`, the scheme is always removed. In effect, this dedupes your imports of Node builtins by homogenizing their names to their unschemed version. Schemed-only builtins like `node:test` are not stripped.\r\n- `ignore` will simply leave all builtins imports as written in your code.\r\n\u003e _Note that scheme handling is always applied, regardless of the `builtins` options being enabled or not._\r\n\r\n#### packagePath?: string | string[] = []\r\nIf you're working with monorepos, the `packagePath` option is made for you. It can take a path, or an array of paths, to your package.json file(s). If not specified, the default is to start with the current directory's package.json then go up scan for all `package.json` files in parent directories recursively until either the root git directory is reached, the root of the monorepo is reached, or no other `package.json` can be found.\r\n\r\n#### deps?: boolean = true\u003cbr\u003edevDeps?: boolean = false\u003cbr\u003epeerDeps?: boolean = true\u003cbr\u003eoptDeps?: boolean = true\r\nSet the `deps`, `devDeps`, `peerDeps` and `optDeps` options to `false` to prevent the corresponding dependencies from being externalized, therefore letting Rollup bundle them with your code.\r\n\r\n#### include?: string | RegExp | (string | RegExp)[] = []\r\nUse the `include` option to force certain dependencies into the list of externals, regardless of other settings:\r\n\r\n```js\r\nnodeExternals({\r\n  deps: false,                // Deps will be bundled in\r\n  include: 'fsevents'         // Except for fsevents\r\n})\r\n```\r\n\r\n#### exclude?: string | RegExp | (string | RegExp)[] = []\r\nConversely, use the `exclude` option to remove certain dependencies from the list of externals, regardless of other settings:\r\n\r\n```js\r\nnodeExternals({\r\n  deps: true,                 // Keep deps external\r\n  exclude: 'electron-reload'  // Yet we want `electron-reload` bundled in\r\n})\r\n```\r\n\r\n\r\n## Notes\r\n\r\n### 1/ This plugin is smart\r\n- Falsy values in `include` and `exclude` are silently ignored. This allows for conditional constructs like `exclude: process.env.NODE_ENV === 'production' \u0026\u0026 'my-prod-only-dep'`.\r\n- Subpath imports are supported with regexes, meaning that `include: /^lodash/` will externalize `lodash` and also `lodash/map`, `lodash/merge`, etc.\r\n\r\n### 2/ This plugin is not _that_ smart\r\nIt uses an exact match against your imports _as written in your code_. No resolving of path aliases or substitutions is made:\r\n\r\n```js\r\n// In your code, say '@/lib' is an alias for source/deep/path/to/some/lib:\r\nimport something from '@/lib'\r\n```\r\n\r\nIf you don't want `lib` bundled in, then write:\r\n\r\n```js\r\n// In rollup.config.js:\r\nnodeExternals({\r\n    include: '@/lib'\r\n})\r\n```\r\n\r\n### 3/ Order matters\r\nIf you're also using [`@rollup/plugin-node-resolve`](https://github.com/rollup/plugins/tree/master/packages/node-resolve/#readme), make sure this plugin comes _before_ it in the `plugins` array:\r\n\r\n```js\r\nimport nodeExternals from 'rollup-plugin-node-externals'\r\nimport nodeResolve from '@rollup/plugin-node-resolve'\r\n\r\nexport default {\r\n  ...\r\n  plugins: [\r\n    nodeExternals(),\r\n    nodeResolve(),\r\n  ]\r\n}\r\n```\r\n\r\nNote that as of version 7, this plugin's `resolveId` hook has a `order: 'pre'` property that will make Rollup call it very early in the module resolution process. Nevertheless, it is best to always make this plugin the first one in the `plugins` array.\r\n\r\n### 4/ Rollup rules\r\nRollup's own `external` configuration option always takes precedence over this plugin. This is intentional.\r\n\r\n### 5/ Using with Vite\r\nWhile this plugin has always been compatible with Vite, it was previously necessary to use the following `vite.config.js` to make it work reliably in every situation:\r\n\r\n```js\r\nimport { defineConfig } from 'vite'\r\nimport nodeExternals from 'rollup-plugin-node-externals'\r\n\r\nexport default defineConfig({\r\n  ...\r\n  plugins: [\r\n    { enforce: 'pre', ...nodeExternals() },\r\n    // other plugins follow\r\n  ]\r\n})\r\n```\r\n\r\nSince version 7.1, this is no longer necessary and you can use the normal syntax instead. You still want to keep this plugin early in the `plugins` array, though.\r\n\r\n```js\r\nimport { defineConfig } from 'vite'\r\nimport nodeExternals from 'rollup-plugin-node-externals'\r\n\r\nexport default defineConfig({\r\n  ...\r\n  plugins: [\r\n    nodeExternals()\r\n    // other plugins follow\r\n  ]\r\n})\r\n```\r\n\r\n\r\n## Breaking changes\r\n\r\n### Breaking changes in version 8\r\n- Removed support for Rollup 3.\r\n- Removed `order: pre` from resolveId hook (see #33). Might force users who relied on this, to make sure this plugin comes first in the plugins array.\r\n\r\n### Breaking changes in previous versions\r\n\u003cdetails\u003e\u003csummary\u003ePrevious versions -- click to expand\u003c/summary\u003e\r\n\r\n### Breaking changes in version 7\r\n- This package now only supports the [Maintenance, LTS and Current versions](https://github.com/nodejs/Release#release-schedule) of Node.js.\r\n- The previously undocumented `externals` named export has been removed.\r\n\r\n#### Breaking changes in version 6\r\n- This package is now esm-only and requires NodeJS v16+.\u003cbr /\u003e*If you need CommonJS or older NodeJS support, please stick to v5.*\r\n- This plugin now has a **peer-dependency** on Rollup `^3.0.0 || ^4.0.0`.\u003cbr /\u003e*If you need Rollup 2 support, please stick to v5.*\r\n\r\n#### Breaking changes in version 5\r\n- In previous versions, the `devDeps` option defaulted to `true`.\u003cbr\u003eThis was practical, but often wrong: devDependencies are meant just for that: being used when developping. Therefore, the `devDeps` option now defaults to `false`, meaning Rollup will include them in your bundle.\r\n- As anticipated since v4, the `builtinsPrefix` option now defaults to `'add'`.\r\n- The deprecated `prefixedBuiltins` option has been removed. Use `builtinsPrefix` instead.\r\n- `rollup-plugin-node-externals` no longer depends on the Find-Up package (while this is not a breaking change per se, it can be in some edge situations).\r\n- The plugin now has a _peer dependency_ on `rollup ^2.60.0 || ^3.0.0`.\r\n\r\n#### Breaking changes in version 4\r\n- In previous versions, the `deps` option defaulted to `false`.\u003cbr\u003eThis was practical, but often wrong: when bundling for distribution, you want your own dependencies to be installed by the package manager alongside your package, so they should not be bundled in the code. Therefore, the `deps` option now defaults to `true`.\r\n- Now requires Node 14 (up from Node 12 for previous versions).\r\n- Now has a _peer dependency_ on `rollup ^2.60.0`.\r\n\r\n\u003c/details\u003e\r\n\r\n\r\n## License\r\nMIT\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSepth%2Frollup-plugin-node-externals","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FSepth%2Frollup-plugin-node-externals","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSepth%2Frollup-plugin-node-externals/lists"}