Astro content site

Generators: create the baseline first

Generator documentation reviewed: 2026-10-23. Evidence: documentation-reviewed; disposable create-astro basics scaffold, install, build and local dev HTTP smoke check executed.

Required workflow

• Before writing a new project's application files, read its profile's starting points and use the official framework or language initializer appropriate to the component. Do not hand-recreate a generated skeleton. Where no full application generator exists, use the documented module/package initializer and assemble only the missing application pieces.
• Choose one starting point per component. Check the installed generator's version and help, prerequisites, template, database, UI, test and runtime options. Commands are examples: replace names and paths, resolve compatible versions, and record the exact invocation and selected options. Do not blindly run every listed generator.
• Generate in a new empty destination. For an existing repository, preserve its conventions and use relevant incremental generators. If a baseline comparison is needed, generate a separate disposable reference with matching versions/options and reconcile deliberately; never regenerate over existing work.
• Keep applicable generated configuration, hidden files, formatter/linter settings, ignore rules, manifests, lockfiles, tests, wrappers and entry points. Extend them for the project instead of replacing them with abbreviated handwritten copies. A generator may initialize version control or offer a commit; respect the user's Git instructions.
• Run the generated baseline's documented checks before feature changes, then relevant checks after configuration and implementation. Inspect what version control would include, including hidden files, build output, local secrets and operating-system metadata. Add needed ignore rules explicitly: no generator guarantees that .DS_Store or every local artifact is ignored.
• Use follow-up generators only when their feature or tool is selected. Review generated changes and dependencies, apply required migrations in the intended environment, and exercise the generated behavior. Scaffolding does not establish authorization, safe retries, production readiness or every best practice.
• If the required generator, template or IDE is unavailable, report the missing prerequisite and the documented route. Do not silently substitute a handwritten scaffold. Keep documentation review, generator execution, baseline checks and application qualification as separate evidence.

Choose a starting point

Official create-astro basics template

Use when: A new content-first site has repeatable pages, typed content or selective interactive components and can start with static output.

1. Use an unused source directory outside synchronized storage. Read project requirements and decide whether source content belongs in Git or an already-selected headless CMS.
2. Check current Astro Node requirements and inspect create-astro help before selecting flags. For the tested create-astro 5.3.1 CLI, the command below generated the basics template with no package installation, Git initialization or AI instruction files.
3. Install dependencies in the generated project with the selected package manager. Record resolved create-astro, Astro, Node and package-manager versions, commit the lockfile, and retain generated scripts and configuration.
4. Create explicit page routes for content. If a collection should produce one URL per entry, define a schema and a dynamic route using getStaticPaths; collection files alone do not create pages.
5. Review public routes, canonical site URL, trailing slashes, redirects, sitemap, 404 behavior and static asset paths before connecting the intended host.

Working directory: An unused local source-workspace parent outside synchronized storage; my-site must not already exist

Check Node against the current Astro installation requirement.

node --version

Working directory: An unused local source-workspace parent outside synchronized storage; my-site must not already exist

Inspect the currently resolved create-astro flags before scaffolding.

npm create astro@latest -- --help

Working directory: An unused local source-workspace parent outside synchronized storage; my-site must not already exist

Generate the official basics project without installing dependencies, initializing Git or creating AI instruction files.

npm create astro@latest my-site -- --template basics --no-install --no-git --no-ai --yes --skip-houston

Working directory: The generated my-site directory

Install the dependencies generated by the CLI and create the package lockfile.

npm install

• The tested CLI version was create-astro 5.3.1; it resolved Astro 7.4.2 from the template. The command-line `--no-ai` option came from the installed CLI help; confirm it remains supported before reusing this command.
• Replace my-site with the intended unused directory. `@latest` is a scaffold-time lookup; pin the selected runtime through project policy and use the generated lockfile for later installs.
• The disposable qualification used Node 24.21.0 and npm 11.19.0. It ran `npm ci`, `npm run build`, `npm run dev -- --host 127.0.0.1`, and fetched `/` with HTTP 200 and `text/html`. This only verifies the untouched basics starter, not an application, integration, CMS, adapter or production host.
• The project README remains the owner of purpose, start commands and content/workflow navigation. Do not create or rely on project AGENTS.md files.

