analog

# AGENTS.md

This is the monorepo that contains all the code and infrastructure for AnalogJS.

## Overview

- **Monorepo** managed by [Nx](https://nx.dev) and [pnpm](https://pnpm.io/)
- Main framework: **AnalogJS** (meta-framework for Angular, powered by Vite)
- Contains multiple apps (Angular, Astro, blog, docs, trpc, etc.) and libraries (shared, card, top-bar, etc.)
- Key packages: `@analogjs/platform`, `@analogjs/vite-plugin-angular`, `@analogjs/vitest-angular`, `@analogjs/vite-plugin-nitro`, `@analogjs/router`, etc.
- Node engines: `^22.0.0 || ^24.0.0`, pnpm `^10.0.0`

## Key Files

- `tsconfig.base.json` - TypeScript path aliases for all packages
- `nx.json` - Nx workspace configuration
- `pnpm-workspace.yaml` - pnpm workspace definition
- `release.config.cjs` - semantic-release configuration
- `.github/workflows/` - CI/CD workflows
- `.githooks/` - git hooks (commit-msg, pre-commit)
- `CONTRIBUTING.md` - full contribution guidelines

## Key Workflows

- **Install dependencies:** `pnpm i`
- **Build all projects:** `pnpm build` (uses Nx)
- **Build** `nx build <project>`
- **Serve main app:** `pnpm dev` or `pnpm start` (runs `nx serve`)
- **Test all projects:** `pnpm test` (runs Vitest via Nx)
- **Format workspace:** `nx format`
- **Lint:** `nx lint <project>`
- **Check formatting:** `nx format:check`
- **Storybook:** `nx storybook <project>`
- **Docs site:** `pnpm nx serve docs-analog` (Analog)
- **E2E:** `nx e2e <project>` (Cypress/Playwright)

## Testing a Specific Package

- `nx test <package-name>` (unit tests via Vitest)
- `nx build <package-name>` to verify build
- For E2E: `pnpm e2e`
- Run `nx format:check` to verify formatting

## Project Structure & Conventions

- **Apps:** in `apps/` (e.g., `analog-app`, `astro-app`, `docs-analog`, `blog-app`, etc.)
- **Libraries:** in `packages/` (shared code, features, platform, plugins)
- **TypeScript path aliases:** defined in `tsconfig.base.json`
- **Vite config:** each app has its own `vite.config.ts` (see `apps/analog-app/vite.config.ts` for advanced AnalogJS/Vite usage)
- **Release:** Automated with semantic-release through CI, see `release.config.cjs` and `tools/publish.sh`

## Packages → Commit Scopes

| Directory                      | npm Package                     | Commit Scope          |
| ------------------------------ | ------------------------------- | --------------------- |
| `packages/platform`            | `@analogjs/platform`            | `platform`            |
| `packages/router`              | `@analogjs/router`              | `router`              |
| `packages/content`             | `@analogjs/content`             | `content`             |
| `packages/content-plugin`      | `@analogjs/content-plugin`      | `content-plugin`      |
| `packages/vite-plugin-angular` | `@analogjs/vite-plugin-angular` | `vite-plugin-angular` |
| `packages/vite-plugin-nitro`   | `@analogjs/vite-plugin-nitro`   | `vite-plugin-nitro`   |
| `packages/vitest-angular`      | `@analogjs/vitest-angular`      | `vitest-angular`      |
| `packages/nx-plugin`           | `@analogjs/nx-plugin`           | `nx-plugin`           |
| `packages/create-analog`       | `create-analog`                 | `create-analog`       |
| `packages/storybook-angular`   | `@analogjs/storybook-angular`   | `storybook-angular`   |
| `packages/trpc`                | `@analogjs/trpc`                | `trpc`                |
| `packages/astro-angular`       | `@analogjs/astro-angular`       | `astro-angular`       |

## Agent Skills

Reusable agent workflows live in `.agents/skills/`:

- [`investigate-issue`](.agents/skills/investigate-issue/SKILL.md) - triage a GitHub issue: reproduce the reporter's repo or snippet in an isolated sandbox outside the monorepo, trace the root cause, and draft a reply for the maintainer to confirm before posting.
- [`fix-issue`](.agents/skills/fix-issue/SKILL.md) - end-to-end flow for resolving a GitHub issue: fetch and understand the issue, create a feature branch off `beta`, implement and verify the fix, then hand off to `open-pr`.
- [`open-pr`](.agents/skills/open-pr/SKILL.md) - commit the current work, push the feature branch, and open a GitHub PR against `beta` filled out from the PR template.
- [`handhold-pr`](.agents/skills/handhold-pr/SKILL.md) - watch a PR's CI, pull the real failure logs, separate genuine failures from Nx DTE flakes and pre-existing base breakage, resolve CodeRabbit's major findings, and iterate until the PR is green.

## Contribution Policy

- Use `CONTRIBUTING.md` as the source of truth for base branch, PR requirements, title and commit conventions, supported types/scopes, breaking change notes, and submission expectations.
- Use `.github/PULL_REQUEST_TEMPLATE.md` for PR body structure, including affected scope, test plan, and maintainer-facing merge-strategy recommendations.

## Commit Review Workflow

- Before reviewing branch history, run `git fetch --all`.
- Treat `https://github.com/analogjs/analog.git` as the upstream source of truth and compare the current branch against the relevant `analogjs/*` remote branch.
- If the branch mixes multiple packages or concerns, recommend `git reset --soft <base-commit>` and re-commit the staged changes into smaller, policy-aligned groups.
- Prefer regrouping by affected package or primary package scope using the directory mapping above.
- Before changing GitHub metadata, ask whether the user wants the PR title and description updated. If no PR exists for the branch, ask whether they want one created.
- Treat `Squash merge` as the highly preferred maintainer recommendation.
- Recommend a non-squash merge only when the PR intentionally preserves important commit boundaries, and include a brief note about why those boundaries matter and why the PR should bypass focused changes per package.
- If history is rewritten, remind the user that they can run `git push --force`, but do not do it on their behalf unless they explicitly ask.

## Nx Usage

- **Nx is the orchestrator for builds, tests, linting, and generators.**
- Use `nx run-many --target <target> --all` for bulk operations.
- Project-specific config in `apps/*/project.json` and `libs/*/project.json`.
- Nx plugins and generators are in `packages/nx-plugin`.

## Contribution Patterns & Best Practices

- Always open an issue before a pull request for review by the maintainers. This ensures alignment on implementation of features.
- Keep changes minimal and targeted.
- Backward compatibility is critical for new features, allowing progressive adoption.
- Keep code concise with emphasis on readability, avoid clever solutions and abstractions.
- Treat simplicity as a completion requirement. Before implementing, choose the smallest design that preserves the required behavior. Minimize mutable state, derive redundant values, make ownership explicit, and separate distinct responsibilities with small private functions. Aggregate or deduplicate data when it arrives where practical. Prefer clear names and named types over assertions and complex inferred types. Before reporting completion, review your own diff and simplify unnecessary state, intermediate collections, branching, and abstractions. Validate the simplified implementation.
- Always scan existing codebase for examples and patterns for implementation.
- Prefer using existing Angular APIs, with wrappers where needed.
- Strongly prefer AST parsing instead of regex for complex file manipulation and traversal.
- Always use modern Angular syntax including dependency injection with inject, control flow, signal APIs, and standalone components.
- Cross compatibility with Nx is strongly encouraged. Prefer schematics and builders for Analog first-party solutions.
- Avoid custom code that replicates Angular framework functionality.
- Don't be overly verbose with comments.
- Keep tests lightweight and targeted to critical functionality testing.
- Add concise documentation with descriptive sections to the appropriate guides in the `docs-analog` app.
- Maintain compatibility with Vite versions 6-8, with progressive fallbacks.
- Use other projects as inspiration, but do not directly copy their APIs.
- See `CONTRIBUTING.md` file for more contribution guidelines.

## Do NOT

- Add Angular SFC references to features or docs
- Create new abstractions for one-time operations
- Add verbose comments, docstrings, or type annotations to code you didn't change
- Add error handling or validation for scenarios that can't happen
- Design for hypothetical future requirements
- Inline code from npm packages, preserving OSS dependencies

## Common Pitfalls

- Always run `pnpm i` before building if `pnpm-lock.yaml` has changed
- The `astro-app` is excluded from the main build (`--exclude=astro-app`)
- Git hooks are in `.githooks/` (not `.husky/`), configured via `git config core.hookspath .githooks`
- The `prepare` script sets up git hooks — runs automatically after `pnpm i`

## Integration Points

- **Vite**: All apps use Vite for build/dev, with custom plugins for Angular and Nitro
- **Nitro**: Used for SSR, SSG, and API routes (see `vite.config.ts` and `server.mjs`)
- **Analog**: Docs site in `apps/docs-analog`
- **Storybook**: For Angular components, see `@analogjs/storybook-angular`
- **CI/CD**: Release and publish via semantic-release and custom scripts

## Examples

- **Add a new Angular app:** `nx g @nx/angular:application <name>`
- **Run tests for a lib:** `nx test <lib-name>`
- **Build docs site:** `pnpm nx build docs-analog`

More agent context in analogjs/analog

5 other files this repository gives its agents.