@convesoft/nx-rust 1.0.0-rc.1 → 1.0.0-rc.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (78) hide show
  1. package/PLUGIN.md +106 -0
  2. package/README.md +8 -4
  3. package/docs/artifacts.mara.md +374 -0
  4. package/docs/caching.mara.md +999 -0
  5. package/docs/ci.mara.md +308 -0
  6. package/docs/configuration.mara.md +508 -0
  7. package/docs/decisions.mara.md +3267 -0
  8. package/docs/execution.mara.md +533 -0
  9. package/docs/index.mara.md +51 -0
  10. package/docs/product.mara.md +366 -0
  11. package/docs/release.mara.md +493 -0
  12. package/docs/setup.mara.md +486 -0
  13. package/docs/targets.mara.md +704 -0
  14. package/docs/testing.mara.md +431 -0
  15. package/docs/verification.mara.md +465 -0
  16. package/docs/workspaces.mara.md +445 -0
  17. package/package.json +1 -1
  18. package/src/cargo/build-settings.d.ts +8 -1
  19. package/src/cargo/build-settings.js +21 -11
  20. package/src/cargo/build-settings.js.map +1 -1
  21. package/src/cargo/metadata.d.ts +2 -0
  22. package/src/cargo/metadata.js.map +1 -1
  23. package/src/cargo/redirections.d.ts +4 -1
  24. package/src/cargo/redirections.js +7 -2
  25. package/src/cargo/redirections.js.map +1 -1
  26. package/src/cargo/warnings-setting.d.ts +24 -0
  27. package/src/cargo/warnings-setting.js +81 -0
  28. package/src/cargo/warnings-setting.js.map +1 -0
  29. package/src/executors/cargo/schema.json +4 -0
  30. package/src/executors/cargo-output.d.ts +8 -2
  31. package/src/executors/cargo-output.js +20 -6
  32. package/src/executors/cargo-output.js.map +1 -1
  33. package/src/executors/command.d.ts +13 -0
  34. package/src/executors/command.js +37 -7
  35. package/src/executors/command.js.map +1 -1
  36. package/src/executors/denied-warnings.d.ts +99 -0
  37. package/src/executors/denied-warnings.js +188 -0
  38. package/src/executors/denied-warnings.js.map +1 -0
  39. package/src/executors/group-run.d.ts +1 -1
  40. package/src/executors/group-run.js +23 -13
  41. package/src/executors/group-run.js.map +1 -1
  42. package/src/executors/groups.d.ts +7 -2
  43. package/src/executors/groups.js +22 -3
  44. package/src/executors/groups.js.map +1 -1
  45. package/src/executors/nextest.d.ts +6 -2
  46. package/src/executors/nextest.js +12 -6
  47. package/src/executors/nextest.js.map +1 -1
  48. package/src/executors/task-guards.js +7 -2
  49. package/src/executors/task-guards.js.map +1 -1
  50. package/src/executors/task.js +10 -3
  51. package/src/executors/task.js.map +1 -1
  52. package/src/executors/test-mode.d.ts +4 -1
  53. package/src/executors/test-mode.js +7 -1
  54. package/src/executors/test-mode.js.map +1 -1
  55. package/src/executors/test-steps.d.ts +20 -8
  56. package/src/executors/test-steps.js +45 -14
  57. package/src/executors/test-steps.js.map +1 -1
  58. package/src/graph/caching.js +5 -0
  59. package/src/graph/caching.js.map +1 -1
  60. package/src/graph/clippy-input.d.ts +53 -0
  61. package/src/graph/clippy-input.js +107 -0
  62. package/src/graph/clippy-input.js.map +1 -0
  63. package/src/graph/collisions.d.ts +7 -0
  64. package/src/graph/collisions.js.map +1 -1
  65. package/src/graph/discovery.d.ts +15 -0
  66. package/src/graph/discovery.js +5 -0
  67. package/src/graph/discovery.js.map +1 -1
  68. package/src/graph/inputs.d.ts +3 -1
  69. package/src/graph/inputs.js +11 -1
  70. package/src/graph/inputs.js.map +1 -1
  71. package/src/graph/projects.js +13 -2
  72. package/src/graph/projects.js.map +1 -1
  73. package/src/graph/rustfmt-config.d.ts +42 -0
  74. package/src/graph/rustfmt-config.js +173 -0
  75. package/src/graph/rustfmt-config.js.map +1 -0
  76. package/src/graph/targets.d.ts +11 -7
  77. package/src/graph/targets.js +12 -8
  78. package/src/graph/targets.js.map +1 -1
