- Docs
- Create a project
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
npx @samline/astro my-site --package-manager npm --runtime nodepnpm
pnpm dlx @samline/astro my-site --package-manager pnpm --runtime nodeBun
bunx @samline/astro my-site --package-manager bun --runtime bunEach 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:
- A package manager and script runtime from the tools available on your computer.
- A deployment target: static, Vercel, Netlify, Cloudflare Workers or a custom server.
- A default language: en-us, es-mx, es-es or a custom locale, followed by any additional languages.
- 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
cd my-site
npm run devpnpm
cd my-site
pnpm run devBun
cd my-site
bun run devUse the tab matching your project. If you chose --no-install, install its
dependencies first:
npm
npm installpnpm
pnpm installBun
bun installKeep 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
npm run astro dev status
npm run astro dev logs
npm run astro dev stoppnpm
pnpm run astro dev status
pnpm run astro dev logs
pnpm run astro dev stopBun
bun run astro dev status
bun run astro dev logs
bun run astro dev stopStart 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.