/raw-app

name: raw-app
description: MUST use when creating raw apps.

Windmill Raw Apps — CLI workflow

This guide covers raw apps from the terminal: scaffolding via `wmill app new`, the on-disk layout, and the file-based conventions the CLI uses to represent backend runnables and data table configuration. The platform shape (how a raw app behaves at runtime — frontend bundling, runnable types, datatable SDK calls) is covered in the companion authoring guide.

Creating a Raw App

**You — the AI agent — create the app yourself by running `wmill app new` with the right flags. Do NOT tell the user to "run `wmill app new` and follow the prompts" or wait for them to do it.** The bare `wmill app new` is an interactive wizard that hangs waiting for stdin in any non-TTY context (which includes you). Always pass flags.

Step 1 — Settle the setup

You need three values to run the command:

1. **summary** — a short description of the app 2. **path** — the windmill path, e.g. `f/folder/my_app` or `u/username/my_app` 3. **framework** — one of `react19` (recommended), `react18`, `svelte5`

**summary and path**: if the user's request did not supply them, ask. Do not guess values and do not invent paths.

**framework**: never ask. Use the one the user named, otherwise the one the project's existing apps use, otherwise `react19` (see "Starting a new app" in the authoring guide).

**data setup**: when the app has to store data and the user did not say where, ask which data table, which schema and which tables, as "Data setup" in the authoring guide lays out. `wmill datatable list` gives the data tables to offer.

Use whichever interactive question facility your runtime provides — a structured multi-choice tool if available, otherwise plain chat — and group everything missing into a single round-trip so the user answers at once:

• For `summary` and `path` — provide one or two example values as multiple-choice options (the user can pick "Other" to type a free-form answer).
• For the data setup — the choices the authoring guide lists, the default first.

Only proceed once every value is concrete. If the user replies with something ambiguous, ask again rather than guessing.

Step 2 — Run the command yourself

Once the setup is settled, run it:

wmill app new \
  --summary "Customer dashboard" \
  --path f/sales/dashboard \
  --framework react19 \
  --datatable main \
  --schema app1

`--summary`, `--path` and `--framework` are the minimum. The datatable wizard and the "Open in Claude Desktop?" prompt are skipped silently because passing any of them puts the command in non-interactive mode, so the data setup only reaches the app through the flags below.

Optional flags

| Flag | When to add it | |---|---| | `--datatable <name>` | The app stores data: the data table settled in step 1. Without it, the app is created with no datatable. | | `--schema <name>` | Together with `--datatable`, when the app's tables go in a schema, new or existing. If the schema doesn't exist yet, writes a `sql_to_apply/` migration with `CREATE SCHEMA IF NOT EXISTS`, applied like any other migration (see "SQL Migrations" below). Leave it out for `public`. | | `--overwrite` | The target directory already exists and the user said it's OK to replace. Without it, non-interactive mode aborts with an error so you don't clobber existing work. | | `--no-open-in-desktop` | Already implied in non-interactive mode; only needed if you're somehow running interactively. |

Existing tables the app reuses have no flag: list them under `data.tables` in `raw_app.yaml` (see "Data tables" below).

Step 3 — Offer the visual preview

After `wmill app new` and any initial edits to `App.tsx` / `index.tsx`, **offer** to open the visual preview as a one-sentence next step (e.g. "Want me to open the visual preview?"). Don't auto-open — opening the dev page has side effects (browser window, possibly a `launch.json` entry when an embedded preview tool is in play) the user should consent to.

For apps the preview command runs from the app folder (`cd <app_path>__raw_app && wmill app dev …`); the `preview` skill picks the proxy vs direct branch based on whether the runtime exposes a tool that can embed a localhost URL. If the user already asked to see/preview/visualize the app in their original request, skip the offer and just invoke the skill.

Anti-patterns to avoid

• ❌ Running `wmill app new` with no flags (the prompt will hang).
• ❌ Telling the user to "run `wmill app new` and follow the prompts" — that's a step backwards from what you can do directly.
• ❌ Inventing a path or summary instead of asking the user.
• ❌ Asking which framework to use — `react19` is the default when nothing says otherwise.
• ❌ Creating a schema or tables for a new app before the user has said where its data goes.
• ❌ Passing `--overwrite` automatically when the directory exists — confirm with the user first.

Interactive (only when a human is at the terminal)

wmill app new

This is the wizard. It only works when run by a human in a real terminal. Don't call it this way from an agent.

On-disk app layout

my_app__raw_app/
├── AGENTS.md              # AI agent instructions (auto-generated)
├── DATATABLES.md          # Database schemas (run 'wmill app generate-agents' to refresh)
├── raw_app.yaml           # App configuration (summary, path, data settings)
├── index.tsx              # Frontend entry point
├── App.tsx                # Main React/Svelte component
├── index.css              # Styles
├── package.json           # Frontend dependencies
├── wmill.ts               # Auto-generated backend type definitions (DO NOT EDIT)
├── backend/               # Backend runnables (server-side scripts)
│   ├── <id>.<ext>         # Code file (e.g., get_user.ts)
│   ├── <id>.yaml          # Optional: config for fields, or to reference existing scripts
│   └── <id>.lock          # Lock file (run 'wmill generate-metadata' to create/update)