package/PLUGIN.md ADDED
@@ -0,0 +1,106 @@
1
+ # nx-rust
2
+
3
+ `@convesoft/nx-rust` turns Cargo workspaces into Nx projects while Cargo stays
4
+ the build tool. Projects, targets and dependencies come from `cargo metadata`:
5
+ no crate needs a `project.json` or other Nx file of its own, and plain `cargo`
6
+ and rust-analyzer work as they would without the plugin.
7
+
8
+ The full documentation of this installed version is in the [`docs/`](docs/)
9
+ folder next to this file; start at [`docs/index.mara.md`](docs/index.mara.md).
10
+ Its `:::mara` blocks are the normative text. This page only points to them.
11
+
12
+ ## Detection
13
+
14
+ The plugin is active when `nx.json` lists `@convesoft/nx-rust` under
15
+ `plugins`. The crates that the plugin discovers are then Nx projects: the
16
+ members of each Cargo workspace it finds, apart from crates that `include` or
17
+ `exclude` on the plugin's entry in `nx.json`, `.gitignore`, `.nxignore` or
18
+ `cargo vendor` leave out ([how workspaces are
19
+ found](docs/workspaces.mara.md#how-workspaces-are-found), [project
20
+ names](docs/workspaces.mara.md#project-names)). Where a workspace's root
21
+ manifest is read, the tasks for the whole workspace are on its root crate, or
22
+ on a project named after the workspace's folder where the root `Cargo.toml`
23
+ defines no crate ([workspace-level
24
+ tasks](docs/workspaces.mara.md#workspace-level-tasks)).
25
+
26
+ ## Commands
27
+
28
+ Run tasks through Nx, prefixed with the workspace's package manager, rather
29
+ than through `cargo`, so that Nx can cache the targets that are cached (`run`
30
+ and `fmt`, among others, are not):
31
+
32
+ | Task | Command |
33
+ | ------------------------------------------ | ------------------------------------------------ |
34
+ | Lint, test and build what changed | `nx affected -t lint test build` |
35
+ | One crate | `nx test <project>`, `nx lint <project>` |
36
+ | Type-check without building | `nx check <project>` |
37
+ | Check or apply formatting | `nx fmt-check <project>`, `nx fmt <project>` |
38
+ | Run a binary | `nx run <project>:run --bin=<name> --args="..."` |
39
+ | Release build | `nx build <project> --profile=release` |
40
+ | See the cargo command of this run | `nx test <project> --verbose --skip-nx-cache` |
41
+ | Create a library crate | `nx g @convesoft/nx-rust:library <folder>` |
42
+ | Create a binary crate | `nx g @convesoft/nx-rust:binary <folder>` |
43
+ | A project's targets and the options it set | `nx show project <project>` |
44
+
45
+ Without `--skip-nx-cache`, a cache hit replays the stored output, which shows
46
+ a command only if the stored run was verbose
47
+ ([seeing the command](docs/caching.mara.md#seeing-the-command)).
48
+
49
+ `lint` runs clippy. Rust formatting has no `nx format`: use `fmt-check` and
50
+ `fmt`. Workspace-level targets such as `doc`, `lockfile`, `audit` and `update`
51
+ are on the workspace project. All targets and when a crate has them are in
52
+ [targets](docs/targets.mara.md); the options each target accepts are in
53
+ [options of targets](docs/configuration.mara.md#options-of-targets).
54
+
55
+ ## Configuration in `Cargo.toml`
56
+
57
+ The plugin's settings for a crate or workspace go in the `Cargo.toml` that
58
+ already describes it:
59
+
60
+ ```toml
61
+ # rust/crates/api/Cargo.toml
62
+ [package.metadata.nx] # one crate
63
+ name = "backend-api"
64
+ tags = ["scope:backend"]
65
+ fileInputs = ["../../../proto/**/*.proto"] # relative to this Cargo.toml: <repo>/proto
66
+
67
+ [package.metadata.nx.targets.test.options]
68
+ features = ["integration"]
69
+ ```
70
+
71
+ ```toml
72
+ # rust/Cargo.toml
73
+ [workspace.metadata.nx] # every member of the workspace
74
+ testRunner = "nextest" # needs cargo-nextest installed
75
+ ```
76
+
77
+ Repository-wide settings, such as `targetNames`, go into the plugin's
78
+ `options` in `nx.json`. An unknown key in those options or in the plugin's
79
+ `Cargo.toml` tables fails graph creation, and so does an unknown option under
80
+ `targets.<name>.options`; the other fields of a `targets.<name>` table go to
81
+ the Nx target as they are. Every setting and where it can go: [all
82
+ settings](docs/configuration.mara.md#all-settings).
83
+
84
+ Where a repository has them, a `project.json` or `package.json` in a crate's
85
+ folder and `targetDefaults` in `nx.json` take part too: Nx applies them after
86
+ the plugin, so they win over the `Cargo.toml` tables
87
+ ([configuration](docs/configuration.mara.md)).
88
+
89
+ ## Caching
90
+
91
+ - Nx caches task results and final artifacts only, never Cargo's build
92
+ directory ([caching](docs/caching.mara.md#what-is-stored)).
93
+ - A cache key covers the crate's files, its dependencies, its locked
94
+ packages, the toolchain and environment variables that change Rust builds,
95
+ with exceptions per target and feature strategy
96
+ ([what is in a cache key](docs/caching.mara.md#what-is-in-a-cache-key)).
97
+ - When a build script or test reads something the key does not cover,
98
+ declare it: a file inside the repository with `fileInputs`, a variable with
99
+ `envInputs`, and a file outside the repository or a command's output with
100
+ `runtimeInputs`. A `fileInputs` pattern that leaves the repository fails
101
+ graph creation
102
+ ([files outside the crate](docs/caching.mara.md#files-outside-the-crate)).
103
+ - Leaving files out of a target's `inputs` is a promise that the target does
104
+ not read them.
105
+ - Do not add `dependsOn: ["^build"]` to Rust targets: Cargo builds
106
+ dependencies itself ([targets](docs/targets.mara.md#no-build-between-crates)).
package/README.md CHANGED
@@ -6,9 +6,9 @@ JS and TS projects.
6
6
 
7
7
  > **Status:** milestones 0.1 to 0.5 of the
8
8
  > [roadmap](https://github.com/convesoft/nx-rust/blob/main/nx-rust/docs/product.mara.md#roadmap)
9
- > are implemented on the [`main` branch](https://github.com/convesoft/nx-rust).
10
- > What is left of v1 is 1.0. It is not published to npm yet; publishing is
11
- > decided at 1.0.
9
+ > are implemented on the [`main` branch](https://github.com/convesoft/nx-rust),
10
+ > and 1.0 release candidates are published on npm under the `next` dist-tag.
11
+ > What is left of v1 is real-repository validation.
12
12
 
13
13
  - **Nothing to describe twice.** Projects, targets and dependencies come from
14
14
  `cargo metadata`. No crate needs a `project.json`.
@@ -28,7 +28,7 @@ CI yet.
28
28
  ## Usage
29
29
 
30
30
  ```sh
31
- nx add @convesoft/nx-rust # once the package is on npm
31
+ nx add @convesoft/nx-rust@next # 1.0 release candidate
32
32
  nx affected -t lint test build
33
33
  ```
34
34
 
@@ -44,6 +44,10 @@ tags = ["scope:backend"]
44
44
  The user guide and specification are in the repository:
45
45
  <https://github.com/convesoft/nx-rust/blob/main/nx-rust/docs/index.mara.md>
46
46
 
47
+ The package carries the same pages for its own version: `PLUGIN.md`, a short
48
+ guide for coding agents, and the `docs/` folder, both at
49
+ `node_modules/@convesoft/nx-rust/`.
50
+
47
51
  ## License
48
52
 
49
53
  MIT OR Apache-2.0
@@ -0,0 +1,374 @@
1
+ # napi and wasm artifacts
2
+
3
+ > **Status:** `napi-build` and `wasm-build` work.
4
+
5
+ A Rust crate can be built into something a JS project consumes: a Node addon
6
+ through [napi-rs](https://napi.rs), or a wasm package through `wasm-bindgen`.
7
+ v1 supports both: Node addons for the host platform, and wasm for the browser.
8
+ Node addons need napi-rs 3: `napi-derive` 3, and `@napi-rs/cli` 3.4.0 or later
9
+ installed in the workspace. napi-rs 2 addons are not supported.
10
+
11
+ | Target | Produces | Flags |
12
+ | ------------ | ----------------------------------------------------------- | ----------------------------------------- |
13
+ | `build` | Native binaries and libraries | Profile, feature set, platform triple |
14
+ | `napi-build` | The Node addon: a `.node` file plus JS and type definitions | Platform triple |
15
+ | `wasm-build` | The wasm package: `.wasm` plus JS glue | wasm target: `web`, `bundler` or `nodejs` |
16
+
17
+ ```sh
18
+ nx wasm-build image-codec
19
+ nx build web # builds image-codec's wasm package first, if needed
20
+ ```
21
+
22
+ ## Which crates get these targets
23
+
24
+ The plugin reads it from the manifest. A library with
25
+ `crate-type = ["cdylib"]` gets `napi-build` when the crate depends directly on
26
+ `napi`, and `wasm-build` when it depends directly on `wasm-bindgen`. If the
27
+ rule guesses wrong for a crate, name the artifacts yourself in its own
28
+ `Cargo.toml` ([Configuration](configuration.mara.md#all-settings)):
29
+
30
+ ```toml
31
+ [package.metadata.nx]
32
+ artifacts = ["wasm"] # or [] for none
33
+ ```
34
+
35
+ ## Depending on an artifact from JS
36
+
37
+ A JS project depends on the artifact target of the crate, not on `^build`, and
38
+ hashes the files it gets from it:
39
+
40
+ ```json
41
+ {
42
+ "name": "web",
43
+ "targets": {
44
+ "build": {
45
+ "dependsOn": [{ "projects": ["image-codec"], "target": "wasm-build" }],
46
+ "inputs": ["default", "^default", { "dependentTasksOutputFiles": "**/*" }]
47
+ }
48
+ }
49
+ }
50
+ ```
51
+
52
+ The dependency builds the artifact first. The input puts the artifact's files
53
+ into `web`'s cache key. Without it, the key holds the crate's source files and
54
+ those of the crates it depends on, but not what only the artifact's own key
55
+ holds: `Cargo.lock`, the toolchain, `RUSTFLAGS` and the tool versions. A change
56
+ there would build a new artifact and still restore `web`'s old build.
57
+
58
+ Nx also needs to know that `web` uses the crate, so that `nx affected` reaches
59
+ `web` when the crate changes. It knows when `web` depends on the crate's
60
+ package (next section). A crate without a `package.json` goes into `web`'s
61
+ `implicitDependencies` instead.
62
+
63
+ If the JS target also declares `^build`, Nx runs the crate's `build` as well:
64
+ the native cargo build, or whatever replaced it (next section). The plugin
65
+ cannot prevent that ([Targets](targets.mara.md#no-build-between-crates)).
66
+
67
+ ## A crate that is also a JS package
68
+
69
+ A napi or wasm crate usually has a `package.json` beside its `Cargo.toml`,
70
+ listed in the package manager's workspaces, so that JS packages can depend on
71
+ it by name. Nx then merges what nx-rust and its own JS support say about the
72
+ folder into one project:
73
+
74
+ - **Name.** The project takes the name of the folder's `project.json`, if that
75
+ sets one, and otherwise of its `package.json` (`nx.name`, else `name`); the
76
+ crate's own name and a `name` in `[package.metadata.nx]` do not apply
77
+ ([Project names](workspaces.mara.md#project-names)).
78
+ - **Targets.** The project has nx-rust's targets and those of the JS files. A
79
+ script in the `package.json`, or a `project.json` target, with the name of
80
+ an nx-rust target replaces it, so the `build` and `test` scripts of the
81
+ napi-rs template replace cargo's `build` and `test`. A `project.json` target
82
+ without an executor of its own, for example one that sets only `inputs`,
83
+ changes the nx-rust target instead. nx-rust reports none of this, because
84
+ these files are yours.
85
+ - **Other plugins.** Of two plugins that give the folder a target of one
86
+ name, the one listed later in `nx.json` wins, and `nx add` appends. A JS
87
+ plugin added after nx-rust can therefore take a crate's `build`, `test` or
88
+ `lint`: move nx-rust after it, or `exclude` the crate folders on its entry.
89
+ - **Consumers.** A JS package that depends on the crate's package, as with
90
+ `"workspace:*"`, gets an edge to it in the project graph, so `nx affected`
91
+ reaches it when the crate, or a crate the crate depends on, changes.
92
+ - **`^build`.** A consumer's `^build` runs the project's `build` as Nx merged
93
+ it. Where that is a script or a TypeScript build that itself depends on
94
+ `^build`, Nx also runs the native `build` of the crates behind it.
95
+ - **Scripts after `napi-build`.** The files that `napi-build` writes are left
96
+ out of the inputs of nx-rust's targets, but not out of those of the
97
+ targets that Nx makes from the package's own scripts. After `napi-build`
98
+ wrote new files, the package's `build` and `test` scripts therefore run
99
+ again instead of being restored. To avoid that, give those targets
100
+ `inputs` of your own that leave out the addon's file, `index.js` and
101
+ `index.d.ts`.
102
+
103
+ To keep cargo's targets in such a folder, list only the scripts you want as
104
+ targets in `nx.includedScripts`:
105
+
106
+ ```json
107
+ {
108
+ "name": "@acme/native",
109
+ "scripts": { "build": "napi build --platform", "artifacts": "napi artifacts" },
110
+ "nx": { "includedScripts": ["artifacts"] }
111
+ }
112
+ ```
113
+
114
+ The same holds for a Cargo workspace whose folder already is an Nx project,
115
+ such as a repository root with a `project.json` or an `nx` key in its
116
+ `package.json`. If a script or target there is called `lockfile`, it replaces
117
+ the task whose digests the crates' cache keys read, and the crates' cached
118
+ tasks fail without storing anything. Rename one of them, for example nx-rust's
119
+ through `targetNames`:
120
+
121
+ ```json
122
+ { "plugin": "@convesoft/nx-rust", "options": { "targetNames": { "lockfile": "cargo-lockfile" } } }
123
+ ```
124
+
125
+ ## Why separate target names
126
+
127
+ The rule: a different **kind** of artifact gets its own target name; a
128
+ different **flavour** of the same artifact is a flag.
129
+
130
+ - Nx's `dependsOn` names a target and cannot pin a configuration of it. A JS
131
+ app can depend on `wasm-build`; it could not depend on "`build`, but the wasm
132
+ configuration".
133
+ - `nx run-many -t build -c wasm` would run the default native build on every
134
+ crate that has no wasm configuration.
135
+ - One configuration applies per invocation, so native plus wasm would take two
136
+ commands.
137
+ - A named target exists only on crates that produce that artifact.
138
+
139
+ ## How an artifact is built
140
+
141
+ Each artifact is built in two steps:
142
+
143
+ 1. A plain cargo compile, which takes part in batching like any other build.
144
+ A non-host triple such as `wasm32-unknown-unknown` is a group of its own and
145
+ builds only the selected crates.
146
+ 2. A post-processing step that Nx caches, with outputs outside Cargo's
147
+ directories: the `wasm-bindgen` CLI for wasm, and for Node addons the
148
+ functions that `@napi-rs/cli` exports for this.
149
+
150
+ The plugin calls `cargo build` and the `wasm-bindgen` CLI directly. It does not
151
+ use wasm-pack, whose home organisation was sunset in 2025. Nor does it run
152
+ `napi build`, which always runs cargo itself and would compile the crate's
153
+ dependencies a second time. `napi-build` writes the files that
154
+ `napi build --platform` writes, into the crate's folder: the addon, such as
155
+ `my-addon.linux-x64-gnu.node` on Linux x86-64, its loader `index.js` and its type
156
+ definitions `index.d.ts`. `wasm-build` writes what
157
+ `wasm-bindgen --target <wasm target> --out-dir pkg` writes for the `.wasm` file
158
+ that cargo built, such as `image_codec.js`, `image_codec.d.ts` and
159
+ `image_codec_bg.wasm`.
160
+
161
+ ## Things to know
162
+
163
+ - **Tool versions matter.** The `wasm-bindgen` CLI must match the version of
164
+ the `wasm-bindgen` crate in your lockfile; `wasm-build` checks
165
+ `wasm-bindgen --version` before cargo runs and says which version to
166
+ install with `cargo install --locked wasm-bindgen-cli --version <version>`.
167
+ Tool versions are part of the cache key.
168
+ - **wasm needs its target and the CLI.** `wasm-build` compiles for
169
+ `wasm32-unknown-unknown`, so the toolchain of the Cargo workspace needs
170
+ that target (`rustup target add wasm32-unknown-unknown`), and the
171
+ `wasm-bindgen` CLI has to be on `PATH`. The plugin installs neither; a task
172
+ without them fails with a message that says what to install.
173
+ - **The wasm package goes to `pkg`.** `wasm-build` writes the `.wasm` file,
174
+ its JS glue and type definitions into the folder `pkg` of the crate's folder,
175
+ as wasm-pack does, and empties that folder first, so keep nothing else
176
+ there. It compiles the crate's library alone, so a binary of the crate,
177
+ such as a command-line tool in `src/main.rs`, is not built for wasm. Point the `main` or `exports` of the crate's `package.json` at it,
178
+ such as `pkg/image_codec.js`.
179
+ - **The wasm target is an option.** `wasmTarget`, the `--target` of
180
+ `wasm-bindgen`, is `bundler` by default, the
181
+ CLI's own default, for bundlers such as webpack; set `web` for a browser
182
+ without a bundler, or `nodejs`, for example
183
+ `nx wasm-build image-codec --wasmTarget=web` or in the options of the
184
+ crate's target table. `wasm-build` takes `features`, `allFeatures`,
185
+ `noDefaultFeatures` and `profile` as `build` does, and no `targetTriple`.
186
+ - **`@napi-rs/cli` comes from your packages.** `napi-build` uses the
187
+ `@napi-rs/cli` that Node finds from the crate's folder, so list it in the
188
+ `devDependencies` of the crate's `package.json` or of the repository's.
189
+ The plugin installs nothing, and a missing or older CLI fails the task with
190
+ a message that says what to install.
191
+ - **The crate's folder needs a `package.json`.** Its `napi` settings, such as
192
+ `binaryName`, `dtsHeader` and `constEnum`, apply as for
193
+ `napi build --platform`. The files get the names that command gives them;
194
+ its flags for other names, other folders or ES modules, and a separate napi
195
+ configuration file, have no counterpart.
196
+ - **napi options.** `napi-build` takes `features`, `allFeatures`,
197
+ `noDefaultFeatures` and `profile`, and the configuration `all-features`, as
198
+ `build` does, for example `"profile": "release"` in the options of the
199
+ crate's `project.json` target. It has no `targetTriple`: it builds for the
200
+ host only, and fails where Cargo's configuration or `CARGO_BUILD_TARGET`
201
+ picks another triple.
202
+ - **Every napi crate needs `napi_build::setup()`.** The addon crate and every
203
+ crate it depends on that uses `napi-derive` need a build script that calls
204
+ `napi_build::setup()`, as the napi-rs templates have it, and at least one
205
+ `#[napi]` item. Otherwise `napi-build` cannot be sure the type definitions
206
+ are current, and fails and names the crate.
207
+ - **`napi-build` and plain cargo rebuild the napi crates for each other.**
208
+ After `nx napi-build`, the next plain `cargo build`, `nx build` or
209
+ rust-analyzer check compiles the napi crates, and every crate that depends
210
+ on them, again, and the next `napi-build` does the same after them. The rest
211
+ of the workspace is reused. Addon crates are usually leaves, so this is
212
+ usually a few crates.
213
+ - **Two addons need different library names.** If two crates have the same
214
+ `[lib] name`, cargo builds one file for both, and `napi-build` fails for
215
+ both until you rename one.
216
+ - **Artifacts are platform-specific.** The target triple is part of the key, so
217
+ a `.node` file built on Linux is never restored on macOS.
218
+ - **Generated files in the source tree**, the addon, `index.js` and
219
+ `index.d.ts` of `napi-build` and the `pkg` folder of `wasm-build`, are
220
+ outputs of those targets and are left out of the inputs of nx-rust's
221
+ targets and of the crates and JS projects that depend on the crate through
222
+ `^default`; scripts of the crate's own `package.json` still read them (see
223
+ above).
224
+
225
+ Not in v1: cross-compiling Node addons to other platforms, wasm tests, and
226
+ publishing the resulting packages to npm.
227
+
228
+ ## Requirements
229
+
230
+ :::mara requirement REQ-ARTIFACT-TARGETS
231
+ :mid: 01M78FHG7FP44K4K3TDR87ZFQS
232
+ :title: Build Node addons and wasm packages as named targets
233
+ :status: accepted
234
+ :satisfies: NEED-JS-BRIDGE
235
+
236
+ A crate that produces a Node addon has a `napi-build` target that builds the addon for the host triple, with its JS and type definitions. A crate that produces a wasm package has a `wasm-build` target that builds the package for the browser, with its JS glue. Each target exists only on crates that produce that artifact, and a JS project can depend on it by name. Which crates produce an artifact is inferred from their manifests, and a crate can state it explicitly instead.
237
+ :::
238
+
239
+ :::mara requirement REQ-ARTIFACT-CACHE
240
+ :mid: 01M78FHG7FWCZAQ21ZSKRABR4B
241
+ :title: Cache artifacts on everything that shapes them
242
+ :status: accepted
243
+ :satisfies: NEED-CORRECT-CACHE
244
+
245
+ The cache key of an [[TERM-ARTIFACT-TARGET]] includes the target triple and the versions of the tools that post-process the build. Files that the target generates inside the source tree are outputs of the target and are not among its inputs. An artifact built for one platform is never restored on another.
246
+ :::
247
+
248
+ :::mara requirement REQ-MIXED-PROJECTS
249
+ :mid: 01M78FHG7FJ88KAM4MK9SZ4FZH
250
+ :title: Describe a folder with Cargo.toml and package.json as one project
251
+ :status: accepted
252
+ :satisfies: NEED-JS-BRIDGE
253
+ :mitigates: RISK-MIXED-PROJECT-MERGE
254
+
255
+ A crate whose folder also is a JS project, through a `package.json` that Nx reads or a `project.json`, is one Nx project. Its name is the one Nx takes from those files ([[REQ-PROJECT-NAMES]]). It has the targets that the plugin infers for the crate, under their usual names, together with those of the folder's files and of other plugins, as Nx merges them: a script or target of one of the plugin's names in the folder's files, or in a plugin listed after this one in `nx.json`, replaces the plugin's target or merges into it, and the plugin neither renames its target nor reports this ([[ADR-MIXED-PROJECT-TARGETS]]). A JS project that depends on the crate's package has a dependency on the project in the graph, so that a change to the crate, or to a crate it depends on, reaches the JS project through `nx affected` and its `^` inputs. The plugin adds no task dependency to the JS project and removes none, so its `^build` runs the `build` of the merged project, whichever layer gave it. The same holds for a [[TERM-WORKSPACE-PROJECT]] whose folder already is an Nx project.
256
+ :::
257
+
258
+ ## Design
259
+
260
+ :::mara design DES-ARTIFACT-STEPS
261
+ :mid: 01M78FHG7F47NNMQ07P6DKD6KB
262
+ :title: Two steps per artifact
263
+ :status: accepted
264
+ :satisfies: REQ-ARTIFACT-TARGETS
265
+ :satisfies: REQ-ARTIFACT-CACHE
266
+
267
+ | Target | Produces | Flags |
268
+ | ------------ | ----------------------------------------------------------- | ---------------------------------------- |
269
+ | `build` | Native binaries and libraries | Profile, feature set, platform triple |
270
+ | `napi-build` | The Node addon: a `.node` file plus JS and type definitions | Platform triple |
271
+ | `wasm-build` | The wasm package: `.wasm` plus JS glue | wasm target (`web`, `bundler`, `nodejs`) |
272
+
273
+ A different kind of artifact gets its own target name; a different flavour of the same artifact is a flag ([[ADR-ARTIFACT-TARGET-NAMES]]).
274
+
275
+ A crate produces an artifact when its library target has the crate type `cdylib` and the crate depends directly, through a normal dependency, on `napi` for a Node addon or on `wasm-bindgen` for a wasm package. A dependency declared for one platform only counts too. Both facts come from the `cargo metadata` report ([[DES-METADATA-REPORT]]), so the usual crate needs no configuration. An `artifacts` list in `[package.metadata.nx]` replaces the inference: it names the kinds the crate produces, and an empty list means none.
276
+
277
+ Each artifact target is built in two steps:
278
+
279
+ 1. A plain cargo compile inside the batch ([[DES-BATCH]]). A non-host triple is its own group and builds only the selected crates ([[DES-FEATURE-SETS]]).
280
+ 2. A post-processing task that Nx caches, with outputs outside Cargo's directories.
281
+
282
+ JS consumers depend on the artifact target, not on `^build`, and hash its outputs ([[DES-MIXED-PROJECTS]]). Generated type definitions and JS glue are declared as outputs and left out of the crate's named input `default`, which the plugin's targets of the crate and every dependent's `^default` read; the targets that Nx or other plugins give the crate's folder keep their own inputs ([[DES-NAPI]], [[DES-WASM]]). The target triple is in the key, as the host triple of the toolchain input for `napi-build` and as a constant of `wasm-build`, whose target Nx hashes; the versions of the post-processing tools are runtime inputs.
283
+ :::
284
+
285
+ :::mara design DES-WASM
286
+ :mid: 01M78FHG7FEJ8068G4VR6C06QJ
287
+ :title: wasm-build
288
+ :status: accepted
289
+ :satisfies: REQ-ARTIFACT-TARGETS
290
+
291
+ `wasm-build` compiles the crate with `cargo build` for the wasm triple, `wasm32-unknown-unknown`, and then runs the `wasm-bindgen` CLI on the result, in the two steps of [[DES-ARTIFACT-STEPS]]. The plugin does not use wasm-pack ([[ADR-NO-WASM-PACK]]). v1 targets the browser and runs no wasm tests ([[ADR-V1-SCOPE]]).
292
+
293
+ **Target.** `wasm-build` runs `@convesoft/nx-rust:cargo-outputs`, the executor of the targets whose files Nx stores ([[DES-BATCH]], "Two batch executors"). It takes `features`, `allFeatures`, `noDefaultFeatures` and `profile` and has the configuration `all-features`, as `build` does, and takes no `targetTriple`: it always builds for the wasm triple ([[DES-PLUGIN-OPTIONS]]). The wasm target is its option `wasmTarget`, one of `bundler`, `web` and `nodejs`, which it passes to the CLI as `--target`; the inferred target sets `bundler`, the CLI's own default. Its output is the folder `pkg` in the crate's folder, outside Cargo's directories, as wasm-pack names it ([[DES-OUTPUTS]]), which is left out of the crate's named input `default`, so that writing it changes the key of no target of the plugin, neither `wasm-build`'s own nor any other target of the crate, and no dependent's key that reads the crate through `^default`. The worker of nxr-0ap8n4 chose on 16 November 2026, and the maintainer confirmed on 20 November 2026, the feature and profile options, as `napi-build` has them ([[DES-NAPI]]), because a package that a web app ships is usually built with `--release`; the default `bundler` of the wasm target; and the folder `pkg`, which the plugin owns and empties on each run. To undo one, change `inferTargets` and `optionTargets` and the constants of `nx-rust/src/graph/wasm.ts`, and this paragraph. The maintainer named the option `wasmTarget` on 20 November 2026, after `wasm-bindgen --target` as `targetTriple` is named after `cargo --target`.
294
+
295
+ **Compile.** The compile step is a group of its own kind in the batch ([[DES-BATCH]]), a plain `cargo build` with `--lib`, `--target wasm32-unknown-unknown`, the feature and profile flags of the task and `--locked` in locked mode. `--lib` builds the library targets alone, in every strategy and for a group of one crate as for a shared `-p` command: the package is the crate's library, and a binary of the crate that is built for the wasm triple writes `<name>.wasm` too, over the library's where it has the library's name, so that the CLI would read the binary ([[EVD-WASM-POSTPROCESS]]). The worker of nxr-0ap8n4 added it on 16 November 2026, after the review of 02ed6a2 found that a crate with a wasm library and a `src/main.rs` failed in the CLI; to undo it, drop `--lib` from the command of `nx-rust/src/executors/command.ts`, which brings that failure back. Because of it, the reading of cargo's messages expects the library's unit alone, and the build input check names no record of a binary. Its command always passes `--keep-going` and `--message-format=json`, also for a group of one crate, since `wasm-build` has no plain cargo command that a user would compare it with, and cargo's JSON messages report the `.wasm` file that the post-processing reads. The wasm triple is a triple other than the host's, so the compile selects crates and resolves features as a `build` group for such a triple does under the workspace's strategy ([[DES-UNIFICATION]], [[DES-FEATURE-SETS]]), so that its result rests only on what its key holds and not on which other tasks share the command ([[ADR-WORKSPACE-FEATURES]]):
296
+
297
+ - **`workspace-build`**: one crate per command, with `-p`, because the whole workspace may not build for the triple ([[DES-BATCH]], "Groups of one crate"). The command resolves features for the crate and what it depends on, which the key of `workspace-build` covers with every member's manifest and digest, a superset.
298
+ - **`hakari`**: `-p` for each crate of the group where the `platforms` that graph creation recorded list both the host and `wasm32-unknown-unknown`, since the hack crate unifies the third-party features on each listed platform; otherwise, and for feature flags, one crate per command ([[DES-UNIFICATION]], "Triples that `platforms` does not list"). The target depends on `hakari-check` as every cached crate target does, and its key follows the `hakari` rule.
299
+ - **`cargo`**: `-p` for each crate with `--config 'resolver.feature-unification="workspace"'` and `-Zfeature-unification`, which resolve features for the whole workspace on the triple, and a group of one crate for `--features`; on a stable cargo the task fails with cargo's error, as every compiling target does under `cargo`.
300
+
301
+ The compile builds in a stage of its own, whatever it selects, and moves nothing into the artifact directory: the CLI reads the `.wasm` file from the stage, and the checks after cargo read the crate's records there, so that it writes no file that a `build` stores ([[DES-BATCH]], "Staged builds"). After the compile, each task whose crate passed runs the checks that follow cargo for `build`: the lockfile post-check and the check of [[DES-BUILD-INPUT-CHECK]] on the crate's records for the wasm triple, where the record of a `cdylib` is `<name>.d` beside `<name>.wasm` ([[EVD-WASM-POSTPROCESS]]). Unlike the compile of `napi-build`, it sets no variable of its own.
302
+
303
+ **Post-processing.** After the compile, for each task whose crate passed, the plugin removes the `pkg` folder of an earlier run and runs the CLI with `--target <wasmTarget> --out-dir <crate folder>/pkg` on the `.wasm` file among the files of the `compiler-artifact` message that cargo printed for the crate's `cdylib` in this compile, which cargo prints also for a fresh unit; where cargo reports no such file for the crate, or more than one, the task fails and says so. The plugin derives no file's place from the layout of Cargo's folders. The CLI runs in the workspace root, with the environment that cargo had. A task fails where the CLI fails, and where it ends without error but wrote no `<name>_bg.wasm`, and then leaves no `pkg` folder. The CLI writes `<name>.js`, `<name>.d.ts`, `<name>_bg.wasm` and `<name>_bg.wasm.d.ts`, with `<name>_bg.js` for `bundler`, and `snippets` and a `package.json` where the crate's code imports JS modules or npm packages ([[EVD-WASM-POSTPROCESS]]).
304
+
305
+ **What the step needs.** A task fails before cargo runs, with a message that names the tool or the crate and says what the user can do ([[DES-DIAGNOSTICS]]), where the crate's library shares its file name with another crate's (**Library names** of [[DES-NAPI]]), where `wasmTarget` is none of the three wasm targets, where the toolchain that the workspace root selects has no standard library for the wasm triple, where the CLI is not on the task's `PATH` in the workspace root, and where the CLI that `wasm-bindgen --version` names differs from the version of the `wasm-bindgen` crate that the crate's entry in `Cargo.lock` reaches, or where that entry reaches none or several. The lockfile task has brought `Cargo.lock` up to date before the task starts ([[DES-LOCKFILE-HASHING]]). The plugin installs nothing ([[ADR-V1-SCOPE]]).
306
+
307
+ **Key.** The cache key holds `build`'s inputs ([[DES-INPUTS]]), the options, `wasmTarget` among them, and the target, whose triple is a constant; the CLI's version, through a `runtime` input that prints what `wasm-bindgen --version` writes in the workspace root, as the task finds the CLI, or a random value where that fails; and the variables that the CLI reads, `WASM_BINDGEN_ANYREF`, `WASM_BINDGEN_EXTERNREF` and `WASM_BINDGEN_MULTI_VALUE`, each with its value and with whether it is set. The CLI turns each on by its presence, an empty value included, while Nx 24 hashes an unset and an empty `env` input alike ([[EVD-WASM-POSTPROCESS]]), so the values are `env` inputs and the same `runtime` input prints, after the version, one line per variable that says whether it is set; the CLI gets the task's environment unchanged. Nx runs that command with the task's environment, its dotenv files included, which is the environment the batch gives the CLI ([[DES-BATCH]], [[EVD-NX-24-INPUT-SEMANTICS]]); an Nx 24 target has no `env` of its own that the two could see differently. The control plane decided this on 16 November 2026 after the review of 02ed6a2 found that a package of an unset `WASM_BINDGEN_MULTI_VALUE` was restored for an empty one; there is no safe undo. The CLI reads no configuration file. It reads the `package.json` of a crate whose code imports a local JS module, which is a crate file of a project or a file of a crate behind it, and nothing else besides the `.wasm` file ([[EVD-WASM-POSTPROCESS]]).
308
+ :::
309
+
310
+ :::mara design DES-NAPI
311
+ :mid: 01M78FHG7FRRT8J6Z5NYMT12A3
312
+ :title: napi-build
313
+ :status: accepted
314
+ :satisfies: REQ-ARTIFACT-TARGETS
315
+
316
+ `napi-build` compiles the crate with `cargo build` for the host triple and then post-processes the library into the `.node` file with its JS and type definitions, in the two steps of [[DES-ARTIFACT-STEPS]]. `napi build` cannot do the second step alone: it always runs cargo itself, for the one package and with `--target`, and would compile the crate's whole dependency tree a second time into the triple's folder, with the features of that package alone ([[EVD-NAPI-POSTPROCESS]]). The plugin therefore does not run `napi build`.
317
+
318
+ **Target.** `napi-build` runs `@convesoft/nx-rust:cargo-outputs`, the executor of the targets whose files Nx stores ([[DES-BATCH]], "Two batch executors"). It takes `features`, `allFeatures`, `noDefaultFeatures` and `profile` and has the configuration `all-features`, as `build` does, and takes no `targetTriple`, since v1 builds Node addons for the host only ([[DES-PLUGIN-OPTIONS]], [[ADR-V1-SCOPE]]). The worker of nxr-tv3r95 gave it these options on 16 November 2026, and the maintainer confirmed them on 20 November 2026, because an addon that a JS package ships is usually built with `--release`; without them it would only build the dev profile. Its outputs are the addon's file, `index.js` and `index.d.ts` in the crate's folder ([[DES-OUTPUTS]]). Graph creation names the addon's file from the `binaryName` of the crate's `package.json` as `readNapiConfig` reads it, else `index`, and from the host triple that `rustc -vV` names in the workspace root, in the form of `parseTriple` of `@napi-rs/cli` 3, such as `addon.linux-x64-gnu.node`; where rustc names no host triple, the target runs uncached. Its inputs are those of `build` with the version of the CLI, `npm_new_version` and the `dtsHeaderFile` of the crate's napi settings ([[DES-INPUTS]]).
319
+
320
+ **Compile.** The compile step is a group of its own kind in the batch ([[DES-BATCH]]), which selects crates and resolves features as `build` does under the workspace's strategy ([[DES-UNIFICATION]]), without `--target` on the host: under `workspace-build` the whole workspace, and a task whose own options give it a feature set as a group of one crate. Its command always passes `--keep-going` and `--message-format=json`, also for a group of one crate, since `napi-build` has no plain cargo command that a user would compare it with, and cargo's JSON messages report the library that the post-processing copies. Its command builds in a stage and moves nothing into the artifact directory, so it writes no file that a batch stores (**Compile** below; [[DES-BATCH]], "Staged builds"). While `napi-derive` 3 expands a crate's `#[napi]` items, it writes the crate's type information into a file named after the package in the folder that `NAPI_TYPE_DEF_TMP_FOLDER` names. It writes nothing while that variable is unset or the folder is missing, and only when the crate is actually compiled: it never removes the file of a crate that is fresh or that no longer has any `#[napi]` item ([[EVD-NAPI-POSTPROCESS]]). The compile therefore starts from nothing each time:
321
+
322
+ - **An empty folder.** Before each compile, the plugin creates the folder empty, in Cargo's build directory, at a path of the group's configuration: everything the tasks of a group share ([[TERM-GROUP]]), and for a group of one crate that crate. The path is `nx-rust/napi/<hash>/types` in the build directory, with a hash of the workspace root and the compile's command, which holds the selection, the feature and profile flags and `--locked`. Nothing from an earlier run is kept, and no two configurations share a folder. The path stays the same from run to run, because cargo rebuilds every crate whose build script calls `napi_build::setup()` when it changes, also crates that this compile does not need.
323
+ - **Every napi crate forced.** The closure is the group's addon crates and every crate that they depend on through normal dependencies. The plugin asks `cargo tree -e normal` for it once per group, with the compile's selection, feature flags and `--locked`, which resolves features as the compile does, for the host. For each crate of the closure that depends on `napi-derive`, whether or not it has a task in the group, the command sets `NAPI_FORCE_BUILD_` with the package name in capitals and `-` replaced by `_` to a value of this compile's own. `napi_build::setup()` makes cargo rebuild the crate when that variable changes, so every such crate is compiled and writes its file.
324
+ - **Every file written.** After cargo, each crate that the command forced must have a file in the folder. Where one has none, every `napi-build` task whose addon is that crate or depends on it fails, with a message that names the crate and the two causes: its build script does not run `napi_build::setup()`, which alone lets the variable force it, or it no longer has any `#[napi]` item and should drop its dependency on `napi-derive` ([[DES-DIAGNOSTICS]]). Forcing cannot reach a crate whose build script does not call `setup()`: cargo keeps it fresh, and only a change to its own files compiles it again.
325
+
326
+ After the compile, each task whose crate passed runs the checks that follow cargo for `build`: the lockfile post-check and the check of [[DES-BUILD-INPUT-CHECK]] on the crate's records.
327
+
328
+ **Strategies.** The compile selects crates and resolves features as a `build` group does under the workspace's strategy ([[DES-UNIFICATION]]), so that its result rests only on what its key holds and not on which other tasks share the command ([[ADR-WORKSPACE-FEATURES]]); `cargo tree` gets the same selection and flags, so that the closure is what the command builds:
329
+
330
+ - **`workspace-build`**: `--workspace` on the host, so every crate compiles with the features of the whole workspace, as the key's digests of every member promise; a task whose own options give it a feature set runs alone with `-p`.
331
+ - **`hakari`**: `-p` for each crate of the group, and a group of one crate for feature flags and for a host or triple that `platforms` does not list. The hack crate gives every crate the same features whatever the selection. The target depends on `hakari-check` as every cached crate target does, and its key follows the `hakari` rule: the crate's own digest, the hack crate's manifest and cargo-hakari's configuration. The hack crate never counts among the crates that write type information: it can depend on `napi-derive` only to unify its features, and has no `#[napi]` item and no build script that calls `napi_build::setup()`.
332
+ - **`cargo`**: `-p` for each crate with `--config 'resolver.feature-unification="workspace"'` and `-Zfeature-unification`, which `cargo tree` gets as well, and a group of one crate for `--features`; on a stable cargo the task fails with cargo's error, as every compiling target does under `cargo`.
333
+
334
+ The compile builds in a stage of its own, whatever it selects, and moves nothing into the artifact directory: the post-processing reads the library from the stage, and the checks after cargo read the crate's records there ([[DES-BATCH]], "Staged builds"). It therefore writes no file that a `build` stores, and a `build` and a `napi-build` of one crate can share a batch ([[DES-BATCH]], "Files that a batch stores").
335
+
336
+ Only this step sets these variables. `build`, `test`, `check` and `lint` run without them, as plain cargo does. Every crate that the step forces, and every crate that depends on one of them, is therefore compiled again on each `napi-build` compile and on the next command without the variables, such as plain `cargo build`, `nx build` or rust-analyzer's check. The plugin accepts this in the shared build directory ([[ADR-NAPI-SHARED-BUILD-DIR]]). Two `nx` commands that run the compile of one group configuration at the same time empty the same folder, and one of them can then miss files or read the other's.
337
+
338
+ **Library names.** The `.node` file is a copy of the library that cargo reports for the crate's `cdylib`. Where two crates give their libraries one file name, as [[DES-OUTPUTS]] compares them ("Files of one name"), cargo builds one file for both, and the copy would give both addons one crate's functions. `build` of such crates runs uncached with a warning; a `napi-build` of such a crate fails when the task starts, before cargo runs, with a message that names both crates and says to give them different `[lib] name`s ([[DES-DIAGNOSTICS]]).
339
+
340
+ **Post-processing.** After the compile, for each task, the plugin removes the addon's file, `index.js` and `index.d.ts` of an earlier run, so that none is left where the CLI writes none, as `index.js` of an addon without exports. It copies the library that cargo reports for the crate's `cdylib` in this compile, the file with the extension of a dynamic library among the files of the crate's `compiler-artifact` message, which cargo prints also for a fresh unit, to `<binaryName>.<platform>-<arch>-<abi>.node` in the crate's folder; where cargo reports no such file for the crate, or more than one, the task fails and says so. The plugin derives no file's place from the layout of Cargo's folders: cargo writes the library into the folder of a triple where `CARGO_BUILD_TARGET`, `build.target` or `--target` selects one, also the host's, and the type folders lie in the build directory that cargo reports, which no triple changes. The review of a86d172 found that an earlier version, which copied `lib<name>.so` from the profile's folder of the artifact directory, stored the older library of a plain build under the new key where `CARGO_BUILD_TARGET` or `build.target` named the host, and failed without one; the control plane decided on 16 November 2026 to copy the reported file in every case. It then writes `index.d.ts` and `index.js` there with `generateTypeDef` and `writeJsBinding`, which the workspace's installed `@napi-rs/cli` exports, and with the crate's `napi` settings, which `readNapiConfig` reads from the crate's `package.json`. The defaults are those of `napi build --platform`, whose post-processing in 3.10.12 the plugin follows: the header, `constEnum` and `runtimeStringEnum` of the settings; the binding-target declaration where the addon has exports or the settings list a WASI target; the WASI flavours of the settings' targets for the loader, the threaded one first; the version of `npm_new_version` in the task's environment, else that of the `package.json`; and `index.d.ts` only where the crate's dependency on `napi-derive` keeps its default features or turns on `type-def`. `generateTypeDef` reads every file in the folder it is given, so the plugin gives it a folder of the task's own, `nx-rust/napi/<hash>/tasks/<crate>` beside the type folder. That folder holds only the files of the crate and of the napi crates in its own closure, whose `#[napi]` items become part of the addon. With that folder, both files were byte-identical to those of `napi build --platform` ([[EVD-NAPI-POSTPROCESS]]), and are in the plugin's tests. These three files are the target's outputs ([[DES-ARTIFACT-STEPS]]). They are left out of the crate's named input `default`, so that writing them changes the key of no target of the plugin, neither `napi-build`'s own nor any other target of the crate, and no dependent's key that reads the crate through `^default`. The targets that Nx makes from the scripts of the crate's `package.json` keep inputs of their own, which held all three files with Nx 24.0.6 also where `nx.json` defines `default` as usual, as the review of a86d172 found with Nx's graph and hasher: after `napi-build` wrote new files, the scripts `build` and `test` run again. That runs more and never less than their keys promise, and the plugin changes no target of a JS project ([[ADR-NO-RUST-BUILD-DEPS]]); the guide tells users how to leave the files out of those targets' inputs. What `napi build` takes as flags, other file names and folders, ES modules and a separate configuration file, and the WASI loader files that it writes again beside earlier ones, have no counterpart.
341
+
342
+ **What the step needs.** `napi-build` supports crates built with `napi-derive` 3 and post-processed with `@napi-rs/cli` 3, from 3.4.0, the first release that exports all three functions ([[ADR-NAPI-RS-3]]). The CLI is the package that Node resolves from the crate's folder, through the `node_modules` folders from there up, as a package manager installs it for the crate's own `package.json` or for the repository. A task fails before cargo runs, with a message that names the tool or the crate and the version ([[DES-DIAGNOSTICS]]), where Node resolves no `@napi-rs/cli` there, as for any missing tool, or one of another major or older than 3.4.0, where the crate's folder has no `package.json`, where `rustc -vV` names no host triple or Cargo's configuration or `CARGO_BUILD_TARGET` picks another triple in the workspace root, and where the installed CLI names the addon's file otherwise than the outputs of a cached task. A crate of its closure that depends on `napi-derive` of another major fails the task after `cargo tree` and before the compile.
343
+
344
+ The cache key holds the version of the `@napi-rs/cli` that Node resolves from the crate's folder and the host triple, through the toolchain input's `rustc -Vv` ([[DES-INPUTS]]). Of what `readNapiConfig` returns and `generateTypeDef` and `writeJsBinding` read, every setting comes from the crate's `package.json`, a crate file, apart from the file that `dtsHeaderFile` names, which `generateTypeDef` reads from the crate's folder. Graph creation reads that path from the `package.json` and puts the file into the target's inputs as a fileset that also covers an ignored file. A cached task fails before cargo where the file lies outside the repository, where Nx cannot hash it, and where the `package.json` now names another file than the graph's inputs, as after a change that the Nx daemon has not seen. The review of a86d172 found that a header outside the crate's folder reached no key, so that Nx restored `index.d.ts` with the old header; the control plane decided on 16 November 2026 that what the plugin cannot cover must fail. A separate napi configuration file, which `napi build` reads only with `--config-path`, is never read. v1 builds for the host triple only: cross-compiling takes one target per command and zig or cargo-xwin, and is normally a CI matrix.
345
+
346
+ Whether napi crates need a special feature to link under `cargo test` is not confirmed ([[RISK-NAPI-TOOLING]]).
347
+ :::
348
+
349
+ :::mara design DES-MIXED-PROJECTS
350
+ :mid: 01M7J4NJ5WGAAQEBVGQCFFCQ02
351
+ :title: One project from two descriptions
352
+ :status: accepted
353
+ :satisfies: REQ-MIXED-PROJECTS
354
+
355
+ **Name.** Nx merges every project returned for one root into one, in this order: the plugins in the order of `nx.json`, target defaults, then its own `package.json` and `project.json` plugins, which no position in `nx.json` follows ([[EVD-NX-PROJECT-MERGE]]). The project is therefore named by the folder's `project.json`, where it sets a name, and otherwise by the `package.json` (`nx.name`, else `name`), and the plugin names the ends of its edges by the project at the crate's root ([[DES-PROJECT-GRAPH]]). Nx reads a crate's `package.json` only where the package manager's workspaces list it or a `project.json` sits beside it; otherwise the folder is the crate's project alone.
356
+
357
+ **Targets.** The plugin infers a mixed crate's targets as any crate's ([[DES-TARGETS]]) and does nothing about the folder's other layers ([[ADR-MIXED-PROJECT-TARGETS]]). Nx merges a later target of the same name into the plugin's where at most one of the two names an executor, or both name the same one; its lists then replace the plugin's unless they hold `"..."`. A target with another executor or a command, such as a `package.json` script, which runs `nx:run-script`, replaces the plugin's whole ([[EVD-NX-24-PLUGIN-NODES]], "Other layers"). A script keeps the plugin's `cargo` record in its metadata beside its own ([[EVD-NX-MIXED-CONSUMER]]), which no executor of the script reads, and the guard leaves every target alone that no longer runs the plugin's executor ([[DES-TARGET-DEFAULT-GUARD]], "Where"). A merged target that still runs it is compared as that item says, and what the folder's own `project.json` and `package.json` do to it counts as the project's own statement ("Other layers"). Of two plugins, the one listed later wins a target; `init` appends nx-rust to the plugins of `nx.json`, and `nx add` appends a plugin added later. `nx.includedScripts` in the `package.json` limits which scripts become targets.
358
+
359
+ **Consumers.** The plugin adds no edge to or from a JS project. Nx's own analysis of a JS project's `package.json` turns a dependency on the crate's package, such as `workspace:*`, into a static edge to the merged project ([[EVD-NX-MIXED-CONSUMER]]). A crate without a `package.json` that Nx reads has no package name, and a JS project reaches it through its own `implicitDependencies`. Through that edge and the plugin's edges between crates, `nx affected` selects the JS project when the crate or a crate behind it changes, and the JS project's `^default` reads each such crate's named input `default`, its folder and its workspace's root manifest ([[DES-INPUTS]]). It does not read what only the crates' own keys hold, the lockfile digests, the toolchain, the variables and the tool versions. A JS target that consumes an artifact therefore depends on the [[TERM-ARTIFACT-TARGET]] and hashes its outputs through a `dependentTasksOutputFiles` input, which the user writes, since the plugin writes nothing into JS projects ([[ADR-NO-RUST-BUILD-DEPS]]).
360
+
361
+ **`^build`.** A JS target's `^build` runs the `build` of the merged project. Where that is the plugin's, it is the crate's native build, which depends only on its workspace's lockfile task and, under `hakari`, the drift check ([[REQ-NO-RUST-TASK-DEPS]]). Where a script, a `project.json` target or a later plugin replaced it, it runs that target with that target's own `dependsOn`. A script has none of its own, a TypeScript build of `@nx/js/typescript` has `^build`, and a `targetDefaults` entry keyed `build` gives one to a script, while the entries keyed by the plugin's executors that `init` writes keep it from the crates' own `build`. Such a `^build` runs the native `build` of the crates that the mixed project depends on directly, which stop at their lockfile task ([[EVD-NX-MIXED-CONSUMER]], [[ADR-NO-RUST-BUILD-DEPS]]).
362
+
363
+ **Workspace project.** A workspace project whose folder already is an Nx project merges in the same way ([[EVD-NX-PROJECT-MERGE]]). A script or target named like the lockfile task replaces it; the crates' cached tasks still depend on the target of that name and then fail without storing a result ([[DES-LOCKFILE-HASHING]], "Merged project").
364
+ :::
365
+
366
+ ## Scenario
367
+
368
+ :::mara scenario SCN-MIXED-CHANGE
369
+ :mid: 01M78FHG7FZW8RSXABKCH37WF5
370
+ :title: A Rust change reaches the JS app that consumes it
371
+ :status: accepted
372
+
373
+ A repository has a web app `web` and a crate `image-codec` that is built into a wasm package; `web`'s build depends on `image-codec:wasm-build`. A developer changes a source file of `core`, a crate that `image-codec` depends on, and opens a pull request. CI runs `nx affected -t lint test build`. Nx runs `lint` and `test` for `core` and `image-codec`, runs `wasm-build` for `image-codec` because `web`'s build needs it, and builds and tests `web`. Unrelated crates and JS projects are restored from the cache or not selected at all. The Rust tasks of one workspace run with one cargo command per step of each group, not one per crate. No command in the pipeline is specific to Rust.
374
+ :::