miel.truyen/nx
1
0
Fork 0
Code Issues Pull Requests Actions 5 Packages Projects Releases Wiki Activity

fixup! docs(core): improve caching feature page

Browse Source
This commit is contained in:
Juri 2024-07-29 17:34:21 +02:00 committed by Juri Strumpflohner
parent a73bbfa7bb
commit 850cedfa9f
3 changed files with 59 additions and 53 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/nx-cloud/concepts/cache-security.md
View File

@ -36,7 +36,7 @@ When an employee leaves a company, it is standard practice to change all the pas
### Skip the Cache When Creating a Deployment Artifact
In order to guarantee that cache poisoning will never affect your end users, [skip the cache](/features/cache-task-results#turn-off-or-skip-the-cache) when creating build artifacts that will actually be deployed. Skipping the cache for this one CI run is a very small performance cost, but it gives you 100% confidence that cache poisoning will not be an issue for the end users.
In order to guarantee that cache poisoning will never affect your end users, [skip the cache](/recipes/running-tasks/skipping-cache) when creating build artifacts that will actually be deployed. Skipping the cache for this one CI run is a very small performance cost, but it gives you 100% confidence that cache poisoning will not be an issue for the end users.
### Do Not Manually Share Your Local Cache

108
docs/shared/features/cache-task-results.md
View File

@ -1,10 +1,11 @@
# Cache Task Results
Rebuilding and retesting the same code repeatedly is costly. Nx offers a sophisticated and battle-tested computation caching system that ensures **code is never rebuilt twice**.
Rebuilding and retesting the same code repeatedly is costly. Nx offers a sophisticated and battle-tested computation caching system that ensures **code is never rebuilt twice**. This:
If you want to learn more about the conceptual model behind Nx's caching, read [How Caching Works](/concepts/how-caching-works).
- drastically **speeds up your task execution times** while developing locally, particularly [on CI](/ci/features/remote-cache)
- **saves you money on CI/CD costs** by reducing the number of tasks that need to be executed
## What gets cached?
Nx **restores the terminal output, along with the files and artifacts** created from running the task (e.g., your build or dist directory). If you want to learn more about the conceptual model behind Nx's caching, read [How Caching Works](/concepts/how-caching-works).
## Define Cacheable Tasks
@ -53,33 +54,28 @@ the same output. As an example, e2e test runs that hit the backend API cannot be
the result of the test run.
{% /callout %}
Now, if you run a `build` task twice, the operation will be instant the second time because it is restored from the cache.
## Enable Remote Caching
{% terminal-video src="/documentation/shared/images/caching/cache-terminal-animation.mp4" alt="Video showing the terminal output of running a build command first without cache and then with cache. The 2nd run is almost instant, taking just 18ms" /%}
By default, Nx caches task results locally. Most of the benefits from caching come on CI, where you can **share the cache between different runs**. To enable remote caching connect your workspace to [Nx Cloud](/nx-cloud) by running the following command:
Nx restores both
```shell
npx nx connect
```
- the terminal output
- The files and artifacts created from running the task (e.g., your `build` or `dist` directory)"
Keep reading to learn how to fine-tune what gets cached.
Learn more about [remote caching](/ci/features/remote-cache).
## Fine-tune Caching with Inputs and Outputs
{% callout type="note" title="Detect Inputs and Outputs" %}
Nx can automatically set inputs and outputs for you based on your tooling configuration settings when you use [inferred tasks](/concepts/inferred-tasks)
{% /callout %}
Nx's caching feature starts with sensible defaults, but you can also fine-tune the defaults to control exactly what gets cached and when. There are two main options that control caching:
Nx's caching feature starts with sensible defaults, but you can also **fine-tune the defaults** to control exactly what gets cached and when. There are two main options that control caching:
- **Inputs -** define what gets included as part of the calculated hash (e.g. files, environment variables, etc.)
- **Outputs -** define folders where files might be placed as part of the task execution.
You can define these inputs and outputs at the project level (`project.json`) or globally for all projects (in `nx.json`).
Take the following example: we want to exclude all `*.md` files from the cache such that whenever we change the README.md (or any other markdown file), it does _not_ invalidate the build cache. We also know that the build output will be stored in a folder named after the project name in the `dist` folder at the root of the workspace.
Take the following example: we want to exclude all `*.md` files from the cache so that whenever we change the README.md (or any other markdown file), it does _not_ invalidate the build cache. We also know that the build output will be stored in a folder named after the project name in the `dist` folder at the root of the workspace.
To achieve this, we can add an `inputs` and `outputs` definition globally for all projects or at a per-project level:
To achieve this, we can add `inputs` and `outputs` definitions globally for all projects or at a per-project level:
{% tabs %}
{% tab label="Globally" %}
@ -96,7 +92,7 @@ To achieve this, we can add an `inputs` and `outputs` definition globally for al
```
{% /tab %}
{% tab label="Project Level" %}
{% tab label="Project Level (project.json)" %}
```json {% fileName="packages/some-project/project.json" %}
{
@ -113,52 +109,62 @@ To achieve this, we can add an `inputs` and `outputs` definition globally for al
}
```
{% /tab %}
{% tab label="Project Level (package.json)" %}
```json {% fileName="packages/some-project/package.json" %}
{
"name": "some-project",
"nx": {
"targets": {
"build": {
...
"inputs": ["!{projectRoot}/**/*.md"],
"outputs": ["{workspaceRoot}/dist/apps/some-project"],
...
}
...
}
}
}
```
{% /tab %}
{% /tabs %}
Note, you only need to define output locations if they differ from the usual `dist` or `build` directory which Nx automatically recognizes.
Note that you only need to define output locations if they differ from the usual `dist` or `build` directory, which Nx automatically recognizes.
Learn more [about configuring inputs including `namedInputs`](/recipes/running-tasks/configure-inputs).
## Where is the Cache Stored?
## Configure caching automatically
The cache is stored in `.nx/cache` by default. You can also [change where the cache](/recipes/running-tasks/change-cache-location) is stored if you want.
When using [Nx plugins](/concepts/nx-plugins), many caching configurations are handled automatically, saving you the effort of manual setup. **Nx plugins can [automatically infer tasks](/concepts/inferred-tasks) and configure caching** based on your underlying tooling configuration files.
## Enable Remote Caching
Enable remote caching by connecting to [Nx Cloud](/nx-cloud):
For example, if you add the `@nx/vite` plugin using the following command...
```shell
npx nx connect
npx nx add @nx/vite
```
Learn more about [remote caching](/ci/features/remote-cache).
...it automatically detects your `vite.config.ts` file, infers the tasks you'd be able to run, such as `build`, and **automatically configures the cache settings** for these tasks as well as the [task pipeline](/concepts/task-pipeline-configuration) (e.g., triggering dependent builds).
This means **you don't need to manually specify cacheable operations for Vite tasks** and the cache setting such as input and outputs are always in sync with the `vite.config.ts` file.
To view the task settings that have been automatically configured by a plugin, use the following command:
```shell
nx show project <project-name> --web
```
Alternatively, you can view these directly in your editor by installing [Nx Console](/getting-started/editor-setup).
Learn more details about [Nx plugins](/concepts/nx-plugins) and [inferred tasks](/concepts/inferred-tasks).
## Troubleshooting Caching
- debug cache misses
- [turn off or skip the cache](/recipes/running-tasks/skipping-cache)
- [change the cache location](/recipes/running-tasks/change-cache-location)
- clear the local or remote cache
Caching is hard. If you run into issues, check out the following resources:
---
## Turn off or Skip the Cache
To ignore the cache (both reads and writes), use the `--skip-nx-cache` flag:
```shell
nx build header --skip-nx-cache
```
Alternatively, to disable caching for a specific task, ensure it is not part of the [cached tasks](/features/cache-task-results#define-cacheable-tasks). If [you're using Nx Cloud](/ci/features/remote-cache#skipping-cloud-cache), you can use `--no-cloud` to skip remote caching.
## Clear the Local Cache
To clear the local cache, run:
```shell
npx nx reset
```
For more details refer to the [`nx reset`](/nx-api/nx/documents/reset) page.
- [Debug cache misses](/troubleshooting/troubleshoot-cache-misses)
- [Turn off or skip the cache](/recipes/running-tasks/skipping-cache)
- [Change the cache location](/recipes/running-tasks/change-cache-location)
- [Clear the local or remote cache](/nx-api/nx/documents/reset)

2
docs/shared/migration/manual.md
View File

@ -46,7 +46,7 @@ Next, we'll create a blank `nx.json` configuration file for Nx:
## Add `.nx` directories to `.gitignore`
Next, we'll add [the Nx default task cache directory](/features/cache-task-results#where-is-the-cache-stored) and the project graph cache directory to the list of files to be ignored by Git. Update the `.gitignore` file adding the `.nx/cache` and `.nx/workspace-data` entry:
Next, we'll add the Nx default task cache directory and the project graph cache directory to the list of files to be ignored by Git. Update the `.gitignore` file adding the `.nx/cache` and `.nx/workspace-data` entry:
```text {% fileName=".gitignore" %}
...