Guide

Create a project

Choose a folder, deployment target, languages and integrations, then run the generated Astro site.

Requirements

The installer requires Node 22.23.4 or newer. Choose npm, pnpm or Bun for dependency installation, and Node.js or Bun for the generated scripts. These are your project’s choices, independent of the tools used to maintain this repository. Node and npm alone are enough to start. When Bun manages dependencies for a Vercel project, use Bun 1.4.0 or newer so scoped dependency overrides are applied.

Run the following from the folder that will contain your new project:

npm

Terminal
npx @samline/astro my-site --package-manager npm --runtime node

pnpm

Terminal
pnpm dlx @samline/astro my-site --package-manager pnpm --runtime node

Bun

Terminal
bunx @samline/astro my-site --package-manager bun --runtime bun

Each tab chooses its package manager explicitly. The wizard also lets you choose the script runtime independently. For example, npm dependencies can be used with Bun scripts by passing --package-manager npm --runtime bun. Requested tools must already be installed; the installer reports a missing tool instead of silently changing an explicit choice.

Answer the setup questions

The wizard uses my-site as the project folder and asks for:

  1. A package manager and script runtime from the tools available on your computer.
  2. A deployment target: static, Vercel, Netlify, Cloudflare Workers or a custom server.
  3. A default language: en-us, es-mx, es-es or a custom locale, followed by any additional languages.
  4. The optional integrations you need now, with follow-up settings for the selected features.

Vercel is the default deployment choice. All profiles start with prebuilt public pages; an adapter supports server work when the project needs it. Choose static hosting when you only need generated files.

Selecting Forms also installs Formatter, and the wizard separately asks whether to include the Fields templates. Selecting Mail includes its Contact Action example. Content asks which source and loading mode to prepare. See all integration choices for the complete list.

Providing a folder or deployment flag still leaves the remaining questions interactive. Use --minimal for the core only, or explicit feature flags with --yes for an unattended command; the command reference describes those options.

The interactive selection defaults to the welcome starter demo: a header, navigation, homepage, /demo page and footer. Press Enter to keep it, include welcome alongside other selected integrations, or enter none for the core only. Explore the demo source to see where to edit each part. --minimal and --yes without explicit features omit the demo.

Run the site

When dependency installation completes, enter the project and start development:

npm

Terminal
cd my-site
npm run dev

pnpm

Terminal
cd my-site
pnpm run dev

Bun

Terminal
cd my-site
bun run dev

Use the tab matching your project. If you chose --no-install, install its dependencies first:

npm

Terminal
npm install

pnpm

Terminal
pnpm install

Bun

Terminal
bun install

Keep the selected manager and its lockfile together: package-lock.json, pnpm-lock.yaml or bun.lock. The generated README records your choices. Later add operations preserve the current project configuration; they do not switch managers just because another tool is installed.

The configured development server runs in the background:

npm

Terminal
npm run astro dev status
npm run astro dev logs
npm run astro dev stop

pnpm

Terminal
pnpm run astro dev status
pnpm run astro dev logs
pnpm run astro dev stop

Bun

Terminal
bun run astro dev status
bun run astro dev logs
bun run astro dev stop

Start replacing the homepage section in src/sections. Keep route assembly in src/pages and document structure in src/layouts/Main.astro. The conventions guide explains that composition.

Local package testing

From a working checkout, install the maintainer dependencies and create a local archive. This repository uses pnpm and Bun:

git clone https://github.com/samline/astro.git
cd astro
pnpm install
bun run kit:pack

Use the archive filename printed by kit:pack. For version 7.29.0, create a project next to the checkout with:

npm exec --yes --package ./artifacts/samline-astro-7.29.0.tgz -- samline-astro ../my-site --minimal --deploy static --no-install

While still in the checkout, the same archive can add a feature to that project:

npm exec --yes --package ./artifacts/samline-astro-7.29.0.tgz -- samline-astro add themes --cwd ../my-site --no-install

Then enter ../my-site, install dependencies using its generated instructions, and run its formatter and verification scripts. Local archive commands exercise the installer without publishing the package.

Start with a design reference

For a design-led project, use the bundled kickoff skill and copyable English prompt in AI agent workflows. The guide also covers standalone downloads and the purpose of the included skills.

Continue with Astro

For the framework itself, read Astro’s installation guide, project structure and development workflow.