Project structure

A full-code app lives in a directory with the .raw_app suffix (e.g. my_app.raw_app/). If your filesystem or tooling hides dotfiles, you can use the __raw_app suffix instead (e.g. my_app__raw_app/) by setting nonDottedPaths: true in wmill.yaml.

All examples below use the default .raw_app suffix.

Directory layout

f/folder/my_app.raw_app/
├── raw_app.yaml            # App configuration (required)
├── package.json            # Frontend dependencies
├── index.tsx               # Frontend entry point
├── App.tsx                 # Main component (React example)
├── index.css               # Styles
├── wmill.d.ts              # Auto-generated TypeScript definitions
├── AGENTS.md               # Auto-generated AI agent instructions
├── DATATABLES.md           # Auto-generated data table documentation
├── backend/                # Backend runnables
│   ├── get_users.ts        # Runnable code
│   ├── get_users.yaml      # Runnable config (optional)
│   ├── get_users.lock      # Generated lock file
│   └── query.pg.sql        # SQL runnable (language inferred from extension)
└── sql_to_apply/           # SQL migrations (dev only, not deployed)
    └── 001_create_table.sql

raw_app.yaml

The raw_app.yaml file is the main configuration file for a full-code app. It defines metadata, execution policy and data table access.

summary: "My dashboard app"

# Optional: custom URL path (admin only)
custom_path: "my-dashboard"

# Optional: make the app publicly accessible
public: false

# Optional: data table access configuration
data:
  datatable: "main"           # Datatable name
  tables:                     # Tables to whitelist
    - "users"
    - "orders"
  schema: "app1"              # Schema within the datatable

The execution policy (including execution_mode, triggerables and triggerables_v2) is auto-generated at deployment time and does not need to be specified in raw_app.yaml.

Fields

Field	Type	Required	Description
summary	string	Yes	Short description of the app (max 1000 chars)
custom_path	string	No	Custom URL path (admin only)
public	boolean	No	Whether the app is publicly accessible
data.datatable	string	No	Datatable name
data.tables	string[]	No	List of table names to whitelist
data.schema	string	No	Schema name within the datatable

Auto-generated files

These files are generated by the CLI and should not be edited manually:

• wmill.d.ts: TypeScript definitions for the wmill.ts module, with typed signatures for each backend runnable. Regenerated when runnables change during wmill app dev.
• AGENTS.md: Instructions for AI coding agents (Claude, Copilot, etc.) describing the project structure and available APIs. Generated by wmill app generate-agents.
• DATATABLES.md: Documentation of available data tables and their schemas. Generated by wmill app generate-agents.

Files excluded from deployment

The following are not included when pushing to Windmill:

• node_modules/
• dist/
• .claude/, .git/
• wmill.d.ts, package-lock.json
• raw_app.yaml (metadata is handled separately)
• sql_to_apply/ (dev-only migrations)
• DATATABLES.md, AGENTS.md
• backend/ (runnables are extracted and uploaded separately)

App path format

App paths follow the standard Windmill path convention:

<u|g|f>/<username|group|folder>/<app_name>

For example: f/dashboard/my_app, u/admin/my_tool, g/engineering/ops_panel.

Backend runnables

Define backend scripts called from your frontend code.

CLI workflow

Scaffold projects with wmill app new.