Start a screen from a template

For AI agents: this page is Markdown at https://squiggle.sh/docs/run/templates.md. Every docs page is listed at https://squiggle.sh/llms.txt, and all of them are one file at https://squiggle.sh/llms-full.txt.

squiggle add screen writes a new screen that already has what the report card checks: a handle on every control, a flow that drives it, its declared controls and a renders budget it meets.

Before you start

An app set up with squiggle init. The screens use agentHint from @squiggle.sh/react-native.
Expo Router, to get a route written for you. Without it you get everything else, and the command tells you which component to mount.

Add a screen

Name the kind, then the route. The route name is lower-case letters, digits and dashes; leave it out and the screen is named after its kind.

Terminal

$ squiggle add screen list ordersadd screen list orders · A searchable list of rows, with a count, a selection and an empty state.  ✔ the list template: src/screens/orders.tsx  ✔ its route: src/app/orders.tsx  ✔ its flow: .squiggle/flows/orders.yaml  ✔ its interface: .squiggle/interfaces/orders.json  ✔ its budget: rendersPerTap 60: .squiggle/config.jsonc  squiggle flow orders                      drive it  squiggle card --files src/app/orders.tsx  its report card

Then run its flow, and its card:

Terminal

$ squiggle flow orders

Terminal

$ squiggle card --files src/app/orders.tsx

The six kinds

Kind	What you get
`list`	A searchable list of rows, with a count, a selection and an empty state. Rows are drawn by a plain ScrollView; switch to FlatList past about a hundred rows.
`form`	Name, email and message fields, checked when you press Send, with an error under each field and a sent state.
`auth`	Email and password sign-in with a busy state and an error. Pass your own check as signIn; the default accepts any well-formed email with a password of eight or more characters.
`detail`	A grid of tiles. Pressing one opens its detail, and the tile’s artwork grows into the detail’s header.
`settings`	Toggles with an On/Off readout, a Delete account button that asks twice, and Done.
`onboarding`	Pages with Next, Back and Skip, ending in Get started.

Each screen comes with sample data, so it runs before you connect it to anything. Replace the sample data and the default callbacks with your own.

Try each one below. The phone runs the same file squiggle add screen writes, its flow drives it, and the report card is built from that run.

Template

Starting the demo app…

What it writes

File	What it is
`src/screens/<name>.tsx`	The screen, as one file you own. It imports only react-native and @squiggle.sh/react-native. Without a src folder, it goes in screens/.
`src/app/<name>.tsx`	The route that shows it. Props that leave the screen, such as onDone, call router.back().
`.squiggle/flows/<name>.yaml`	A flow that opens the screen, uses it, asserts what changed on screen, and goes back, so the next run starts the screen fresh.
`.squiggle/interfaces/<name>.json`	Every control the screen draws when it opens, with its testID. The report card checks the running screen against them, so when you add a control with a testID, add it here too, or the card’s interface row fails.
`.squiggle/config.jsonc`	A budget for the screen: at most 60 renders for any one tap. Your other settings and comments stay as they are.

The route for a settings screen named prefs:

Terminal

$ import { router } from 'expo-router';$ import { SettingsScreen } from '../screens/prefs';$ export default function PrefsRoute() {$   return <SettingsScreen onDone={() => router.back()} />;$ }

Options

Flag	What it does
`--app-dir <dir>`	The app’s directory, when you run it from somewhere else, such as the root of a monorepo. The flow, the interface and the budget still go in the project’s .squiggle folder.
`--dry-run`	Lists every file it would write, and writes none.
`--force`	Overwrites files that already exist.
`--json`	Prints each file with its status: written, planned, exists or todo.

When something is already there

A file exists. It is left alone and listed as skipped. Add --force to overwrite it, or pick another name.
The screen already has a budget. It is never changed, with or without --force.
Your config can’t be edited safely. The command writes everything else and prints the budget line to add yourself.
An unknown kind or a name with spaces or capitals stops it with exit code 2 and the kinds it has.

How the templates are checked

Every template runs in Squiggle’s own CI, inside the demo app the web Studio drives, with its flow and its report card. A change that turns a template’s card red fails that CI run: every control has to be reachable by name, its flow has to pass, and no tap may cost more than 60 renders. See The report card for what each row means.