docs(repo): add conformance rule for NX_* env var documentation#35353
Merged
Conversation
✅ Deploy Preview for nx-dev ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
✅ Deploy Preview for nx-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Contributor
|
View your CI Pipeline Execution ↗ for commit d97c1b2
☁️ Nx Cloud last updated this comment at |
barbados-clemens
changed the title
![nx-cloud[bot]](https://avatars.githubusercontent.com/in/80458?s=60&v=4){kind=small}
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
Contributor
There was a problem hiding this comment.
✅ The fix from Nx Cloud was applied automatically
We fixed the astro-docs:format failure by running Prettier on astro-docs/src/content/docs/reference/environment-variables.mdoc, which had style inconsistencies introduced by the PR's documentation additions. Our change brings the file into compliance with the workspace's Prettier formatting rules, which the format check enforces across all .mdoc files.
Tip
✅ We verified this fix by re-running astro-docs:format.
Suggested Fix changes
diff --git a/astro-docs/src/content/docs/reference/environment-variables.mdoc b/astro-docs/src/content/docs/reference/environment-variables.mdoc
index c302b161ef..9dab00b318 100644
--- a/astro-docs/src/content/docs/reference/environment-variables.mdoc
+++ b/astro-docs/src/content/docs/reference/environment-variables.mdoc
@@ -63,7 +63,7 @@ The following environment variables are ones that you can set to change the beha
| `NX_SKIP_PROVENANCE_CHECK` | boolean | If set to `true`, skips `npm` provenance verification when installing packages during `nx migrate`. This is a security-sensitive check. Only disable it if you understand the implications. |
| `NX_NATIVE_LOGGING` | string | Filter directive for the native (Rust) tracing logger. Defaults to `nx::native=info`. Set to a log level (`trace`, `debug`, `info`, `warn`, `error`, `off`) to control all native logs, or scope by crate or module (e.g. `nx=trace`, `nx::native::tasks::hashers=debug`, `[{project_name=myapp}]`). |
| `NX_NATIVE_FILE_LOGGING` | string | Enables the native (Rust) tracing logger and writes logs to `.nx/workspace-data/nx.log`. Accepts the same filter directives as `NX_NATIVE_LOGGING` (e.g. `debug`, `info`, `[{project_name=myapp}]`). Useful for debugging native code paths. |
-| `NX_REJECT_UNKNOWN_LOCAL_CACHE` | boolean | Legacy cache safety toggle. Set to `0` or `false` to allow reading a local cache that wasn't populated by the current machine. Not supported with the new database cache. See [legacy cache](/docs/reference/deprecated/legacy-cache#nxrejectunknownlocalcache). |
+| `NX_REJECT_UNKNOWN_LOCAL_CACHE` | boolean | Legacy cache safety toggle. Set to `0` or `false` to allow reading a local cache that wasn't populated by the current machine. Not supported with the new database cache. See [legacy cache](/docs/reference/deprecated/legacy-cache#nxrejectunknownlocalcache). |
| `NX_SELF_HOSTED_REMOTE_CACHE_SERVER` | string | URL of a self-hosted remote cache server. When set, Nx uses this endpoint for remote cache reads and writes instead of Nx Cloud. |
| `NX_SELF_HOSTED_REMOTE_CACHE_ACCESS_TOKEN` | string | Bearer token passed as the `Authorization` header when contacting the self-hosted remote cache server configured via `NX_SELF_HOSTED_REMOTE_CACHE_SERVER`. |
🔔 Heads up, your workspace has pending recommendations ↗ to auto-apply fixes for similar failures.
🎓 Learn more about Self-Healing CI on nx.dev
barbados-clemens
force-pushed
the
cu/env-var-conformance-docs
branch
from
838b122 to
7edd9e5
Compare
AgentEnder
reviewed
Apr 21, 2026
AgentEnder
requested changes
Apr 21, 2026
AgentEnder
left a comment
AgentEnder
left a comment
Member
There was a problem hiding this comment.
The rust bit is the only real change I'm requesting, the others are "we may want to doc this one" comments to open a discussion
4 tasks
Adds `env-vars-documented` conformance rule that scans Nx source for `NX_*` environment variable reads and fails when any are missing from `astro-docs/.../environment-variables.mdoc`. Registers the rule in `nx.json` with an initial ignore list for internal markers, and documents previously-undocumented user-facing vars (including Nx Cloud timeouts, self-hosted cache, provenance, and isolation flags). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…LOGGING
Extends the conformance rule's Rust patterns to catch
`EnvFilter::(try_)?from_env("NX_*")` usage from `tracing_subscriber`,
which was missed by the `env::var` / `env!` patterns. Documents
`NX_NATIVE_LOGGING` (filter directive for the native tracing logger).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The variable is still read by the Nx Cloud client, so label it as typically not needed rather than deprecated and point users at `--no-dte` / `--no-agents`. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: barbados-clemens <barbados-clemens@users.noreply.github.com>
Co-authored-by: barbados-clemens <barbados-clemens@users.noreply.github.com>
Switch source file reads from `readFileSync` to the conformance `tree.read` helper used by sibling rules (drops `workspaceRoot`, `readFileSync`, and `join` imports plus an explicit try/catch). Replace the `isRust` boolean parameter with file-path dispatch, and cap the per-var example set at insert time to bound memory under `scope: 'all'`. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
All NX_* env var reads live in `packages/nx`, so look up that project's files directly instead of walking every project with a scope filter. Also inline the one-use `failure` helper. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Addresses review feedback from Craigory: - Drop Rust env! macro regex (compile-time, not runtime). - Document NX_CACHE_FAILURES, NX_NATIVE_COMMAND_RUNNER, NX_WRAPPER_SKIP_INSTALL, NX_SKIP_NATIVE_FILE_CACHE, and NX_SOCKET_DIR in the main Nx table. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Addresses review feedback from Craigory: - Drop Rust env! macro regex (compile-time, not runtime). - Document NX_CACHE_FAILURES, NX_NATIVE_COMMAND_RUNNER, NX_WRAPPER_SKIP_INSTALL, NX_SKIP_NATIVE_FILE_CACHE, and NX_SOCKET_DIR in the main Nx table. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Give NX_DAEMON_SOCKET_DIR its own row instead of only mentioning it inline under NX_SOCKET_DIR, and drop it from the conformance rule's ignore list. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
It is not a deprecated alias — NX_SOCKET_DIR covers both daemon and forked process sockets, while NX_DAEMON_SOCKET_DIR scopes the override to the daemon socket only. Match the existing troubleshooting and nx-daemon concept docs. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Tracing getSocketDir() in tmp-dir.ts and get_socket_dir() in socket_path.rs shows both vars feed the same function used for every Nx socket (daemon, forked process, plugin, nx-console) — they are aliases, not scope-separated overrides. Update the env var reference, unix-sockets troubleshooting page, and nx-daemon concept doc to recommend NX_SOCKET_DIR and describe NX_DAEMON_SOCKET_DIR as a legacy fallback. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The previous table had ~60 entries in a single block that was overwhelming to scan. Group everyday settings (bail, base/head, cache dirs, parallel, dry run, verbose logging, migration basics, TUI) under Common, and move debugging/internals (native runner, logging, plugin isolation, v8 serializer, wrapper, socket dirs, self-hosted cache, profiling, provenance) under Advanced. Rows are sorted alphabetically within each section for faster lookup. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
barbados-clemens
force-pushed
the
cu/env-var-conformance-docs
branch
from
c348701 to
d97c1b2
Compare
AgentEnder
approved these changes
Apr 22, 2026
Contributor
|
This pull request has already been merged/closed. If you experience issues related to these changes, please open a new issue referencing this pull request. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Current Behavior
NX_*env vars can be added to Nx source without being documented inastro-docs/src/content/docs/reference/environment-variables.mdoc. Nothing catches the drift.Expected Behavior
Adds a conformance rule (
env-vars-documented) that fails when anNX_*var is read in source but missing from the docs. Covers TS/JSprocess.env.NX_*and Rustenv::var/env!patterns, skipping tests and fixtures. Anignorelist innx.jsonhandles internal markers not meant to be documented.Also documents the user-facing vars the first run surfaced (self-hosted cache, provenance, plugin isolation, Nx Cloud timeouts, etc.) and marks
NX_CLOUD_AUTH_TOKENandNX_CLOUD_DISTRIBUTED_EXECUTION_AGENT_COUNTas deprecated.Related Issue(s)
N/A — internal tooling improvement.