- Docs
- Installation examples
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.
Create a project
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
npx @samline/astro my-site --minimal --deploy static --locale en-uspnpm
pnpm dlx @samline/astro my-site --minimal --deploy static --locale en-usBun
bunx @samline/astro my-site --minimal --deploy static --locale en-usWhat 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.
Add Fields
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
npx @samline/astro add fieldspnpm
pnpm dlx @samline/astro add fieldsBun
bunx @samline/astro add fieldsWhat 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/formatterTo 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.
Add content
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
npx @samline/astro add content --source local --collection articlespnpm
pnpm dlx @samline/astro add content --source local --collection articlesBun
bunx @samline/astro add content --source local --collection articlesWhat 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.
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
npx @samline/astro add mail --dry-runpnpm
pnpm dlx @samline/astro add mail --dry-runBun
bunx @samline/astro add mail --dry-runMail 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
npx @samline/astro my-site --minimal --deploy vercel --locale es-mxpnpm
pnpm dlx @samline/astro my-site --minimal --deploy vercel --locale es-mxBun
bunx @samline/astro my-site --minimal --deploy vercel --locale es-mxThe 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
npx @samline/astro add themes --dry-run
npx @samline/astro statuspnpm
pnpm dlx @samline/astro add themes --dry-run
pnpm dlx @samline/astro statusBun
bunx @samline/astro add themes --dry-run
bunx @samline/astro statusReview 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.