The source code build mode is used in the monorepo development scenario, allowing developers to directly reference the source code of other sub-projects within the monorepo for development.
In 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.
For example, the monorepo contains an app application and a lib:
The app is built using Modern.js and relies on some methods from the lib:
When using artifact referencing, the current project references the artifacts built from other sub-projects.
In 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.
The advantages of this approach are:
The disadvantages are:
When using source code referencing, the current project references the source code of other sub-projects for building.
In the example mentioned earlier, when you enable the source code build mode and add the relevant configuration in the lib
directory, Modern.js 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.
The advantages of this approach are:
The disadvantages are:
You can enable source code build mode by setting experiments.sourceBuild to true
.
When the source code build mode is enabled, the Modern.js 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.
For example, in the following example, when the lib package is referenced, the ./src/index.ts
file will be read for building:
If the sub-project uses exports field, you also need to add the source
field in the exports
field.
In a TypeScript project, you need to use the capability provided by TypeScript called Project Reference. It helps you develop source code more effectively.
Project reference provides the following capabilities:
tsconfig.compilerOptions.path
configuration of the sub-project, so that the use of aliases in the sub-project works correctly.In the example mentioned earlier, since the app project references the lib sub-project, we need to configure the composite
and references
options in the app project's tsconfig.json
file and point them to the corresponding relative directory of lib:
After adding these two options, the project reference is already configured. You can restart VS Code to see the effects of the configuration.
Note 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.
If you want to learn more about project reference, please refer to the official documentation on TypeScript - Project References.
When using source code build mode, there are a few things to keep in mind:
source
field from the sub-project's package.json and debug using the built artifacts of the sub-project.composite: true
is enabled, TypeScript will generate *.tsbuildinfo
temporary files. You need to add these temporary files to the .gitignore
file.