Skip to content

development.md

Latest commit

 

History

History
234 lines (173 loc) · 12.5 KB

development.md

File metadata and controls

234 lines (173 loc) · 12.5 KB
Raw
title Development setup
description Set up the repository, run the devtools UI and the demo apps, and run the same checks as CI.
Clone, install, and run the devtools against a real Angular app. The same checks CI runs, on your machine.

Development setup

The repository is an Nx workspace with pnpm. It holds the npm package, the devtools UI, the Chrome extension, two demo apps and this docs site.

Prerequisites

.nvmrc pins 24, and the root package.json requires >=24. The root package.json sets packageManager to pnpm@10.33.4.

Set up the repository

git clone https://github.com/santoshyadavdev/angular-devtools.git
cd angular-devtools
pnpm install

pnpm-workspace.yaml lists packages/*, examples/* and apps/*, so one install covers every project.

Git hooks

pnpm install sets core.hooksPath to .githooks and commit.template to .gitmessage. If you already set either one yourself, it keeps your value.

Hook What it does
pre-commit Formats the staged files with Prettier and stages the result. It skips a file that also has unstaged changes, so hunks you left out with git add -p stay out of the commit.
commit-msg Checks the message against the commit message guidelines. It prints a warning and never blocks the commit.

Project structure

app/                          # Devtools UI SPA (Angular + Vite)
  src/app.ts                  # Root component with tab navigation
  src/pages/                  # One component per tab
  vite.config.ts              # Vite config with the Analog Angular plugin
packages/
  ng-devtools/                # Publishable npm package
    src/devframe.ts           # defineDevframe(): the tool definition
    src/overlay.ts            # Client script running in the user's page
    src/rpc/                  # Node-side RPC functions and agent tools
extension/                    # Chrome DevTools extension
examples/analog/              # Analog demo app
apps/docs/                    # This documentation site
src/                          # Angular Travel, the host demo app

Nx projects

Project Root Targets
angular-devtools . (project.json) build, serve, test
@santoshyadavdev/ng-devtools packages/ng-devtools build
analog-demo examples/analog dev, build, preview
angular-devtools-docs apps/docs dev, build, test, and more

Run pnpm exec nx show projects to list them. Package projects get their targets from their package.json scripts.

Run things

Root scripts

Most work goes through the root package.json scripts:

pnpm devtools:dev        # Devtools UI with hot reload and live RPC
pnpm devtools:build      # Build the devtools UI SPA into dist/devtools-ui
pnpm devtools:build-pkg  # Build the npm package (library + UI in dist/)
pnpm start               # Build the package, then serve Angular Travel

Nx targets

The scripts call Nx. You can also run a target on a project directly:

pnpm exec nx build                              # Angular Travel
pnpm exec nx build @santoshyadavdev/ng-devtools # The npm package
pnpm exec nx build angular-devtools-docs        # This site
pnpm exec nx test                        # Angular Travel
pnpm exec nx test angular-devtools-docs  # This site
pnpm exec nx serve         # Angular Travel on port 4200
pnpm exec nx dev analog-demo
pnpm exec nx affected -t test build

build and test are cached. build runs the build of its dependencies first, so building a demo also builds the package.

The package's build target lists app/** as an input. A change to the devtools UI invalidates the package build.

Ports

Command Port Notes
pnpm start 4200 ng serve with SSR and hot reload. The popup and live data work without a separate server.
pnpm build --configuration development && node dist/angular-devtools/server/server.mjs 4000 The demo app as an SSR server.
pnpm devtools:dev 5173 The devtools UI with hot reload and its own RPC. Source-scan data only; live tabs need an app page connected, so use the SSR server for those.
The SSR server serves the UI built into packages/ng-devtools/dist/public. Run pnpm devtools:build-pkg to refresh it after you change app/.

Run the checks

Run the same checks as CI before you open a PR:

pnpm format:check                   # Prettier
pnpm typecheck                      # Host app + specs, devtools UI and Analog demo (with templates), devtools package + its tests
pnpm exec nx affected -t test build # Test and build affected projects
pnpm test:devtools                  # Devtools package tests (Vitest)
pnpm test:panel                     # Devtools UI tests (Vitest)
pnpm test:axe                       # axe check of every panel page (needs Chromium)
pnpm extension:build                # Chrome extension
pnpm skills:check                   # Agent skills and roles in .claude/
pnpm commit:check                   # Commit messages on your branch

pnpm typecheck runs ngc on app/tsconfig.json and examples/analog/tsconfig.app.json, so template errors fail it. app/tsconfig.json turns on strictTemplates.

pnpm test:panel runs the tests in app/src/__tests__ in jsdom, with the Analog Angular plugin compiling the components. pnpm test:axe builds the package, writes a static report of Angular Travel to dist/panel-axe, serves it, and runs axe on every tab and on each hub view (?view=ngrx, analog, nativescript, capacitor) in light and dark color schemes. It fails on any violation or page error. Run pnpm exec playwright install chromium once before the first run.

pnpm skills:check validates the frontmatter of every skill and role and checks that the files and links they mention exist. pnpm commit:check checks every commit on your branch that is not on main (it compares with upstream/main, then origin/main, then main).

What CI runs

.github/workflows/ci.yml runs on pushes and pull requests to main, in this order:

pnpm install --frozen-lockfile on the Node version from .nvmrc. pnpm format:check, pnpm skills:check, then pnpm typecheck. nx affected -t test build, compared against the last green commit on main. pnpm test:devtools, then pnpm test:panel. pnpm extension:build. The job fails when extension/ui differs from the committed copy. node bin.mjs --help.

A separate axe job in the same workflow installs Chromium and runs pnpm test:axe.

Pull request checks

Two more workflows run on pull requests. Both only warn. They never fail the pull request.

Workflow File What it checks
Commit message .github/workflows/commit-message.yml The pull request title and every commit message. The title becomes the commit on main when the pull request is squash merged.
Docs check .github/workflows/docs-check.yml That a change to packages/ng-devtools/src/, app/src/ or the top-level files in extension/ also changes a page in apps/docs/src/content. Tests don't count.

If a code change needs no docs change, add the no-docs label to the pull request and say why in the description. The Docs check workflow then skips the warning.

Make changes

Add an RPC function

  1. Create the function in packages/ng-devtools/src/rpc/.
  2. Register it in packages/ng-devtools/src/devframe.ts.
  3. Map it to its inspector in RPC_INSPECTOR in packages/ng-devtools/src/config.ts, so turning the inspector off removes it.
  4. Call it from the UI in app/src/pages/.

Add a tab

  1. Create a component in app/src/pages/.
  2. Import and add it to app/src/app.ts (imports array, tabs array, template switch).
  3. Add a card to app/src/pages/dashboard.ts.

Add an agent tool

Add agent: { description } to an RPC function, or call ctx.agent.registerTool() in the devframe setup. List the tool on the Tools page.

Map a registered tool to its inspector in AGENT_INSPECTOR in packages/ng-devtools/src/config.ts, so inspectors and agent.tools can hide it. A tool that acts on the page sets safety: 'action', so agent.readOnly drops it. See Configuration.

Run pnpm extension:build and commit extension/ui. CI fails when it is stale. See Build the extension.

Work on the docs

This site lives in apps/docs. It is built with NgMd on *Analog.

pnpm docs:dev     # Dev server
pnpm docs:build   # Production build

Pages are markdown files under apps/docs/src/content. The sidebar comes from apps/docs/src/ngmd.config.ts.

The build fails on broken internal links and on raw external anchors without target="_blank". Run pnpm docs:build before you open a PR.

Where to next