npm Scripts Guide

This page explains every script in the repository root package.json, when to use it, and which order to run scripts for common workflows.

All commands assume you are in the repository root after npm install (or npm ci).

Recommended sequences

Use these sequences instead of running every script ad hoc. Later steps usually depend on earlier builds or reports.

1. First-time setup

npm ci
npm run architecture:verify
npm run version:check
npm run build:packages
npm start

2. Daily local development

Pick one path:

Whole platform (recommended default)

npm start

Multi-host platform (separate ports for docs/showcases)

npm run start:multi-host

Live Angular/React servers behind the portal

npm run portal:dev

One showcase only

npm run serve:vanilla-showcase
# or serve:angular-showcase / serve:react-showcase / serve:docs

3. After code changes (before a PR)

npm run version:check
npm run architecture:verify
npm run lint:all
npm run test:ci
npm run build:site
npm run site:verify
npm run test:hosting
npm run security:quick

Optional focused checks:

npm run test:e2e:smoke
npm test
npm run reports:open

4. Generate browsable test/coverage reports

npm run test:reports
npm run reports:open

Or the CI-shaped path used by release gates:

npm run test:ci

5. Security scanning

npm run security:quick      # day-to-day
npm run security:full       # broader local scan + SBOM
npm run release:security    # strictest gate before publishing

Install Gitleaks, Semgrep, and Dependency-Check (or Docker) for full/release profiles. See Release & Versioning and the repository file tools/security/README.md.

6. Release / publish rehearsal

Do not start with publish. Follow this order:

npm run release:dry-run
# or the fuller local gate:
npm run release:verify

Only after a green rehearsal and an intentional tag/trusted-publisher setup:

# preferred explicit local publish
VRE_CONFIRM_PUBLISH=YES npm run release:publish

# or existing wrapper (also runs release:verify first)
npm run publish:packages

Tagged releases on GitHub run .github/workflows/release.yml, which re-runs the quality gates and publishes with provenance.

7. Hosted evidence refresh (slow)

npm run evidence:refresh

This runs unit/coverage reports, the full Playwright suite, then publishes evidence into the hosted site layout. Prefer test:e2e:smoke during normal development.

Decision cheat sheet

Script reference

Aliases are noted where a script simply forwards to another command.

Launch & serve

Build

Build dependency order for publishable packages:

core → angular
core → react

Single-host site order:

build:packages → build:platform → hosted showcase builds → build-site packager

Version, architecture, branding

Security

Reports land in reports/security/ (gitignored) and can be published to the hosted Reports → Security page via npm run evidence:publish. Details: Security Scanning & Reports, Release & Versioning, and the repository file tools/security/README.md.

Release & publish

Recommended release order:

release:security
   → tests / lint (via dry-run or verify)
   → build packages
   → SBOM / inspect / pack
   → explicit publish

Unit, coverage, and report generation

Typical report sequence:

test:reports → reports:verify → reports:open

Playwright E2E & hosting navigation

Suggested E2E order while developing:

test:e2e:smoke → focused tag suite → test:e2e → test:e2e:full (before evidence/release)

Evidence publishing

Lint

What not to run first

Related docs

• Architecture
• Single-Host Deployment
• Release & Versioning
• Testing, Coverage & Reports
• Playwright E2E Testing