ng-ready

ng-ready restores existing Angular + NG-ZORRO workspaces without upgrading them and creates version-matched Angular + NG-ZORRO starters with one command.

It supports npm and nvm-sh on macOS, Linux, and WSL. Native Windows, Yarn, and pnpm are intentionally refused in V1.

Install globally

After publishing, install the CLI globally with:

npm install --global ng-ready
ng-ready --version
ng-ready --help

You can use it without a global install through npx:

npx ng-ready@latest doctor
npx ng-ready@latest create@17 office-dashboard

To publish a checked-out release from a maintainer environment:

npm install
npm run lint
npm run typecheck
npm test
npm run build
npm pack
npm login
npm publish --access public

create@17 is the requested Angular version; ng-ready@latest is the npm package version. They are independent selectors.

Recover an old application

cd legacy-project
npx ng-ready doctor
npx ng-ready fix
nvm use
npm start

doctor and inspect are offline and read-only. They inspect package.json, npm lock metadata, Angular workspace configuration, .nvmrc, .node-version, and package manifests under node_modules as data. They do not load project JavaScript.

fix selects a compatible Node release through nvm-sh, writes an exact .nvmrc, prefers npm ci when a lockfile exists, and verifies the local Angular CLI. It never runs ng update, upgrades Angular, changes NG-ZORRO, or deletes a lockfile.

Because npm lifecycle scripts execute project and dependency code, recovery commands print a warning. Disable them explicitly when appropriate:

ng-ready install --ignore-scripts

Peer-dependency relaxation is never automatic:

ng-ready repair --legacy-peer-deps

Create an Angular + NG-ZORRO application

npx ng-ready create@17 office-dashboard
cd office-dashboard
nvm use
npm start

The command resolves exact stable Angular, Angular CLI, NG-ZORRO, and Angular CDK releases before creating a directory. It selects a supported Node version, invokes the matching Angular CLI temporarily, installs exact framework dependencies, generates the side-menu starter, records .nvmrc and .ng-ready.json, and passes a production build before reporting the project ready.

Generated applications include:

• TypeScript, CSS, and Angular Router
• matching NG-ZORRO and Angular CDK releases
• a responsive collapsible side navigation and header
• Dashboard, Users, and Settings routes
• version-appropriate NgModule (Angular 14–16) or standalone (Angular 17+) structure
• narrowly registered menu, dashboard, user, and settings icons

Version forms are major, major/minor, exact, or latest stable:

ng-ready create@14 admin
ng-ready [email protected] office-app
ng-ready [email protected] crm
ng-ready create@latest portal

create@17 selects the target Angular generation. In contrast, ng-ready@latest selects the npm CLI package:

npx ng-ready@latest create@17 dashboard

Useful creation options:

--skip-git             do not initialize Git
--directory <path>     use an explicit destination
--node <version>       override Node after range validation
--no-build             explicitly skip final build validation
--json                 emit JSON only on stdout

Existing or non-empty destinations are never overwritten. If a later creation step fails, generated files are preserved for diagnosis.

Commands

doctor                 diagnose and recommend recovery (read-only)
inspect                return project evidence (read-only)
fix                    select Node, restore dependencies, and verify
install                restore dependencies after compatibility checks
repair                 conservative dependency restoration
verify [--build]       run local Angular CLI checks and optional build
snapshot               atomically write .ng-ready.json
start -- <args>        run npm start, or local ng serve
build -- <args>        run the local Angular build
create@<version> NAME  create and validate a new starter

Run ng-ready --help for all options. inspect, doctor, and verify support --json. JSON mode reserves stdout for a single JSON document.

Exit codes are 0 for healthy/success, 1 for a recoverable failure, 2 for an unsupported environment, and 3 for invalid metadata or invocation.

Common command examples:

# Existing project diagnosis and repair
ng-ready doctor
ng-ready inspect --json
ng-ready fix --build
ng-ready install --ignore-scripts
ng-ready verify --build
ng-ready snapshot

# Run the local project tools
ng-ready start -- --port 4300
ng-ready build -- --configuration production

# New projects
ng-ready create@14 admin-panel --skip-git
ng-ready [email protected] office-dashboard --directory ./projects/office-dashboard
ng-ready create@latest portal --node 24.15.0
ng-ready create@17 dashboard --no-build

Use --json with inspect, doctor, verify, or create@... when another tool needs machine-readable output. JSON mode keeps stdout as one JSON document and sends failures to the structured result.

Compatibility policy

Offline Angular/Node/TypeScript/RxJS data is kept in src/compatibility/angular.ts. It was verified on 2026-09-08 against the official Angular version compatibility table and Angular release policy.

NG-ZORRO documents that its major tracks Angular's major in its official FAQ. Creation additionally checks the selected release's npm peer metadata before touching the destination. create@latest uses the npm registry's stable latest tag and rejects prereleases.

Development

npm install
npm run lint
npm run typecheck
npm test
npm run build
npm run test:e2e
npm pack

No telemetry is collected.