Guide

Add integrations

Choose what to include, add features later, and find the setup steps for each integration.

Choose features during setup or later

The installation wizard asks which integrations to include. You can start with the core and add a feature when the project needs it.

From the root of a project created by @samline/astro, open the feature picker:

npm

Terminal
npx @samline/astro add

pnpm

Terminal
pnpm dlx @samline/astro add

Bun

Terminal
bunx @samline/astro add

Or name the features directly:

npm

Terminal
npx @samline/astro add themes gtm
npx @samline/astro add fields

pnpm

Terminal
pnpm dlx @samline/astro add themes gtm
pnpm dlx @samline/astro add fields

Bun

Terminal
bunx @samline/astro add themes gtm
bunx @samline/astro add fields

Adding Fields also includes its required Forms and Formatter packages. To install the packages without the templates, choose forms alone.

What each selection adds

SelectionAdded source and dependenciesNext step
themesShared theme initialization, switch and styles.Place the switch in a section and design both themes.
authBetter Auth with the selected external API, OAuth/OIDC or owned-database setup.Configure that identity source and protect the required operations.
captchaTurnstile or reCAPTCHA widget and server verifier.Supply provider keys/domains and verify tokens before the protected operation.
gtmGoogle Tag Manager and CookieConsent.Set the container ID and review the project’s tags and consent policy.
language-pickerLanguagePicker and language-label dictionaries.Place it in a section and check that its destinations exist.
forms@samline/forms, @samline/formatter and usage guidance.Define the form, validation and submission transport.
fieldsAstro form-control templates, plus Forms prerequisites.Compose the controls inside a form section.
actionsAn independent Basic Action example.Adapt its input, authorization and result to the operation.
contentThe selected local, API or CMS collection example.Follow the generated collection README to configure and read it.
mailSMTP mail service and Contact Action example.Configure the transport, sender and recipient, then connect a form.
pageloaderPageLoader and ldrs.Keep the default animation or select another one.
faiconInline SVG component and free Font Awesome icon packages.Import the individual icons the project uses.
welcomeThe optional starter presentation.Replace its content as the site takes shape.

Mail always includes Contact, even when the separate actions selection is omitted. Forms and Fields remain separate choices, so a Mail form can also use native controls or another project-owned presentation.

Supply feature-specific settings

The wizard asks the extra questions needed by your selections. Explicit commands can supply those settings too:

npm

Terminal
npx @samline/astro add auth --auth-mode external
npx @samline/astro add captcha --captcha-provider turnstile

pnpm

Terminal
pnpm dlx @samline/astro add auth --auth-mode external
pnpm dlx @samline/astro add captcha --captcha-provider turnstile

Bun

Terminal
bunx @samline/astro add auth --auth-mode external
bunx @samline/astro add captcha --captcha-provider turnstile

Content has its own source and loading choices. Server features also need a compatible deployment target.

Know where the feature appears

Themes, GTM and PageLoader receive their required initialization in src/layouts/Main.astro. Controls such as Theme Switch, LanguagePicker, Fields and Captcha are ready for your sections to compose. A later addition keeps your existing header and homepage.

Read each installed feature’s README before activation. Authentication starts disabled; remote collections wait for source configuration; mail and CAPTCHA need their real environment values. The installer prepares those connections, and your project supplies the provider configuration.

Review before applying

npm

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

pnpm

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

Bun

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

The first command shows planned files. The second reports the project’s local installation state. Repeat the addition without --dry-run when ready. These commands expect compatible installer metadata in package.json; see configuration and recovery for conflicts and older-project handling.

Use Astro integrations for the framework’s integration API and official adapters. Better Auth, Forms, CAPTCHA providers and other dependencies document their own APIs.