Conditional follow-up generators

Content Collections

Use when: Markdown or structured content needs a validated schema and generated pages; do not add a collection layer for a handful of stable one-off pages.

1. Define the content shape and source owner before writing a schema. Use local files for Git-reviewed content or fetch from the selected CMS without changing that CMS's editorial ownership.
2. Create the collection schema and an explicit route template. Call getCollection and getStaticPaths to create static URLs for entries; verify the final route names and content output.
3. Test malformed content at build time and check empty, draft and missing-route behavior. Preview/editor access is a separate CMS integration and authorization concern.

• Astro validates collection entries against schemas and generates TypeScript support, but collection entries do not become pages automatically.
• If editors need a visual workflow, select a headless CMS and define ownership for drafts, preview, approvals, publishing hooks and media. Astro itself is not that editorial interface.

Server adapter

Use when: A specific route needs request-time rendering, request cookies/headers or private personalization, and the selected host/runtime can operate the chosen adapter.

• Read the current adapter guide and the selected host's support limits before adding it. Astro's default output is static; on-demand rendering requires an adapter.
• This profile does not add database, authentication, API, email or durable-job ownership. Keep those responsibilities in their existing backend unless they are separately designed, migrated and tested.
• Qualify adapter behavior, secrets, cookies, headers, caching, redirects, cold starts and deployment independently. The static starter build does not establish any of these properties.

Interactive island integration

Use when: A content route has a defined widget whose stateful behavior justifies a component framework, and the team has selected that framework.

• Use semantic HTML and browser APIs first. Add only the chosen official Astro integration (for example, React, Svelte or Vue) and hydrate only the component that needs browser interaction.
• Keep content output usable as HTML. A client island does not supply backend authorization, persistence or offline synchronization.

Preserve the generated foundation

• Generated package scripts, Astro configuration, TypeScript settings, project lockfile and ignore rules; record any intentional change in README.
• Content collection schemas, route templates, public URL policy and CMS/API ownership as editable project sources.
• Original media sources and attribution records; use src assets for processing or public assets for deliberate unprocessed direct URLs.

Baseline and generation checks

• Run npm ci and npm run build with the committed lockfile; a successful untouched starter build does not qualify a site's content or integrations.
• Run npm run dev and inspect generated pages and routes. Check route HTML, collection entry URLs, missing pages, assets and browser behavior.
• Set the real site URL and verify canonical metadata and sitemap against production host configuration. Check redirect status and trailing-slash behavior at that host; static output may express redirects as HTML rather than an HTTP status.
• Verify image transformations and direct public asset URLs. If video is used, test its chosen streaming service and do not attribute video handling to Astro.
• If adding an adapter or CMS, test its actual preview, draft privacy, authorization, cookies, redirects, runtime APIs, cache behavior and production deployment separately. No application integration test or static regression suite was run for this record.

Generation receipt

• Component and selected starting point, or the documented absence of a full application generator
• Generator/toolchain versions, exact commands or IDE template/settings, working directory and generated destination
• Generated files retained, deliberate deviations with reasons, and required supplemental ignore rules
• Baseline checks and later checks actually run, results and remaining prerequisites or untested behavior

Generator sources

• Install Astro and create-astro CLI
• Astro CLI commands
• Content Collections
• On-demand rendering and adapters
• Routing and redirects
• Astro CMS integration
• Astro image handling

Build with the stack’s strengths

Architecture and developer workflow.

