02 · Scaffolding
Creating the projects
Section titled “Creating the projects”Location: /home/sambasene/dev/ (the established project folder — twilight, freecodecamp, yonko… live there).
# public site — Astrogon templatenpm create astro@latest public-docs -- --template astrogon/astrogon --yes
# private site — Starlight templatenpm create astro@latest private-docs -- --template starlight --yesBoth scaffolds reported success — but that was a lie.
Gotcha #1 — node_modules was empty
Section titled “Gotcha #1 — node_modules was empty”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:
npm install # installs packages, silently skipping blocked scriptsnpm install-scripts ls # shows what's blockednpm install-scripts approve @parcel/watcher sharp workerdnpm rebuild sharp workerd @parcel/watcherApprovals were persisted into each package.json (allowScripts field), so fresh clones with npm ci apply them automatically — no global config changes needed.
Reasoning
Section titled “Reasoning”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.
Config fixes
Section titled “Config fixes”public-docs/astro.config.mjs— placeholdersite: "https://janedoe.com"→https://public-docs.pages.dev(and later renamed; see 05)public-docs/wrangler.jsonc— project nameastrogon→public-docsprivate-docs/astro.config.mjs—title: 'My Docs'→'Private Docs', addedsite, 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.
Verification
Section titled “Verification”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:
(npx astro dev --port 4321 &) # public-docs(npx astro dev --port 4322 &) # private-docscurl -s -o /dev/null -w "%{http_code}" http://localhost:4321/ # → 200curl -s -o /dev/null -w "%{http_code}" http://localhost:4322/ # → 200Both were left running in the background (PIDs recorded, stopped for later tests). To restart anytime:
cd ~/dev/public-docs && npm run dev # → :4321cd ~/dev/private-docs && npm run dev # → :4322Reasoning
Section titled “Reasoning”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.