docs/tooling: document caching options

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>

docs/tooling/cli/02-build-system.md

@@ -559,6 +559,14 @@ The overrides in a single `package.json` may for example look like this:
   },
 ```
 
+## Caching
+
+Caching is used sparingly throughout the Backstage build system. It is always used as a way to squeeze out a little bit of extra performance, rather than requirement to keep things fast. The following is a list of places where optional caching is available:
+
+- **TypeScript** - The default `tsconfig.json` used by Backstage projects has `incremental` set to `true`, which enables local caching of type checking results. It is however generally not recommended in CI, where `yarn tsc:full` is preferred, which sets `--incremental false`.
+- **Linting** - The `backstage-cli repo lint` command has a `--cache` flag that enables caching of successful linting results. This is done at the package level, meaning that if a package has not been changed since the last lint run and it was successful, the linting will be skipped. This is recommended to be used in CI, but not during local development.
+- **Webpack** - It is possible to enable experimental caching of frontend package builds using the `BACKSTAGE_CLI_EXPERIMENTAL_BUILD_CACHE` environment variable. This will enable the Webpack filesystem cache.
+
 ### Debugging Jest Tests
 
 For your productivity working with unit tests it's quite essential to have your debugging configured in IDE. It will help you to identify the root cause of the issue faster.