{"id":35474665,"url":"https://github.com/rstackjs/rsbuild-plugin-source-build","last_synced_at":"2026-01-16T04:01:43.813Z","repository":{"id":252084583,"uuid":"839279781","full_name":"rstackjs/rsbuild-plugin-source-build","owner":"rstackjs","description":"An Rsbuild plugin to provide support for monorepo source code referencing.","archived":false,"fork":false,"pushed_at":"2026-01-03T18:06:57.000Z","size":191,"stargazers_count":17,"open_issues_count":3,"forks_count":1,"subscribers_count":4,"default_branch":"main","last_synced_at":"2026-01-06T16:00:28.204Z","etag":null,"topics":["rsbuild","rsbuild-plugin","rspack"],"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/rstackjs.png","metadata":{"files":{"readme":"README.md","changelog":null,"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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-08-07T09:43:34.000Z","updated_at":"2026-01-01T13:51:39.000Z","dependencies_parsed_at":"2024-12-11T02:11:44.620Z","dependency_job_id":"a7d22045-412c-41c0-b888-f556ba1a4d09","html_url":"https://github.com/rstackjs/rsbuild-plugin-source-build","commit_stats":null,"previous_names":["rspack-contrib/rsbuild-plugin-source-build","rstackjs/rsbuild-plugin-source-build"],"tags_count":3,"template":false,"template_full_name":"rstackjs/rsbuild-plugin-template","purl":"pkg:github/rstackjs/rsbuild-plugin-source-build","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rstackjs%2Frsbuild-plugin-source-build","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rstackjs%2Frsbuild-plugin-source-build/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rstackjs%2Frsbuild-plugin-source-build/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rstackjs%2Frsbuild-plugin-source-build/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rstackjs","download_url":"https://codeload.github.com/rstackjs/rsbuild-plugin-source-build/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rstackjs%2Frsbuild-plugin-source-build/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28251784,"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","status":"online","status_checked_at":"2026-01-09T02:00:07.210Z","response_time":75,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["rsbuild","rsbuild-plugin","rspack"],"created_at":"2026-01-03T12:00:40.055Z","updated_at":"2026-01-09T02:01:46.947Z","avatar_url":"https://github.com/rstackjs.png","language":"TypeScript","readme":"# @rsbuild/plugin-source-build\n\nAn Rsbuild plugin to provide support for monorepo source code referencing.\n\n`@rsbuild/plugin-source-build` allows referencing source code from other subdirectories of monorepo and performs the build and hot updates.\n\n\u003cp\u003e\n  \u003ca href=\"https://npmjs.com/package/@rsbuild/plugin-source-build\"\u003e\n   \u003cimg src=\"https://img.shields.io/npm/v/@rsbuild/plugin-source-build?style=flat-square\u0026colorA=564341\u0026colorB=EDED91\" alt=\"npm version\" /\u003e\n  \u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square\u0026colorA=564341\u0026colorB=EDED91\" alt=\"license\" /\u003e\n\u003c/p\u003e\n\nEnglish | [简体中文](./README.zh-CN.md)\n\n## Usage\n\nInstall:\n\n```bash\nnpm add @rsbuild/plugin-source-build -D\n```\n\nAdd plugin to your `rsbuild.config.ts`:\n\n```ts\n// rsbuild.config.ts\nimport { pluginSourceBuild } from \"@rsbuild/plugin-source-build\";\n\nexport default {\n  plugins: [pluginSourceBuild()],\n};\n```\n\n## Use Cases\n\nIn a monorepo, there are two main ways for projects to reference each other: **artifact referencing and source code referencing**. Let's use a simple monorepo as an example to illustrate the use case of source code referencing.\n\nFor example, the monorepo contains an app application and a lib:\n\n```ts\nmonorepo\n├── app\n└── lib\n    └── src\n        └── index.ts\n```\n\nThe app is built using Rsbuild and relies on some methods from the lib:\n\n```json\n{\n  \"name\": \"app\",\n  \"dependencies\": {\n    \"lib\": \"workspace:*\"\n  }\n}\n```\n\n### Artifact Referencing\n\n**When using artifact referencing, the current project references the artifacts built from other sub-projects.**\n\nIn the example above, the lib is written in TypeScript. Typically, we need to build the lib's code in advance to generate JavaScript artifacts so that the app can reference it correctly. When the lib's code is updated, we need to rebuild it (or use `tsc --watch`) to ensure that the app can use the latest code.\n\nThe advantages of this approach are:\n\n- The build processes of each sub-project are completely independent and can have different build configurations.\n- Build caching can be applied to individual sub-projects.\n\nThe disadvantages are:\n\n- The HMR chain becomes longer during local development.\n- The process becomes cumbersome when a project contains multiple lib packages.\n\n### Source Code Referencing\n\n**When using source code referencing, the current project references the source code of other sub-projects for building.**\n\nIn the example mentioned earlier, when you register the `@rsbuild/plugin-source-build` and add the relevant configuration in the `lib` directory, Rsbuild will automatically reference the `src/index.ts` source code of the lib. This means that you don't need to build the lib's code in advance, and when the source code of the lib is updated, it can trigger automatic hot updates for the app.\n\nThe advantages of this approach are:\n\n- The sub-project does not rely on a build tool and does not require build configurations. The code of the sub-project will be compiled by the build tool of the current project.\n- There is no need to execute the build process for the sub-projects in advance.\n- HMR is more efficient during local development.\n\nThe disadvantages are:\n\n- The current project needs to support syntax features used by sub-projects and follow the same syntax specifications, such as using a consistent version of decorator syntax. If the current project and sub-projects require different build configurations, building from source code may not be suitable.\n- The current project requires compiling more code, which may result in longer build times.\n\n### Configuring Sub-projects\n\nWhen the `@rsbuild/plugin-source-build` is registered, the Rsbuild will prioritize reading the file specified in the `source` field of the sub-project during the build process. Therefore, you need to configure the `source` field in the package.json file of the sub-project and point it to the source code file.\n\nFor example, in the following example, when the lib package is referenced, the `./src/index.ts` file will be read for building:\n\n```json title=\"package.json\"\n{\n  \"name\": \"lib\",\n  \"main\": \"./dist/index.js\",\n  \"source\": \"./src/index.ts\"\n}\n```\n\nIf the sub-project uses [exports](https://nodejs.org/api/packages.html#package-entry-points) field, you also need to add the `source` field in the `exports` field.\n\n```json title=\"package.json\"\n{\n  \"name\": \"lib\",\n  \"exports\": {\n    \".\": {\n      \"source\": \"./src/index.ts\",\n      \"default\": \"./dist/index.js\"\n    },\n    \"./features\": {\n      \"source\": \"./src/features/index.ts\",\n      \"default\": \"./dist/features/index.js\"\n    }\n  }\n}\n```\n\n### Customizing Source Field\n\nAlthough the plugin uses the `source` field by default to specify the source file, we recommend configuring a custom field through the [sourceField](#sourceField) option (for example, `@custom/source`, where `custom` can be replaced with any scope name).\n\n```ts\npluginSourceBuild({\n  sourceField: \"@custom/source\",\n});\n```\n\nThis is because some packages (such as Mobx) also define a `source` field in their `package.json`. If not distinguished, Rsbuild may mistakenly resolve the source files of those dependencies, leading to unexpected build results or type issues. By using a custom field, you can avoid such conflicts and ensure that Rsbuild behaves predictably when resolving dependencies.\n\n## Configure Project Reference\n\nIn a TypeScript project, you need to use the capability provided by TypeScript called [Project Reference](https://typescriptlang.org/docs/handbook/project-references). It helps you develop source code more effectively.\n\n### Introduction\n\nProject reference provides the following capabilities:\n\n- It allows TypeScript to correctly recognize the types of other sub-projects without the need to build them.\n- When you navigate the code in VS Code, it automatically takes you to the corresponding source code file of the module.\n- Rsbuild reads the project reference configuration and automatically recognizes the `tsconfig.compilerOptions.path` configuration of the sub-project, so that the use of aliases in the sub-project works correctly.\n\n### Example\n\nIn the example mentioned earlier, since the app project references the lib sub-project, we need to configure the `references` options in the app project's `tsconfig.json` to point to the relative directory of the lib:\n\n```json title=\"app/tsconfig.json\"\n{\n  \"references\": [\n    {\n      \"path\": \"../lib\"\n    }\n  ]\n}\n```\n\nAt the same time, we need to set `composite` to `true` in the lib project's `tsconfig.json`:\n\n```json title=\"lib/A/tsconfig.json\"\n{\n  \"compilerOptions\": {\n    \"composite\": true\n  }\n}\n```\n\nAfter adding these two options, the project reference is already configured. You can restart VS Code to see the effects of the configuration.\n\nNote that the above example is a simplified one. In real monorepo projects, there may be more complex dependency relationships. You need to add a complete `references` configuration for the functionality to work correctly.\n\n\u003e If you want to learn more about project reference, please refer to the official documentation on [TypeScript - Project References](https://typescriptlang.org/docs/handbook/project-references).\n\n## Options\n\n### sourceField\n\n- **Type:** `string`\n- **Default:** `'source'`\n\nUsed to configure the resolve field of the source code files.\n\nFor example, when configured as `@custom/source`:\n\n```ts\npluginSourceBuild({\n  sourceField: \"@custom/source\",\n});\n```\n\nIn `package.json`, the source code file path can be specified using `@custom/source`:\n\n```json title=\"package.json\"\n{\n  \"name\": \"lib\",\n  \"main\": \"./dist/index.js\",\n  \"@custom/source\": \"./src/index.ts\",\n  \"exports\": {\n    \".\": {\n      \"@custom/source\": \"./src/index.ts\",\n      \"default\": \"./dist/index.js\"\n    }\n  }\n}\n```\n\n### resolvePriority\n\n- **Type:** `'source' | 'output'`\n- **Default:** `'source'`\n\nUsed to control the priority of reading the source code or the output code.\n\nBy default, `@rsbuild/plugin-source-build` will reading the source code first, for example, in the following example, it will read the `source` field.\n\n```json title=\"package.json\"\n{\n  \"name\": \"lib\",\n  \"main\": \"./dist/index.js\",\n  \"source\": \"./src/index.ts\"\n}\n```\n\nWhen `resolvePriority` is set to `'output'`, `@rsbuild/plugin-source-build` will read the output code first, i.e., the code from the `main` or `module` field.\n\n```ts\npluginSourceBuild({\n  resolvePriority: \"output\",\n});\n```\n\n- The `exports` field in package.json is not affected by `resolvePriority`.\n- The keys order in `exports` determines the resolving order, earlier declared keys having higher priority.\n\n## Caveat\n\nWhen using `@rsbuild/plugin-source-build`, there are a few things to keep in mind:\n\n1. Ensure that the current project can compile the syntax or features used in the sub-project. For example, if the sub-project uses Stylus to write CSS, the current app needs to support Stylus compilation.\n2. Ensure that the current project has the same code syntax and features as the sub-project, such as consistent syntax versions for decorators.\n3. Source code building may have some limitations. When encountering issues, you can remove the `source` field from the sub-project's package.json and debug using the built artifacts of the sub-project.\n4. When `composite: true` is enabled, TypeScript will generate `*.tsbuildinfo` temporary files. You need to add these temporary files to the `.gitignore` file.\n\n```text title=\".gitignore\"\n*.tsbuildinfo\n```\n\n## License\n\n[MIT](./LICENSE).\n","funding_links":[],"categories":["Plugins"],"sub_categories":["Rsbuild Plugins"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frstackjs%2Frsbuild-plugin-source-build","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frstackjs%2Frsbuild-plugin-source-build","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frstackjs%2Frsbuild-plugin-source-build/lists"}