Guide

Installation examples

Choose a starting setup, understand its command, and follow the files it creates.

Choose a starting setup

Each example below describes one installation task. Read where to run the command, the required tools and the files it creates, then copy the command for the setup you want. The panels describe real CLI operations; the browser displays the instructions while the installer runs in your terminal.

Choose the tab matching your tools. See Create a project for requirements, wizard choices and the first development run.

Choose a setup task

Create a project

Create a projectSetup example

Start with the core configuration and a simple homepage. Optional integrations are omitted until you choose to add them.

Where to run it
The parent folder where you keep your projects.
Before you start
Node 22.23.4 or newer, with your chosen package manager available. Use a new or empty folder named my-site.

npm

Terminal
npx @samline/astro my-site --minimal --deploy static --locale en-us

pnpm

Terminal
pnpm dlx @samline/astro my-site --minimal --deploy static --locale en-us

Bun

Terminal
bunx @samline/astro my-site --minimal --deploy static --locale en-us

What you get

The installer creates my-site with Astro, Tailwind, local fonts, SEO components, a homepage and English dictionaries. Dependency installation uses the selected manager; add --package-manager npm, pnpm or bun to choose explicitly.

Files added or configured
my-site/
  astro.config.mjs
  src/layouts/Main.astro
  src/sections/Home/
  src/i18n/dictionaries/en-us/
  public/img/  public/docs/  public/video/

No server adapter is installed. This project builds files for static hosting; server features need a compatible adapter and runtime.

What to do next

Run cd my-site, then the development command in the generated README (npm run dev, pnpm run dev or bun run dev). Edit src/sections/Home/index.astro to build your homepage.

Read the setup guide

Add Fields

Add FieldsSetup example

Add Astro components for native form controls, together with @samline/forms and @samline/formatter. You still create the form section and choose its submission handler.

Where to run it
Your generated project root: the folder containing package.json and astro.config.mjs.
Before you start
A project created by this modular installer. Create the project in the first recipe before running add.

npm

Terminal
npx @samline/astro add fields

pnpm

Terminal
pnpm dlx @samline/astro add fields

Bun

Terminal
bunx @samline/astro add fields

What you get

Form, Input, Select and the other Fields components, their styles and API docs, plus the package usage guide in src/forms. Both package dependencies are included.

Files added or configured
src/components/Fields/
src/forms/README.md
src/i18n/dictionaries/<your-locale>/forms/

Dependencies: @samline/forms, @samline/formatter

To add the packages and usage guide without the Fields components, run npx @samline/astro add forms and decline Fields when prompted.

What to do next

Read src/components/Fields/README.md, then compose Form, Input and Button inside your own section. Add labels to your dictionaries and connect an Action or endpoint before expecting submission to work.

Read the setup guide

Add content

Add contentSetup example

Register a collection named articles with a schema and local sample data. This prepares content to query; you still build the article list and pages.

Where to run it
Your generated project root: the folder containing package.json and astro.config.mjs.
Before you start
A project created by this modular installer. The collection name articles must not conflict with your own source.

npm

Terminal
npx @samline/astro add content --source local --collection articles

pnpm

Terminal
pnpm dlx @samline/astro add content --source local --collection articles

Bun

Terminal
bunx @samline/astro add content --source local --collection articles

What you get

src/content.config.ts registers articles. The example stores locale, a dictionary copy key, a date and a draft flag in JSON, with display text in the content dictionary. It works offline.

Files added or configured
src/content.config.ts
src/content/articles/
  README.md
  index.ts
  data/

Choose API, Strapi, Shopify or another service when content lives elsewhere. Those examples need your source schema, credentials and explicit activation.

What to do next

Open src/content/articles/README.md for the getCollection example. Query articles from your content section, resolve the sample copy key through the dictionary, then replace the example with your project’s content model.

Read the setup guide

Use these commands to create a project or add integrations. Choose your package manager, then follow the setup guide for the generated files.

Add mail when the project needs it

Run this from an existing generated project to inspect the proposed changes:

npm

Terminal
npx @samline/astro add mail --dry-run

pnpm

Terminal
pnpm dlx @samline/astro add mail --dry-run

Bun

Terminal
bunx @samline/astro add mail --dry-run

Mail includes the SMTP service and Contact Action. Forms and Fields are optional. If the plan is correct, repeat the command without --dry-run, then follow src/server/mail/README.md and src/actions/contact/README.md to configure SMTP and connect the form. The mail reference describes the service API.

Start in Mexican Spanish

Run this from the folder that will contain the new project:

npm

Terminal
npx @samline/astro my-site --minimal --deploy vercel --locale es-mx

pnpm

Terminal
pnpm dlx @samline/astro my-site --minimal --deploy vercel --locale es-mx

Bun

Terminal
bunx @samline/astro my-site --minimal --deploy vercel --locale es-mx

The result is a core-only Vercel project whose default dictionaries are the es-mx preset. Later language additions scaffold the keys from that project’s current dictionaries for you to translate. See Set up languages for the activation steps.

Add themes to an existing project

From the generated project root:

npm

Terminal
npx @samline/astro add themes --dry-run
npx @samline/astro status

pnpm

Terminal
pnpm dlx @samline/astro add themes --dry-run
pnpm dlx @samline/astro status

Bun

Terminal
bunx @samline/astro add themes --dry-run
bunx @samline/astro status

Review the plan, then apply the first command without --dry-run. The installer adds theme initialization to Main and makes the switch available for your sections. Follow the Theme component example to place the control.

The command reference lists all supported options.