added docs

internal-docs/scripts-and-tasks.md

@@ -31,6 +31,79 @@ Some scripts may be nested under other scripts using the colon (`:`) symbol. Thi
 - Doesn't expect another script from the same project to be run before this script.
 - If the build fails, exits with an error.
 
+### Caching builds
+
+When running tasks using [Nx](https://nx.dev/), packages and dependencies are automatically built if needed. To avoid the need to run tasks without Nx, builds are [cached](https://nx.dev/concepts/how-caching-works#how-caching-works) and should only be re-built when their source files are changed.
+
+By default, when adding new packages, builds aren't cached. In order to make a project's builds cache-able, you should follow these steps:
+
+1. Create a [`project.json` file](https://nx.dev/recipes/tips-n-tricks/integrated-in-package-based#project.json) at the root of the project.
+
+   - How:
+
+     - You can copy this scaffold (replace all instances of "turtle" with the name of your project):
+
+       ```json
+       {
+         "name": "turtle",
+         "$schema": "../../node_modules/nx/schemas/project-schema.json",
+         "namedInputs": {},
+         "targets": {
+           "cached:build": {
+             "executor": "nx:run-commands",
+             "options": {
+               "commands": [
+                 "rimraf ./dist",
+                 "mkdir ./dist",
+                 "echo \"hello\" > ./dist/hello.txt",
+                 "cp ./dist/hello.txt ./dist/world.txt"
+               ],
+               "parallel": false,
+               "cwd": "packages/turtle"
+             }
+           },
+           "build": {
+             "dependsOn": ["cached:build"],
+             "executor": "nx:noop"
+           }
+         }
+       }
+       ```
+
+2. In your new `project.json` file, adapt the "cached:build" [task](https://nx.dev/core-features/run-tasks#define-tasks) (tasks are sometimes referred to as "targets") so that it builds your project.
+
+   - Ensure it runs the correct command.
+     - How:
+       - A good place to start is by looking at the [`nx:run-commands` executor's documentation](https://nx.dev/packages/nx/executors/run-commands).
+       - Make sure to prefix commands that come from dependencies with "npx ".
+   - Do not rename it.
+     - Why:
+       - The name of the task must be "cached:build" since Nx only caches tasks whose name is part of the [cacheable operations](https://nx.dev/nx-cloud/reference/config#cacheable-operations). We defined "cached:build" as a cacheable operation in [`nx.json`](/nx.json).
+   - Define the correct [inputs](https://nx.dev/concepts/more-concepts/customizing-inputs#customizing-inputs-and-named-inputs).
+     - When:
+       - If some files which aren't part of the default inputs (defined in [`nx.json`](/nx.json)) and affect the final build output are outside the project's directory.
+       - If some auto-generated files from a different task or a different project are part of the current directory.
+       - If you **really** want to be selective about which changes in your project's directory will invalidate their cache.
+     - How:
+       - If possible, only customize the `buildInputs` [named inputs](https://nx.dev/concepts/more-concepts/customizing-inputs#customizing-inputs-and-named-inputs).
+         - The default inputs for build tasks defined in [`nx.json`](/nx.json) uses the `buildInputs` in addition to some other files.
+       - Input glob patterns should match every file that can affect the final build output.
+     - Why:
+       - When a build task is triggered, Nx will verify if any of its inputs was changed. If none of its input was changed, it will skip re-building the package and may load its outputs from the cache.
+   - Define the correct [outputs](https://nx.dev/concepts/how-caching-works#what-is-cached).
+     - When:
+       - If the default outputs defined in [`nx.json`](/nx.json) either don't match every file generated by the task or match some files that aren't generated by the task.
+     - How:
+       - The output glob patterns should match all the files generated by the build task, and no more than that.
+       - You must also copy all these glob patterns to the `negativeBuildOutputs` [named inputs](https://nx.dev/concepts/more-concepts/customizing-inputs#customizing-inputs-and-named-inputs), but prefix them with an exclamation symbol (`!`).
+         - The default inputs defined in [`nx.json`](/nx.json) won't match files which are also matched in `negativeBuildOutputs`.
+     - Why:
+       - After Nx runs your task, it will save every file matched by the output glob patterns. The next time you run the same task, Nx may restore the files it saved.
+
+3. Replace the `build` script in your `package.json`
+   - How:
+     - Simply replace it with `nx build`.
+
 ## `dev` script
 
 - Generates all the files needed for a dependent project to run.