Skip to content

02 · Scaffolding

Location: /home/sambasene/dev/ (the established project folder — twilight, freecodecamp, yonko… live there).

Terminal window
# public site — Astrogon template
npm create astro@latest public-docs -- --template astrogon/astrogon --yes
# private site — Starlight template
npm create astro@latest private-docs -- --template starlight --yes

Both scaffolds reported success — but that was a lie.

create-astro said “Dependencies installed”, yet ls node_modules | wc -l returned 0 in both projects. The culprit: npm 11.19.0’s allow-scripts guard (the machine’s global ~/.npmrc restricts install scripts to an allow-list: netlify-cli,esbuild,unix-dgram,sharp).

Fix:

Terminal window
npm install # installs packages, silently skipping blocked scripts
npm install-scripts ls # shows what's blocked
npm install-scripts approve @parcel/watcher sharp workerd
npm rebuild sharp workerd @parcel/watcher

Approvals were persisted into each package.json (allowScripts field), so fresh clones with npm ci apply them automatically — no global config changes needed.

Blocked scripts were the standard native-build ones (sharp = image optimization, workerd = Cloudflare runtime for wrangler, @parcel/watcher = dev file-watching). All benign and needed; approving them is the correct call, and persisting per-project keeps the global guard intact.


  • public-docs/astro.config.mjs — placeholder site: "https://janedoe.com" → https://public-docs.pages.dev (and later renamed; see 05)
  • public-docs/wrangler.jsonc — project name astrogon → public-docs
  • private-docs/astro.config.mjs — title: 'My Docs' → 'Private Docs', added site, pointed the GitHub social link at the real repo

Also discovered the Astrogon template already ships: @astrojs/cloudflare adapter, wrangler.jsonc, Pagefind search as a postbuild step, KaTeX, remark-toc, shiki themes.


Terminal window
npm run build # public-docs: 55 pages indexed by Pagefind ✅
npm run build # private-docs: 4 pages + sitemap ✅ (warning fixed by setting site)

Local dev smoke test — both servers booted and answered:

Terminal window
(npx astro dev --port 4321 &) # public-docs
(npx astro dev --port 4322 &) # private-docs
curl -s -o /dev/null -w "%{http_code}" http://localhost:4321/ # → 200
curl -s -o /dev/null -w "%{http_code}" http://localhost:4322/ # → 200

Both were left running in the background (PIDs recorded, stopped for later tests). To restart anytime:

Terminal window
cd ~/dev/public-docs && npm run dev # → :4321
cd ~/dev/private-docs && npm run dev # → :4322

Verified build and dev-server behavior before touching git — a broken scaffold would have poisoned every later step. The pkill cleanup accidentally self-matched (pkill -f "astro dev" matched its own command line) — lesson: kill by PID, not broad patterns.