From 0a052c9be1dfed8b456c9cad0e3c35461614c0a3 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Fri, 17 Dec 2021 22:31:13 +0100 Subject: [PATCH] docs: initial build system build step docs Signed-off-by: Patrik Oldsberg --- docs/local-dev/cli-build-system.md | 45 +++++++++++++++++++++++++++++- 1 file changed, 44 insertions(+), 1 deletion(-) diff --git a/docs/local-dev/cli-build-system.md b/docs/local-dev/cli-build-system.md index bbcb4c2bd3..9cc7c1ea8c 100644 --- a/docs/local-dev/cli-build-system.md +++ b/docs/local-dev/cli-build-system.md @@ -152,4 +152,47 @@ variables, and provided some sane default flags like `--watch` if executed within a Git repository. The by far biggest amount of work is done by the Jest configuration included -with the Backstage CLI. It both takes care of providing a default configuration +with the Backstage CLI. It both takes care of providing a default Jest +configuration, as well as allowing for configuration overrides to be defined in +each `package.json`. How this can be done in practice is discussed in the +configuration section below. + +### Building + +The primary purpose of the build process is to prepare packages for publishing, +although it is also used as part of the backend bundling process which we will +discuss below. Since it's only used in these two cases, any Backstage app that +does not use the Backend parts of the project may not need to interact with the +build process at all. It can nevertheless be useful to know how it works, since +all of the published Backstage packages are built using this process. + +The build is currently using [Rollup](https://rollupjs.org/) and executes in +complete isolation for each individual package. There are currently three +different commands in the Backstage CLI that invokes the build process, +`plugin:build`, `backend:build`, and simply `build`. The two former are +pre-configured commands for frontend and backend plugins, while the `build` +command provides more control over the output. It is likely that the two +specialized commands disappear in the future, leaving just the `build` command. + +There are three different possible outputs of the build process: JavaScript in +CommonJS module format, JavaScript in ESM format, and type declarations. Each +invocation of a build command will write one or more of these outputs to the +`dist` folder in the package, and in addition copy any asset files like +stylesheets or images. For more details on what syntax and file formats are +supported by the build process, see the transpilation section below. + +When building CommonJS or ESM output, the build commands will always use +`src/index.ts` as the entrypoint. All dependencies of the package will be marked +as external, meaning that in general it is only the contents of the `src` folder +that ends up being compiled and output to `dist`, any imported external +dependencies, even within the monorepo, will stay intact. + +The build of the type definitions works quite differently. The entrypoint of the +type definition build is the relative location of the package within the +`dist-types` folder in the project root. This means that it is important to run +type checking before building any packages with type definitions, and that +emitting type declarations must be enable in the TypeScript configuration. The +reason for the type definition build step is to strip out all types but the ones +that are exported from the package, leaving a much cleaner type definition file +and making sure that the type definitions are in sync with the generated +JavaScript.