Recommendation: use Astro as a content presentation site, statically pre-rendering public pages and optionally hydrating discrete interactive islands. A content collection is not a route until a page template creates it. The selected CMS may own authoring, drafts and assets; existing APIs and application backends remain their own data, identity, migration and side-effect authorities. Astro's request-time mode requires a separately selected and qualified adapter/runtime.

Version scope: Astro installation and content/routing docs checked 23 October 2026. The disposable official basics scaffold used create-astro 5.3.1, Astro 7.4.2, Node 24.21.0 and npm 11.19.0. It built and served its starter route. This is not application or adapter compatibility evidence. · Reviewed 2026-10-23 · Evidence: documentation-reviewed · Source: migrations/astro-content.json

Architecture boundaries

• Inventory public content routes, source formats, existing URL and redirect contracts, canonical domain, sitemap and media. Define a collection schema only for structured content; define explicit routes and getStaticPaths for generated entry URLs.
• Recommendation: keep repository-authored content in reviewed Markdown/data, or name a headless CMS as the editorial owner. A CMS integration needs explicit draft/preview authorization, publish hook, media and failure behavior. Astro does not supply the CMS authoring interface.
• Static output is public build output. Do not place secrets, private drafts or authorization decisions in generated HTML or client JavaScript. Retain an existing API/backend as owner for identity, protected data, mutations, jobs and external effects until a separate transfer is designed.
• A client island is a browser UI boundary, not a backend. Add framework hydration only for the selected interaction and keep useful content in initial HTML.
• Use src image imports where processing is supported; public assets are copied without optimization. Astro has no built-in video streaming/processing. Keep original assets, licenses and delivery owner explicit.
• Static redirects may be emitted as HTML meta refresh and do not provide a portable HTTP redirect status. Check actual host rules, status codes, trailing-slash normalization, cache behavior and 404 response.
• Only enable request-time pages with a selected adapter and host that support needed cookies, headers, runtime APIs and caches. Rehearse deployment and secret handling for that exact target; this record does not qualify any adapter.

Tools and feedback

• Start from the content owner, route/URL inventory and project README. Run the official generator in an unused local source directory, inspect installed create-astro help, install using the chosen package manager and preserve its lockfile.
• The disposable baseline used `npm create astro@latest astro -- --template basics --no-install --no-git --no-ai --yes --skip-houston`; installed create-astro was 5.3.1. Node was 24.21.0 and npm was 11.19.0. `npm ci` then `npm run build` passed on the untouched starter; `npm run dev -- --host 127.0.0.1` served `/` as HTTP 200 `text/html`. No application tests were run.
• For content routes, add the collection schema and route template, run the build, and inspect emitted URLs and malformed-entry failures. Keep generated routes synchronized with the authored/cms-owned content inventory.
• Set the production site URL; inspect canonical links, metadata, sitemap, direct route loads, missing pages and redirect behavior in generated output and the selected host. A local build does not establish host status codes, headers, indexing or production delivery.
• For a CMS, adapter, private preview or API, qualify its actual version, auth boundary, secrets, caching, webhooks and production runtime separately. Record commands and results for that application; do not inherit the starter's smoke check as proof.

Translations to avoid

• Do not select Astro merely because it can import React, Vue or Svelte; use a rich browser-app framework when most routes require persistent client state and app-like interaction.
• Do not use static build output for account-specific content or pretend that a client island, hidden link or generated HTML protects data.
• Do not treat a Content Collection as CMS, route generation, search index or editorial preview; each requires explicit project-owned setup.
• Do not assume a redirect configured in Astro produces a production HTTP 301/302 on a static host. Verify the provider's routing rule and observed response.
• Do not assume public assets are optimized or that Astro streams video. Inspect the selected pipeline and delivery service.
• Do not infer that replacing a full-stack web application with Astro transfers its API, database, identity, migration or job responsibilities. Retain the current owners or define and qualify each transfer separately.

For an existing application

Keep the contracts while you change the stack.

These are documented options and proposed checks. Inspect the actual source application before adopting a transition.

Read the migration workflow →