Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Um comando direto ignora o prompt de revisão. Verifique a origem antes de executá-lo.
Instruções da origem · Visualização somente leitura
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 — Gather the three required values by asking the user
You need three things to run the command:
summary — a short description of the app
path — the windmill path, e.g. f/folder/my_app or u/username/my_app
framework — one of react19 (recommended), react18, svelte5, vue
If the user's request did not supply every one of these explicitly, ask. Do not guess values, do not invent paths, do not pick a framework on the user's behalf, do not "just use react19 because it's the default".
Use whichever interactive question facility your runtime provides — a structured multi-choice tool if available, otherwise plain chat — and group all missing fields into a single round-trip so the user answers them at once:
For framework — multiple-choice with the four allowed values; mark as and put it first.
react19
(Recommended)
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).
Only proceed once you have concrete values for all three. If the user replies with something ambiguous, ask again rather than guessing.
That's the minimum. The datatable wizard and the "Open in Claude Desktop?" prompt are skipped silently because passing any of --summary/--path/--framework puts the command in non-interactive mode.
Optional flags
Layer these in only when the user asked for them:
Flag
When to add it
--datatable <name>
The user wants this app wired to a specific Windmill datatable. Without it, the app is created with no datatable.
--schema <name>
Together with --datatable. Creates the schema with CREATE SCHEMA IF NOT EXISTS if it doesn't already exist.
--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.
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/summary/framework instead of asking the user.
❌ Defaulting to react19 because the user didn't say — even sensible defaults must be confirmed.
❌ 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/Vue 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)
└── sql_to_apply/ # SQL migrations (dev only, not synced)
└── *.sql # SQL files to apply via dev server
Backend runnables on disk
Add a code file to the backend/ folder:
backend/<id>.<ext>
The runnable ID is the filename without extension. For example, get_user.ts creates a runnable with ID get_user.
Supported languages (extension-driven)
Language
Extension
Example
TypeScript
.ts
myFunc.ts
TypeScript (Bun)
.bun.ts
myFunc.bun.ts
TypeScript (Deno)
.deno.ts
myFunc.deno.ts
Python
.py
myFunc.py
Go
.go
myFunc.go
Bash
.sh
myFunc.sh
PowerShell
.ps1
myFunc.ps1
PostgreSQL
.pg.sql
myFunc.pg.sql
MySQL
.my.sql
myFunc.my.sql
BigQuery
.bq.sql
myFunc.bq.sql
Snowflake
.sf.sql
myFunc.sf.sql
MS SQL
.ms.sql
myFunc.ms.sql
GraphQL
.gql
myFunc.gql
PHP
.php
myFunc.php
Rust
.rs
myFunc.rs
C#
.cs
myFunc.cs
Java
.java
myFunc.java
After creating or editing a backend runnable — especially when its imports or arguments changed — its local lock and wmill-lock.yaml go stale. Offer to run wmill generate-metadata and run it once the user agrees (or automatically if the project's AGENTS.md opts into that) — YOU run it, don't just name it and wait. It writes local files only (not a deploy), and keeping the lock current avoids noise in git-sync/CI:
wmill generate-metadata
After it runs, check the regenerated .lock diff and tell the user which dependency versions changed (e.g. requests 2.31.0 → 2.32.0), so they can catch an unwanted bump before deploying.
Optional YAML configuration
Add a <id>.yaml file alongside the code to configure fields or static values:
To use an existing Windmill script instead of inline code:
backend/existing_script.yaml:
type:scriptpath:f/my_folder/existing_script
For flows:
type:flowpath:f/my_folder/my_flow
Data tables — raw_app.yaml config
The data block in raw_app.yaml controls which tables the app can query.
data:datatable:main# Default datatableschema:app_schema# Default schema (optional)tables:-main/users# Table in public schema-main/app_schema:items# Table in specific schema
Table reference formats:
<datatable> — All tables in the datatable
<datatable>/<table> — Specific table in public schema
<datatable>/<schema>:<table> — Table in specific schema
SQL Migrations (sql_to_apply/)
The sql_to_apply/ folder is for creating/modifying database tables during development.
Workflow
Create .sql files in sql_to_apply/
Run wmill app dev — the dev server watches this folder
When SQL files change, a modal appears in the browser to confirm execution
After creating tables, add them to data.tables in raw_app.yaml
Example migration
sql_to_apply/001_create_users.sql:
CREATE TABLE IF NOTEXISTS users (
id SERIAL PRIMARY KEY,
email TEXT NOT NULLUNIQUE,
name TEXT,
created_at TIMESTAMPDEFAULT NOW()
);
After applying, add to raw_app.yaml:
data:tables:-main/users
Migration best practices
Use idempotent SQL: CREATE TABLE IF NOT EXISTS, etc.
Number files: 001_, 002_ for ordering
Always whitelist tables after creation
This folder is NOT synced — it's for local development only
CLI Commands
Two commands you run yourself, not the user:
wmill app new — run it with flags, per the "Creating a Raw App" section above.
wmill generate-metadata — (re)generates local lock files and refreshes wmill-lock.yaml content hashes; writes local files only (not a deploy). After adding or editing a runnable, offer it and run it on agreement — or automatically if the project's AGENTS.md opts into that (see "After creating a runnable" above).
For the rest, tell the user which command fits their intent and let them run it — these deploy to the workspace, overwrite local files, or launch a long-running server, so the user should consent each time:
Command
Description
wmill app dev
Start dev server with live reload (see the preview skill for the full open-the-app-in-the-IDE-pane procedure).
wmill app generate-agents
Refresh AGENTS.md and DATATABLES.md
wmill sync push
Deploy app to Windmill
wmill sync pull
Pull latest from Windmill
Windmill Raw Apps
Raw apps let you build custom frontends with React, Svelte, or Vue that connect to Windmill backend runnables and datatables.
App shape
A raw app has three logical parts:
Frontend — bundled with esbuild from index.tsx as the entrypoint. Files include the entrypoint, components (App.tsx), styles, etc.
Backend runnables — server-side scripts the frontend calls, each addressed by a unique key.
Data — optional whitelisted datatables (managed PostgreSQL) that the backend runnables can query. The frontend never queries the database directly; backend runnables are the only bridge.
Frontend
Entrypoint
The entrypoint is index.tsx for React and index.ts for Svelte and Vue. It is both the bundling entrypoint (the bundler is esbuild) and the mount entrypoint: the preview executes the bundle against an empty <div id="root"> and auto-renders nothing, so the entrypoint must mount a top-level App itself. Keep the UI in App.tsx / App.svelte / App.vue and keep the entrypoint as the mount shim.
Never replace the entrypoint with a bare component (export default function App() { ... } and no mount call). A component that is defined but never mounted renders a blank screen with no error thrown — it never executes, so nothing reaches the console or the error overlay. If an app renders blank, check that the entrypoint still mounts App into #root.
Always begin every React file (.tsx/.jsx) that uses JSX with import React from 'react'. esbuild uses the classic JSX transform, so React must be in scope wherever JSX appears — a missing import compiles fine but throws React is not defined at runtime, leaving a blank screen.
Generated bindings (wmill.d.ts / wmill.ts)
The frontend imports a generated module that mirrors the backend runnables. Never write to it directly — it gets regenerated whenever backend runnables change. Modifying it by hand will be overwritten.
Calling backend runnables
Import the generated bindings and call the runnable like a function:
import { backend } from'./wmill';
// Call a backend runnableconst user = await backend.get_user({ user_id: '123' });
The frontend cannot reach datatables, workspace items, or external services on its own — it goes through backend.<key>(args) for everything server-side.
Keeping data out of recorded demos
An app can be demoed by recording a session: every interaction becomes a step carrying a snapshot of the page, replayed publicly or on the Hub. Password inputs are masked automatically. Mark anything else that must not appear with data-wm-no-record — the whole marked subtree is dropped from every snapshot, along with its values and the step's own metadata:
Apply it to customer data, internal notes and anything else a viewer of the demo should not see. It costs nothing when the app is never recorded.
Backend runnables
Each runnable has a unique key (used to call it from the frontend) and one of four types:
Type
What it is
inline
Custom code stored on the app itself. Most common for app-specific logic.
script
Reference to an existing workspace script by path.
flow
Reference to an existing workspace flow by path.
hubscript
Reference to a hub script by path.
Inline runnables
Inline runnables carry their own source code. For file-based raw apps, the runnable language is determined by the backend file extension. The script must expose a main function as its entrypoint.
TypeScript example (backend/get_user.ts):
import * as wmill from'windmill-client';
exportasyncfunctionmain(user_id: string) {
const sql = wmill.datatable();
const user = await sql`SELECT * FROM users WHERE id = ${user_id}`.fetchOne();
return user;
}
Python example (backend/get_user.py):
import wmill
defmain(user_id: str):
db = wmill.datatable()
user = db.query('SELECT * FROM users WHERE id = $1', user_id).fetch_one()
return user
Path runnables (script / flow / hubscript)
When type is script, flow, or hubscript, the runnable just stores a path to an existing workspace or hub item — no inline code. The referenced item's input/output schema becomes the runnable's surface.
Static inputs
staticInputs is an optional Record<string, any> for arguments not overridable from the frontend. Useful with path runnables to pre-fill some args while leaving the rest to the frontend caller.
Data Tables
Data tables are PostgreSQL databases managed by Windmill. Backend runnables query them via the wmill client; the frontend never queries them directly.
Critical rules
Whitelisted tables only: a runnable can only query tables listed in the app's data.tables config. Tables not in this list are not accessible.
Add tables before using: queries against unlisted tables fail at runtime. When you introduce a new table, register it in data.tables first.
Use the configured datatable/schema: the app's data config sets the default datatable and schema; reference them consistently across runnables.
Querying in TypeScript (Bun/Deno)
import * as wmill from'windmill-client';
exportasyncfunctionmain(user_id: string) {
const sql = wmill.datatable(); // Or: wmill.datatable('other_datatable')// Parameterized queries (safe from SQL injection)const user = await sql`SELECT * FROM users WHERE id = ${user_id}`.fetchOne();
const users = await sql`SELECT * FROM users WHERE active = ${true}`.fetch();
// Insert/Updateawait sql`INSERT INTO users (name, email) VALUES (${name}, ${email})`;
await sql`UPDATE users SET name = ${newName} WHERE id = ${user_id}`;
return user;
}
Querying in Python
import wmill
defmain(user_id: str):
db = wmill.datatable() # Or: wmill.datatable('other_datatable')# Use $1, $2, etc. for parameters
user = db.query('SELECT * FROM users WHERE id = $1', user_id).fetch_one()
users = db.query('SELECT * FROM users WHERE active = $1', True).fetch()
# Insert/Update
db.query('INSERT INTO users (name, email) VALUES ($1, $2)', name, email)
db.query('UPDATE users SET name = $1 WHERE id = $2', new_name, user_id)
return user
Best Practices
Check existing tables before creating new ones — reuse beats schema growth.
Use parameterized queries — never concatenate user input into SQL.
Keep runnables focused — one function per runnable; small surface area.
Use descriptive keys — get_user, not a.
Always whitelist tables — adding a runnable that queries a new table requires the table to be in data.tables first.
Mark sensitive UI with data-wm-no-record — it is what keeps that data out of a recorded demo; passwords are handled for you.
