Smeltery
Get started

Getting started

v0.1

Create an app

text
smeltery new my-app

smeltery new asks a few questions. Every question is also a flag; with any flag given, or when the terminal is not interactive, no question is asked and the defaults apply. At the end it prints the equivalent one-line command.

Question Flag Choices (default first)
What are you building? --kind web (a web app), headless (Watchfire agents, jobs and the scheduler, no web pages)
Database --db sqlite, postgres, mysql
Starter kit (not asked for headless) --frontend mold (Mold + Sparks), react (React, Inertia, TypeScript), vue (Vue, Inertia, TypeScript)
Install Tailwind? / Tailwind CSS? (not asked for headless) --tailwind / --no-tailwind yes
Alpine.js? (asked for the Mold frontend) --alpine / --no-alpine no
Which building blocks should we smelt into your stack? (not asked for headless) --smelt watchfire,temper; any of watchfire, temper, hallmark, anvil, prospect (comma-separated), or none
Bellows (AI-agent files) --bellows none, or any of mcp, skills, guidelines (comma-separated), or all
Install the npm packages now? (asked for react and vue when Node.js 20.19+ or 22.12+ is found) --npm / --no-npm yes
Run the migrations now? (smeltery migrate in the new app) --migrate / --no-migrate yes
Seed the basic data? (smeltery db:seed, after the migrations) --seed / --no-seed yes
Initialise git? --git / --no-git yes

The building blocks of a web app:

  • watchfire: Watchfire agents, jobs and the scheduler in the app (app/agents/, the Watchfire tables, the /_watchfire dashboard). A headless app always has Watchfire.
  • temper: authentication through Temper, described below.
  • hallmark: API tokens for mobile apps, desktop apps and other clients (API tokens). It needs user accounts, so it brings temper with it: the checklist and --smelt hallmark add Temper and say so (Hallmark needs Temper: added).
  • anvil: WebSockets and broadcasting (Broadcasting).
  • prospect: full-text search for models (Search).

Under the checklist (and with --smelt), a chosen block that works well with one that is not chosen gets a hint, and nothing is added for it: Anvil works with Temper (private channels for signed-in users), with Hallmark (private channels for mobile apps and other clients) and with Watchfire (broadcasting from agents and jobs).

.env gets a fresh APP_KEY and SESSION_DRIVER=database (the sessions table is one of every new app's migrations); .env.example lists the same keys without secrets. Every new app's users table has the nullable credentials_epoch column and its User model returns it from Authenticatable::credentials_epoch, so auth::end_credentials signs a user out everywhere.

With authentication (the temper building block, on by default), a web app has registration, log-in, log-out, password reset by mail and a dashboard behind the temper and verified middleware, and its seeder creates a demo user under APP_ENV local or testing. Email verification is scaffolded and off: the email_verified_at column, MustVerifyEmail on User, the notice page, the signed link's route and "send it again"; uncommenting .verify_email::<app::models::User>() in bootstrap/app.rs turns it on.

The authentication is Temper in every starter kit: bootstrap/app.rs calls .temper(app::providers::temper::temper()). app/providers/temper.rs turns on registration, password reset, e-mail verification, profile and password updates and two-factor authentication and names the page of each GET route (Mold views in resources/views/auth/, React or Vue pages in resources/js/pages/auth/ through alloy::render, with the password confirmation and two-factor challenge pages); in a React or Vue app it also clears the browser's history state on logout. app/actions/temper/ holds the forms and what they do, with the password rules in one place (password_rules.rs). The app adds the settings pages /settings/profile, /settings/password and /settings/two-factor (app/controllers/settings.rs; the two-factor page sits behind password.confirm and shows the QR code as an <img>, the key, the confirmation form and the recovery codes once; all three answer Cache-Control: no-store; the React and Vue page fetches the QR code and the key from Temper's JSON routes, so they never become props, and drops the recovery codes from its props as soon as it shows them, so the back button does not show them again), the add_two_factor_columns_to_users_table migration, the four two_factor_* fields and TwoFactorAuthenticatable on User, AUTH_PASSWORD_TIMEOUT=10800 in .env, and tests for the profile, the password change, two-factor log-in, recovery codes, the password confirmation and signing a user out everywhere. A React or Vue app's shared auth.user has two_factor_enabled.

The forms that create an account or ask for and use a password reset (POST /register, /forgot-password, /reset-password/{token}) carry .middleware("throttle:6,1"): at most 6 requests a minute per client on each of those routes, counted in the cache; past that the form shows "Too many attempts. Please try again in N seconds." (429 for JSON clients); the login form (POST /login) carries .middleware("throttle:30,1"). The auth forms read the e-mail address trimmed and in lower case (smeltery::auth::deserialize_email), so Ada@Example.com and ada@example.com are one account. Registering an address that has an account answers "The email has already been taken.", which tells the visitor that the address is registered; the throttle limits how fast addresses can be tried. Without temper the app has none of these pages, no password_reset_tokens migration and no demo user; the users table and the User model stay, and .temper(…) turns authentication on in such an app (its CLAUDE.md lists the steps).

