{"id":20659330,"url":"https://github.com/ncpa0cpl/nodepack","last_synced_at":"2025-04-19T14:13:54.294Z","repository":{"id":58448154,"uuid":"528465241","full_name":"ncpa0cpl/nodepack","owner":"ncpa0cpl","description":"Simple packaging script for node libraries based on ESBuild","archived":false,"fork":false,"pushed_at":"2024-06-24T10:08:20.000Z","size":65207,"stargazers_count":3,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-05T22:32:41.694Z","etag":null,"topics":["cjs","esm","mjs","nodejs","typescript"],"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/ncpa0cpl.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"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}},"created_at":"2022-08-24T14:41:06.000Z","updated_at":"2023-03-12T17:18:53.000Z","dependencies_parsed_at":"2024-06-21T04:16:53.648Z","dependency_job_id":"2f94a860-2826-4d45-8612-ed8946682dd5","html_url":"https://github.com/ncpa0cpl/nodepack","commit_stats":{"total_commits":62,"total_committers":5,"mean_commits":12.4,"dds":0.3709677419354839,"last_synced_commit":"7a241c4c89d218e223e4b871b342b1675661e7d4"},"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ncpa0cpl%2Fnodepack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ncpa0cpl%2Fnodepack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ncpa0cpl%2Fnodepack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ncpa0cpl%2Fnodepack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ncpa0cpl","download_url":"https://codeload.github.com/ncpa0cpl/nodepack/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249709606,"owners_count":21313949,"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":["cjs","esm","mjs","nodejs","typescript"],"created_at":"2024-11-16T18:33:57.913Z","updated_at":"2025-04-19T14:13:54.275Z","avatar_url":"https://github.com/ncpa0cpl.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# nodepack\n\n## Features\n\n- Fast (uses ESBuild under the hood)\n- Build your project for CommonJS modules, ESModules and legacy environments all at once\n- Generate TypeScript declarations along with the compiled JavaScript\n- Generate TypeScript declarations for JSON files\n- Path aliases out of the box, along with import rewriting in `.d.ts` files\n\n## Table of contents\n\n1. [Installation](#installation)\n2. [Usage](#usage)\n3. [Options](#options)\n   1. [target](#target)\n   2. [srcDir](#srcdir)\n   3. [outDir](#outdir)\n   4. [formats](#formats)\n   5. [bundle](#bundle)\n   6. [entrypoint](#entrypoint)\n   7. [external](#external)\n   8. [exclude](#exclude)\n   9. [replaceImports](#replaceImports)\n   10. [compileVendors](#compileVendors)\n   11. [preset](#preset)\n   12. [declarations](#declarations)\n   13. [decoratorsMetadata](#decoratorsMetadata)\n   14. [extMapping](#extMapping)\n   15. [isomorphicImports](#isomorphicImports)\n   16. [pathAliases](#pathAliases)\n   17. [tsConfig](#tsConfig)\n   18. [watch](#watch)\n   19. [esbuildOptions](#esbuildOptions)\n\n## Installation\n\n1. Intall this package and `esbuild` using _yarn_ or _npm_:\n\n   ```sh\n     npm i -D esbuild @ncpa0cpl/nodepack\n   ```\n\n   or\n\n   ```sh\n     yarn add -D esbuild @ncpa0cpl/nodepack\n   ```\n\n2. (Optional) If you want to be able to generate TypeScript declarations also install `typescript`.\n3. (Optional) If you want to be able to generate TypeScript declarations for JSON files also install `json-to-ts` package.\n\n## Usage\n\n\u003e **\u003cspan style=\"color:red\"\u003eImportant\u003c/span\u003e**\n\u003e\n\u003e Make sure to explicitly set all type exports/imports as a type exports/imports in your project files. (use eslint rules to enforce this rule: [for exports](https://github.com/typescript-eslint/typescript-eslint/blob/main/packages/eslint-plugin/docs/rules/consistent-type-exports.md) and [for imports](https://github.com/typescript-eslint/typescript-eslint/blob/main/packages/eslint-plugin/docs/rules/consistent-type-imports.md))\n\u003e\n\u003e All exports and imports of TS types that are not marked as such will be left over in the compiled JS files, which will lead to runtime errors.\n\nExecute this JavaScript script to build the files for the selected formats:\n\n```ts\nimport { build } from \"@ncpa0cpl/nodepack\";\nimport process from \"node:process\";\nimport path from \"path\";\n\nbuild({\n  target: \"es6\",\n  srcDir: path.resolve(process.cwd(), \"src\"),\n  outDir: path.resolve(process.cwd(), \"dist\"),\n  formats: [\"cjs\", \"esm\", \"legacy\"],\n  declarations: true,\n});\n```\n\nThen for node environments to correctly resolve the build files depending on the environment include the following in your `package.json` file:\n\n```js\n{\n  // main entrypoint for legacy environments that do not support the `exports` field\n  \"main\": \"./dist/legacy/index.js\",\n  // main type declarations entrypoint for legacy environments that do not support the `exports` field\n  \"types\": \"./dist/types/index.d.ts\",\n  \"exports\": {\n    \".\": {\n      // main type declarations entrypoint\n      \"types\": \"./dist/types/index.d.ts\",\n      // main entrypoint for environments that use the ESModules\n      \"import\": \"./dist/esm/index.mjs\",\n      // main entrypoint for environments that use the CommonJS modules\n      \"require\": \"./dist/cjs/index.cjs\"\n    }\n  }\n}\n```\n\n#### Raw JSON\n\n```json\n{\n  \"main\": \"./dist/legacy/index.js\",\n  \"types\": \"./dist/types/index.d.ts\",\n  \"exports\": {\n    \".\": {\n      \"types\": \"./dist/types/index.d.ts\",\n      \"import\": \"./dist/esm/index.mjs\",\n      \"require\": \"./dist/cjs/index.cjs\"\n    }\n  }\n}\n```\n\n## Options\n\n#### target\n\n**(required)**\n\nTarget environment for the generated JavaScript.\n\n#### srcDir\n\n**(required)**\n\nAbsolute path to the directory containing the source files.\n\n#### outDir\n\n**(required)**\n\nAbsolute path to the directory to which the compiled source should be outputted to.\n\n#### formats\n\n**(required)**\n\nList of format types that should be outputted.\n\n- `cjs` format - CommonJS module format with a .cjs file extension.\n- `esm` format - ES module format with a .mjs file extension.\n- `legacy` format - CommonJS module format with a .js file extension.\n\n#### bundle\n\n**(optional)**\n_Default: false_\n\nWhen enabled, the entire program will be bundled into a single file, with the exception of files and packages marked as external or as vendors.\n\n`entrypoint` option must be provided when bundle is enabled.\n\n#### entrypoint\n\n**(optional)**\n\nFilename of the entrypoint file, relative to the `srcDir`. This option is only used when `bundle` is enabled.\n\n#### external\n\n**(optional)**\n_Default: []_\n\nList of packages that should be excluded from compilation. Imports of those packages will be left as is, unless `replaceImports` for that package is specified.\n\n#### exclude\n\n**(optional)**\n_Default: []_\n\nRegex patterns used to exclude files from compilation.\n\n#### replaceImports\n\n**(optional)**\n\nAllows to define import mappings, for example if given this `replaceImports` option: `{ eventemitter2: \"eventemitter3\" }`, all imports of eventemitter2 in the source will be replaced with an import of eventemitter3 in the output.\n\n#### compileVendors\n\n**(optional)**\n\nList of external packages that should be compiled along with the source files.\n\nEach specified vendor package will be compiled into a single bundle file and\nplaced inside a `_vendors` directory.\n\nIf set to `all`, all external packages will be compiled.\n\n#### preset\n\n**(optional)**\n\nCan define which presets to use for the compilation. Available presets are: `node`, `deno` and `gjs`.\n\nEach preset includes a set of package names that should be added to the `external` option for the given target environment.\n\n#### declarations\n\n**(optional)**\n_Default: false_\n\nIndicates if typescript declarations are to be generated. If set to true, `.d.ts` files will be generated along the JavaScript files, if set to `only` no JavaScript will be emitted, only the declarations.\n\nTo be able to generate declarations, TypeScript package must be installed.\n\n#### decoratorsMetadata\n\n**(optional)**\n_Default: false_\n\nWether to generate metadata along with the typescript decorators, this requires to transpile files first with a TypeScript compiler before compiling with esbuild and will make the build process noticeably slower.\n\n#### extMapping\n\n**(optional)**\n\nAllows to customize the file extension of the outputted files. This is useful for custom esbuild loaders, like a file loader.\n\nIf you want to map given extension to the used format (`.cjs`, `.mjs` or `.js`), you can use a `%FORMAT%` wildcard instead of a extension.\n\n##### Example\n\nTo map all `.png` files to the javascript extension depending on which format it is generated for:\n\n```ts\nimport { build } from \"@ncpa0cpl/nodepack\";\n\nbuild({\n  // ...\n  formats: [\"cjs\", \"esm\", \"legacy\"],\n  extMapping: {\n    \".png\": \"%FORMAT%\",\n  },\n  esbuildOptions: {\n    loader: {\n      \".png\": \"dataurl\",\n    },\n  },\n});\n```\n\nWith the above options, a source with a `./src/icon.png` file would get transformed to:\n\n```\ndist\n|- cjs\n|--|- icon.cjs\n|- esm\n|--|- icon.mjs\n|- legacy\n|--|- icon.js\n```\n\nTo statically map `.png` file to other extension just replace the `%FORMAT%` with the desired extension.\n\n#### isomorphicImports\n\n**(optional)**\n\nFiles that should get their imports replaced to other path, depending on the extension for which it is compiled.\n\nAll path provided should be relative to the `srcDir`.\n\nIf no import is defined for a format, the import will be left as is.\n\nSince some of the features in Node are only available for ESModules or CommonJS modules (for example `__filename` or `import.meta`), it might be helpful to have different file be imported depending on which module type the program is using.\n\nTo define a different index file for each of the compiled formats:\n\n```ts\nbuild({\n  // ...\n  isomorphicImports: {\n    \"./index.ts\": {\n      mjs: \"./index.esm.ts\",\n      cjs: \"./index.cjs.ts\",\n      js: \"./index.legacy.ts\",\n    },\n  },\n});\n```\n\n#### pathAliases\n\n**(optional)**\n\nA map of path aliases.\n\nEach path alias must end with a `/*`, and each alias value must be a path relative to the `srcDir`, start with a `./` and end with a `/*`.\n\nPath aliases are used to replace imports in JavaScript files for all formats and TypeScript declaration files.\n\n##### Example\n\n```ts\nimport { build } from \"@ncpa0cpl/nodepack\";\n\nbuild({\n  // ...\n  pathAliases: {\n    \"@Utils/*\": \"./Utils/*\",\n  },\n});\n```\n\n#### tsConfig\n\n**(optional)**\n\nAbsolute path to the TypeScript config file.\n\n#### watch\n\n**(optional)**\n_Default: false_\n\nWhen watch mode is enabled, nodepack will listen for changes on the file system and rebuild whenever a file changes.\n\n_This option is currently experimental and you may encounter bugs if you use it._\n\n#### esbuildOptions\n\n**(optional)**\n\nOptions to pass to the `esbuild` compiler. ([See available options here](https://esbuild.github.io/api/#simple-options)), most of the options are available but some can potentially break the compilation process.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fncpa0cpl%2Fnodepack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fncpa0cpl%2Fnodepack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fncpa0cpl%2Fnodepack/lists"}