@niondigital/create-astro

Scaffolds a new Astro project from nion's astro-starter: the base template plus any of three composable modules (storyblok, svelte, storybook).

npm create @niondigital/astro@latest my-new-site                          # interactive
npm create @niondigital/astro@latest my-new-site -- --yes --svelte --storybook

Note the -- separator before the flags in the non-interactive form: npm create passes everything after -- to the CLI. --yes is the agent/CI form (accept defaults, never prompt).

A GitHub token is required only to clone the private template repo. The CLI resolves it from --token, GITHUB_TOKEN, GIGET_AUTH, or a healthy gh auth session. Dependencies install from public npm — no token needed for that.

Development

nvm use                 # Node 24.16.0 (see cli/.nvmrc)
npm ci
npm run build           # tsdown → dist/index.mjs
npm run dev -- <args>   # run from source (node src/index.ts)
npm test                # 74 fast unit/contract tests
npm run typecheck       # tsc --noEmit

Tests

• npm test — the fast unit/contract suite (src/**/*.test.ts), incl. the modules.manifest ↔ docs cross-check. Configured via vitest.config.ts, which excludes the slow scaffold harness.

• npm run test:e2e — the scaffold e2e harness (test/scaffold.e2e.test.ts, via vitest.e2e.config.ts). It is RUN_E2E-guarded and builds + verifies a real scaffold per module combo, so it is slow. It needs no token — every combo is --local (no remote clone) and the template's @niondigital/* deps install from public npm:

  npm run build
  npm run test:e2e                     # all 6 combos
  # filter to a subset:
  RUN_E2E=1 npx vitest run --config vitest.e2e.config.ts -t 'svelte'

  The harness runs the built bin (node cli/dist/index.mjs <tmpdir> --local <repoRoot>/template --yes <flags>) into os.tmpdir() for each of the six valid combos (base, --storyblok, --svelte, --svelte --storybook, --storyblok --svelte, --storyblok --svelte --storybook) and asserts the module gates: the Storyblok rule#1 ESLint guard fires on a forbidden @storyblok import in src/components, a hydrated astro-island appears in built HTML for svelte combos, and build-storybook produces storybook-static/index.html.

CI

Workflow: .github/workflows/cli-ci.yml. Two jobs:

• unit — runs on every PR (and on push to main/develop) touching cli/**, docs/modules/**, template/**, or the workflow file. Steps: npm ci → npm run build → npm run typecheck → npm test. Fast; no scaffold installs and no token needed (the CLI's own deps are public).
• e2e — runs the scaffold harness, gated so it does not run on every PR. It triggers only when:
  • the weekly schedule fires (cron: '0 6 * * 1', Mondays 06:00 UTC), or
  • the workflow is dispatched manually (workflow_dispatch), or
  • a PR carries the run-e2e label (the pull_request trigger includes the labeled type, so adding the label re-runs it on an existing PR).

Triggering e2e manually

• Add the run-e2e label to a PR, or
• Go to Actions → cli-ci → Run workflow (workflow_dispatch).

e2e auth requirement

None. Every combo is --local (no remote clone) and the template's @niondigital/* deps install from public npm, so the e2e job runs with no secrets (permissions: contents: read only).