With hallmark, bootstrap/app.rs calls .hallmark(Hallmark::new()), and the app has the create_personal_access_tokens_table migration, routes/api.rs with POST /api/tokens (throttle:10,1: a token for email, password, device_name and, for an account with two-factor authentication on, code, through issue_for_credentials), DELETE /api/tokens/current and GET /api/user (both auth:hallmark), their controllers in app/controllers/api/, the HALLMARK_* settings as comments in .env, and tests/api_tokens.rs, whose tests create their own users with UserFactory. With Watchfire too, app/agents/mod.rs schedules hallmark-prune daily (tokens expired a day or more). smeltery hallmark:install adds the same files to an app made without the block.

With anvil, bootstrap/app.rs calls .anvil(routes::channels::channels), and the app has routes/channels.rs (the public channel announcements; with temper also users.{user}, which only that user may join), app/events/announcement_posted.rs (an event on announcements), the pubsub_messages migration (also without Watchfire), the ANVIL_* settings as comments in .env (the key and the secret are derived from APP_KEY until set; the CORS settings too) and tests/broadcasting.rs. With temper it also has app/events/user_notified.rs (an event on private-users.<id>). A Mold app listens without JavaScript: the Spark announcements (app/sparks/announcements.rs, on the home page) shows the newest announcements, and with temper the Spark notifications on the dashboard listens to the user's private channel and its "Notify me" button sends one. A React or Vue app gets Echo: package.json pins laravel-echo 2.5.0, @laravel/echo-react or @laravel/echo-vue 2.5.0 and pusher-js 8.6.0; resources/js/echo.ts connects to the page's own host and port with the key the pages get as the shared prop app.anvil_key, authorizes private and presence channels at /broadcasting/auth with the session cookie and the XSRF-TOKEN cookie as X-XSRF-TOKEN, and adds X-Socket-ID to Inertia's requests; the entry calls it before the first page. The welcome page shows the announcements card; with temper the dashboard's "Live" card listens to the user's private channel, sends itself an event through POST /notify-me (temper, throttle:10,1) and shows how many people are online through the presence channel presence-dashboard, with the viewer's own name ("3 people online · you: Ada"). The channel shares each member's id only, so no other user's name reaches the browser; routes/channels.rs shows the one line that shares names. The create_presence_tables migration holds the members under PUBSUB_DRIVER=database.

With prospect, bootstrap/app.rs calls .prospect(app::providers::search::register), app/providers/search.rs registers the searchable models above // smeltery:searchables, and .env has PROSPECT_DRIVER=database; no migration is written until a model is made searchable. smeltery make:model Post title:string body:text --searchable --all then writes impl Searchable (every string / text field searched, the first with Weight::A, foreign fields as filters), the SearchIndex in the create-table migration (without -m, a separate add_search_index_to_posts_table migration), the registration, and a list page that searches: GET /posts?q=…&page=… behind throttle:60,1, ranked and paginated, the label highlighted (Mold: a search form and Previous / Next buttons, no JavaScript; React and Vue: a search box that reloads the page 300 ms after the last key). --searchable is refused in an app without the block and for a model without a string or text field. smeltery prospect:install adds the provider to a web app made without the block.

With Alpine.js, the app gets Alpine.js 3.17.4 (the official dist/cdn.min.js of the npm package, with its MIT licence header) as public/assets/js/alpine.min.js, embedded in the CLI, so nothing is downloaded. The layout loads it with defer after @sparksScripts, the welcome page shows an Alpine toggle, and the counter Spark reads its count through $spark.

With --frontend react or --frontend vue the pages are React or Vue components in TypeScript under resources/js/pages/, rendered in the browser by Inertia's client packages; the controllers return them through smeltery::alloy (alloy::render("welcome")), and resources/views/app.mold.html is the HTML of a first visit. The app has the same routes, authentication and settings pages and tests as a Mold app, a welcome page whose "Ask the forge" button loads an optional prop with a partial reload, and a dashboard with a deferred prop. package.json pins exact npm versions (Vite 8.3.2, Inertia 3.8.0, React 19.3.0 or Vue 3.5.43, TypeScript 6.0.3); npm install runs in the new app unless --no-npm is given or no usable Node.js is found, for at most 5 minutes (SMELTERY_NPM_TIMEOUT sets the seconds), and a failed or stopped install leaves the app complete, with npm install in the next steps. The first install writes package-lock.json, which pins every package the kit pulls in, its dependencies' dependencies included, with integrity hashes; with it in the repository, smeltery build (and npm ci on a CI runner or a server) installs exactly those versions. With Tailwind the kit uses the tailwindcss npm packages through @tailwindcss/vite (no binary download); without it, resources/css/app.css is a prebuilt stylesheet of the kit's pages. Node.js builds the assets only: smeltery serve starts the Vite dev server (node node_modules/vite/bin/vite.js, on 127.0.0.1:5173) next to the app, and smeltery build runs npm run build into public/build/ before the release build. .env gets VITE_APP_NAME; every VITE_ value is compiled into the JavaScript and is public. Alloy: React and Vue describes the pages, the generators and the tests of these apps.

↑↓ moveEnter openEsc close