CLAUDE.md · nrwl/nx

Sections

1. Documentation Contributions
2. GitHub Issue Response Mode
3. Avoid making changes to generated files
4. Code Comments
5. Essential Commands
6. Fixing GitHub Issues
7. Pull Request Template
8. General Guidelines for working with Nx
9. Scaffolding & Generators
10. When to use nxdocs

First lines (shown under the repo's MIT license)

When responding to queries about this repository:

1. Suggest relevant commands from the "Essential Commands" section when applicable
2. Highlight Nx's focus on monorepos and its key features like smart task execution, code generation, and project graph
   analysis
3. Mention the plugin ecosystem and support for various frameworks when relevant
4. Emphasize the importance of running the full validation suite before committing changes

Always strive to provide accurate, helpful responses that align with the best practices and workflows described in this
file.

## Documentation Contributions

When working on Nx documentation, all documentation content lives in the `astro-docs/` folder. This is the new Astro-based documentation site built with Starlight.

**Important**: Before making any documentation changes, read the `astro-docs/README.md` file for detailed guidance on:

- Project structure and architecture
- Content types (regular docs, dynamic plugin docs, CLI docs)
- Available Markdoc tags for rich content
- Development workflow and commands
- Sidebar management

**MANDATORY**: After editing any file in `astro-docs/src/content/`, run the `check-docs-style` skill. No exceptions.

**MANDATORY**: All documentation content must follow `astro-docs/STYLE_GUIDE.md`. vale only enforces its mechanical rules, so check the structural and voice rules yourself.

### Quick Reference

- Documentation content: `astro-docs/src/content/docs/`
- Use `.mdoc` (Markdoc) or `.mdx` format for documentation files
- Run `nx serve astro-docs` to start the local dev server
- Sidebar structure is defined in `astro-docs/sidebar.mts`

## GitHub Issue Response Mode

When responding to GitHub issues, determine your approach based on how the request is phrased:

### Plan-First Mode (Default)

Use this approach when users ask you to:

- "analyze", "investigate", "assess", "review", "examine", or "plan"
- Or when the request is ambiguous

In this mode:

1. Provide a detailed analysis of the issue
2. Create a comprehensive implementation plan
3. Break down the solution into clear steps
4. Then please post the plan as a comment on the issue

### Immediate Implementation Mode

Use this approach when users ask you to:

- "fix", "implement", "solve", "build", "create", "update", or "add"
- Or when they explicitly request immediate action

In this mode:

1. Analyze the issue quickly
2. Implement the complete solution immediately
3. Make all necessary code changes. Please make multiple commits so that the changes are easier to review.
4. Run appropriate tests and validation
5. If the tests, are not passing, please fix the issues and continue doing this up to 3 more times until the tests pass
6. Once the tests pass, push a branch and then suggest opening a PR which has a description of the changes made, and
   that
   it make sure that it explicitly says "Fixes #ISSUE_NUMBER" to automatically close the issue when the PR is merged.

## Avoid making changes to generated files

Files under `generated` directories are generated based on a different source file and should not be modified directly.
Find the underlying source and modify that instead.

## Code Comments

A comment earns its place only by saying something the code cannot. The default is **no comment** — clearer names,
smaller functions, and explicit types usually beat one. When warranted, it is a line or two in the terse style of the
surrounding code. Past ~3 lines, it should have been cut down or moved into the commit message.

Keep it true. A comment that contradicts the code is worse than no comment, so when you change code, update or delete
the comments around it — a stale comment is a bug and review treats it as one.

**MANDATORY**: the paragraph above is orientation, not the rule set. The full rules live in
`.claude/agents/comment-analyzer.md` — read it before writing or editing a comment, before adding a `TODO` or
`@deprecated` marker, and before changing what counts as a comment defect. That file is authoritative for writing
comments as well as for reviewing them, and it is not loaded automatically, so you must open it.

## Essential Commands

### Code Formatting

After code changes are made, please make sure to format the files with oxfmt via `npx oxfmt FILE_NAME`

oxfmt skips `.mdoc` files, so format edited docs content with `pnpm nx run astro-docs:format:write` instead.

### Pre-push Validation

```bash
# Full validation suite - run before committing
nx prepush
```

If the prepush validation suite fails, please fix the issues before proceeding with your work. This ensures that all
code adheres to the project's standards and passes all tests. DO NOT make a new commit to fix these issues. Instead,
amend the current commit.

### Testing Changes

After code changes are made, first test the specific project where the changes were made:

```bash
nx run-many -t test,build,lint -p PROJECT_NAME
```

After verifying the individual project, validate that the changes in projects which have been affected:

```bash
# Test only affected projects (recommended for development)
nx affected -t build,test,lint
```

As the last step, run the e2e tests to fully ensure that changes are valid:

```bash
# Run affected e2e tests (recommended for development)
nx affected -t e2e-local
```

## Fixing GitHub Issues

When working on a GitHub issue, follow this systematic approach:

### 1. Get Issue Details

```bash
# Get issue details using GitHub CLI (replace ISSUE_NUMBER with actual number)
gh issue view ISSUE_NUMBER

# View multiple issues efficiently in one command
gh issue list --limit 50 --json number,title,state,labels,assignees,updatedAt,body --jq '.[] | select(.number == 123 or .number == 456 or .number == 789)'

# Or filter by specific criteria to get multiple related issues
gh issue list --label "bug" --state "open" --json number,title,body,labels --jq '.[]'
gh issue list --assignee "@me" --json number,title,body,state --jq '.[]'
```

**Tip**: Instead of running `gh issue view` multiple times, use `gh issue list` with JSON output and filtering to gather
information about multiple issues in a single command. This is much more efficient than viewing issues one at a time.

**Always provide clickable links**: When discussing GitHub issues or PRs, always include the full GitHub URL so the user
can easily open them in their browser. For example:

- Issue #12345: https://github.com/nrwl/nx/issues/12345
- PR #67890: https://github.com/nrwl/nx/pull/67890

When cloning reproduction repos, please clone within `./tmp/claude/repro-ISSUE_NUMBER`

### 2. Analyze the Plan