Starter Kits

Introduction

Starter kits are overlays on the application scaffolder. Pick one when you run almasix new (or pass --kit) and the installer layers production auth, settings, teams, and a shared Forge design language on top of the blank app.

The blank none kit is built into Almasix. Conduit (web), Signet (api), and Inertia SPA kits ship as separate packages and register through the almasix.kits entry-point group.

terminal

# Install kits (once per environment)
pip install 'almasix[kits]'
# or: pip install almasix-starter-kit-web almasix-starter-kit-api almasix-starter-kit-spa

almasix new myapp --kit web --stack tailwind
almasix new myapi --kit api
almasix new myspa --kit react   # or vue | svelte
almasix stacks                  # lists discovered kits + stacks + databases

After scaffolding, migrate and walk register → email verify → logout → login in the browser to confirm Day-1 auth.

Packages

Package	Kits	Depends on
almasix-starter-kit-web	web	almasix-conduit
almasix-starter-kit-api	api	Signet (in Almasix core)
almasix-starter-kit-spa	react, vue, svelte	almasix-inertia

Source: almasix-dev/almasix-starter-kits.

If a kit is missing, almasix new --kit web tells you which package to install.

Kits

Kit	Flag	Stack	Surface
None	--kit none (default)	any	Blank scaffold only (built-in)
Web	--kit web	Tailwind 4 / Bootstrap / none	Prism + Conduit
API	--kit api	forced none	Signet PAT JSON
SPA	--kit react|vue|svelte	forced Tailwind	Official @inertiajs/*

Forge design

Same language across Web and SPA:

• Landing — brand-first, full-bleed hero (Outfit + JetBrains Mono), chartreuse CTA, teal brand #0d9488. No cards in the first viewport.
• Authenticated chrome — quiet sidebar (Dashboard, Notifications, Settings, Teams), theme toggle, light and dark (class="dark" + localStorage).
• CSS stacks — Web kit honors Tailwind / Bootstrap / none; SPA kits always ship Vite + Tailwind 4.

Auth depth

Kits aim at Jetstream-class depth (not a thin login form):

• Register / login / logout
• Password forgot + reset
• Email verification + password confirmation
• Profile (name/email), password change, delete account, profile photo
• Two-factor authentication (stdlib TOTP + recovery codes)
• Teams (create, switch, invite, settings)
• Notifications shell (inbox UI ready for database notifications)
• Settings / appearance (theme)

API kit: personal access tokens only — POST /api/tokens, GET /api/user, revoke. No session auth UI.

Web kit (Conduit)

terminal

almasix new forgeweb --kit web --stack tailwind -n
cd forgeweb && python -m venv .venv && source .venv/bin/activate
pip install -e .
python smith migrate
npm install && npm run build
python smith serve

Conduit ships a theme-toggle island on the authenticated layout. Routes live in routes/web.py; components under app/conduit/.

SPA kit (Inertia)

terminal

almasix new forgespa --kit react -n
cd forgespa
pip install -e .
npm install && npm run build
python smith migrate && python smith serve

Web kits declare almasix[conduit]; SPA kits declare almasix[inertia]. Both extras resolve to the published first-party packages. Pages under resources/js/Pages/ use the official Inertia client. Root Prism view provides @inertia / @inertiaHead. Middleware alias inertia runs on the web stack; stateful_api() is enabled for cookie SPA flows.

API kit (Signet)

terminal

almasix new forgeapi --kit api -n
# issue a token
curl -X POST /api/tokens -d '{"email":"…","password":"…","name":"cli"}'
curl /api/user -H "Authorization: Bearer …"

Extending

Kit overlays live in the starter-kit packages (not in Almasix core). Contribute or fork almasix-starter-kits, or publish your own package that registers under the almasix.kits entry-point group and returns an almasix.installer.kits.Kit with stub_root set.

Publish a private blank scaffold with smith stub:publish --scaffold and point almasix new --stubs at your tree for team-wide app skeletons (kit overlays still come from installed starter-kit packages).