start-astro

name	start-astro
description	Scaffold a new Astro project (minimal template) with a ready-to-use, scalable architecture — a shared Layout + Header (logo + centered nav) + Footer, a zero-dependency light/dark theme toggle, native Astro View Transitions, a `@/`→`src/` path alias, a SITE + ROUTES single-source-of-truth config, icons (`@lucide/astro` + custom brand SVGs), Content Collections wired up, a 404 page, and an open backend door (`lib/` + `pages/api/`). Use when starting, creating, or bootstrapping a new Astro site/project/"proyecto astro" from scratch, or when the user wants a base/starter ready to grow from a portfolio to a full app. Generates the project via `bun create astro@latest` (minimal/empty template), writes the full structure, installs deps (incl. @lucide/astro), and verifies the production build.
license	Complete terms in LICENSE.txt
metadata	{"author":"bastndev","version":"2.0.0"}

start-astro

Scaffolds a publishable, scalable Astro base: the clean minimal template, then a hand-written architecture on top — Layout + Header + Footer + 4 pages (incl. 404) + light/dark toggle + View Transitions + @/ alias + SITE/ROUTES config + icons + Content Collections + a backend door. The stuff you set up every single time you start an Astro project, done once, correctly. It starts as light as a portfolio, but every folder a growing app needs is already there — so you never restructure, you only fill in.

When to use

The user wants to start a new Astro project: "create/scaffold/bootstrap a new astro project", "set up an astro site", "necesito un proyecto de astro listo", or they have an empty folder and want a base with theme switching, navigation, icons, and a scalable structure already working.

---

Why minimal, not basic

bun create astro@latest offers four templates. This skill always picks "Use minimal (empty) template", not "A basic, helpful starter project (recommended)".

Why: the "basic" template ships its own boilerplate page, default styles, and an Astro logo/welcome component that would all need to be located and deleted before this architecture can go in cleanly. That's an extra, error-prone step that also drifts depending on whatever Astro bundled in that release. minimal gives an empty src/pages/index.astro and nothing else — everything this skill adds is therefore exactly what's in references/, no leftover files, no guessing what to delete.

---

Architecture at a glance

src/
├── assets/icons/{social,theme}/   custom + brand SVGs (imported as components)
├── components/{ui/,Header,GXB}    reusable UI
├── sections/Footer.astro          page-level blocks
├── layouts/Layout.astro           HTML shell (ClientRouter + no-flash theme + Header + Footer)
├── content/                       Content Collection entries (empty, ready)
├── pages/{index,work/index,contact/index,404,api/hello}
├── lib/utils.ts · types/index.ts
├── styles/global.css              design tokens (light + dark) + footer + toggle CSS
├── consts.ts                      SITE + ROUTES (single source of truth)
└── content.config.ts · env.d.ts
ARCHITECTURE.md · README.md · .prettierignore · tsconfig.json (@/ alias)

The whole base is built on one principle: a single source of truth. The project name lives once in SITE.name (src/consts.ts); the tab title, header brand, and footer all derive from it. The top-level routes live once in ROUTES; the header nav and the 404 page both read it. So the project name and routes are written in exactly one file each — everything else is name-free.

---

Procedure

1. Gather inputs:

   • PROJECT_NAME — the user already created and named their folder before invoking this skill. Detect it automatically from the current working directory (pwd / the basename of the folder Claude is operating in) and use it as-is — never ask the user to name the project, and never request a name in chat. The folder's existing name (e.g. TEST1) is the project name, exactly as the user typed it (preserve its original casing — don't lowercase/slugify it).
   • DIR — always . (the current directory). This skill scaffolds into the folder the user is already standing in; it does not create a new sibling folder and does not rename anything.
   • PAGES — default Home, Work, Contact (the standard set this skill ships). Only deviate if the user explicitly asks for different sections.

2. Scaffold via the official CLI, into the current folder — the user already made and is standing inside their project folder (e.g. TEST1), so this always targets ., never a new named folder:

   bun create astro@latest . -- --template minimal --no-install --no-git --skip-houston
   

   • . → scaffold into the current directory; this skill never creates a new folder or renames the existing one.
   • Never create a separate, temporary, or differently-named project folder (e.g. test-project1, astro-scaffold, a /tmp copy, a sibling dir) to scaffold or "test" in and then move/delete. There is exactly one project and it is the current folder. Run every command — scaffold, install, build — directly here.
   • --template minimal → the empty template (see rationale above).
   • --no-install → this skill controls the install step explicitly (next steps), keeps output readable.
   • --no-git → don't assume the user wants a fresh git repo; skip unless asked.
   • --skip-houston → skip the mascot/animation prompt, keep it non-interactive.
   • If any flag is rejected by the installed create-astro version, fall back to running it without flags and answer the interactive prompts yourself: dir → ., → minimal/empty, decline git init, decline install.

---

Gotchas checklist (verify before declaring done)

• Project name detected from the current folder's name — never asked the user, never invented a separate name
• {{PROJECT_NAME}} substituted in only consts.ts, README.md, ARCHITECTURE.md — pages/Layout/Header/Footer are name-free (the name flows from SITE.name); the footer is {SITE.name} © year, never a hardcoded mark
• Used minimal template, not basic — no boilerplate to clean up
• tsconfig.json overwritten with the @/→src/* alias (extends astro/tsconfigs/strict; no baseUrl, no React jsx/jsxImportSource)
• Footer CSS and theme-toggle icon CSS live in global.css, NOT in a scoped <style>. They depend on [data-theme] on <html>, an ancestor a component's scoped styles can't target — scope them and the toggle icon freezes (stuck on the moon) and the footer flashes left-aligned on load
• Theme-toggle icons are imported SVG components (@/assets/icons/theme/{sun,moon}.svg) rendered as <Sun id="icon-sun" aria-hidden="true" /> / <Moon id="icon-moon" aria-hidden="true" />
• Theme toggle script runs on astro:page-load (not only initial load) and the no-flash <head> script re-applies on astro:after-swap — both required so theme + toggle survive View Transitions
• <ClientRouter /> imported from astro:transitions and placed in Layout.astro's <head>
• GXB.astro written byte-for-byte from the reference — the ASCII art is not edited, renamed, or moved (404.astro reuses it)