Building Frappe Studio apps
A Studio app contains Studio Page documents. Each page has a JSON block tree,
optional Studio Page Resource rows, and page logic.
- Read RULES.md before writing bindings, events, or styles.
- Read DESIGN.md before building or restyling a page.
- Read ROUTING.md when working on navigation, redirects, guards,
or
boot data.
- Check
studio/frontend/src/data/components.ts and
studio/frontend/src/data/componentFamilies.ts for available components.
Custom and standard apps
Read is_standard on the Studio App before editing it. This field controls
source storage, compilation, editing, and preview. Read the matching Custom apps
or Standard apps section. The later sections apply to both types unless they
name one type.
| Detail |
Custom app (is_standard 0) |
Standard app (is_standard 1) |
| Source files |
Studio App File records, plus each page's own script field |
Files under <frappe_app>/studio/<studio_app>/ |
| Compiled in the editor and preview |
The browser |
Vite's dev server |
| Compiled on publish |
Vite, from a copy of the source files |
Vite |
| Languages |
.js, .json, .css |
.js, .json, .css + .ts, .vue |
| Edit |
In Studio, on any site |
The files or Studio, in developer mode only |
Custom apps
- Insert
Studio App and Studio Page documents, or create them in Studio.
Then write the source files.
- No build is needed while editing. After you save a file, it runs on the next
render in the editor and preview. Publishing builds the app with Vite.
- The browser compiles and runs the source as written. A custom app rejects
.ts and .vue files, tsconfig.json, Tailwind config files, and dotfiles.
TypeScript syntax inside a .js file is a runtime syntax error.
- Use Studio Components for reusable layouts. Export the app if you need your
own
.vue files.
- The app can import
vue, vue-router, pinia, frappe-ui,
frappe-ui/list, frappe-ui/charts, and its own files. There is no npm.
Export the app if it needs another package. Export makes the app standard.
- Preview and publishing insert CSS without changes. Use public asset URLs,
such as
/files/logo.png. CSS references cannot read the server filesystem.
Module rules
- Use ESM
import and export. Relative paths and @app/ are supported.
Dynamic import() requires a literal path.
- A JSON file exports its object as the default export. Its top-level keys are
also named exports. Import CSS for its side effects. CSS has no default
export.
- Import queries such as
?raw and ?url are not supported. Import fragments
and attributes are also not supported. Use identifiers for import and export
names. Do not use string names.
require, module, and exports are not available. These names are also
reserved as top-level bindings.
- Top-level
await and import.meta are not supported. Put asynchronous work
in setup() or an event handler. For cyclic imports, read imported values
inside setup() instead of during module execution.
Standard apps
Developer mode is required to save a standard app, page, or component
(validate_standard_app_change). Document saves export only in developer
mode (can_export). Both checks are in frappe/studio/export.py.
Create the app as standard: insert a Studio App with is_standard set to 1
and frappe_app set to an installed Frappe app. frappe_app is mandatory
when is_standard is set. The save writes the export folder. To convert an
existing custom app, see Switching app types.
Files are stored under the linked Frappe app. Before creating files directly,
inspect an existing export such as helpdesk/studio/helpdesk/:
<frappe_app>/studio/<studio_app>/<studio_app>.json
<frappe_app>/studio/<studio_app>/studio_page/<scrubbed_title>/<scrubbed_title>.json
<frappe_app>/studio/<studio_app>/studio_page/<scrubbed_title>/<scrubbed_title>.ts
<frappe_app>/studio/<studio_app>/studio_components/<component_name>.json
Page scripts are optional. Use TypeScript (.ts) for new page scripts. Keep
existing .js files in JavaScript. Do not create both extensions for one
module.
In page JSON, top-level name is the scrubbed page title. page_name is the
document ID used by Studio and the script bundle. Keep page_name unchanged.
If you change a page title on disk, rename its folder, JSON file, and script
file to match frappe.scrub(page_title).
In exported resource rows, fields such as fields and filters contain
JSON-encoded strings.
Sync and run
- For local editing, run
bench --site <site> watch-studio beside
bench start. bench start runs Studio's Vite dev server, which serves page
scripts and vue components to the editor and preview. If the dev server is
not running, start it with yarn dev in studio/frontend.
- The watcher imports changed app, page, and component JSON automatically. It
finds
studio/ folders at startup. Restart it if you create a folder later.
The watcher does not sync deletions. Vite hot-reloads page scripts and vue
components.
- The watcher imports your edits. You do not need to run
bench migrate.
- Saving a standard document in Studio can export it to disk. Wait for disk
changes to sync before editing the same document in Studio. If the editor
reports an external change, refresh before saving.
Switching app types (standard/custom)
Both types use the same source paths. Do not copy files by hand. A copy does
not update is_standard or frappe_app.
Call StudioApp.enable_app_export(target_app) to make a custom app standard.
This sets is_standard and frappe_app, writes the JSON files, and moves the
source files to disk. Existing page scripts become .js files, the language
they were written in. Use rename_studio_file to change one to .ts.
Call disable_app_export to make the app custom again. A custom app cannot
keep some exported files, including .ts and .vue. If these files exist,
disable_app_export stops unless you confirm their deletion.
Source files
Use the frappe.studio.api file APIs for source files. list_studio_files and
read_studio_file read them. write_studio_file, create_studio_file,
rename_studio_file, and delete_studio_file change them. All of these take
frappe_app and studio_app and work for both app types. A custom app does
not use frappe_app.
The APIs support scripts, stylesheets, and shared code. They reject writes to
the app, page, and component JSON generated by Studio. Change the document
fields for blocks, resources, and routes. In a standard app, you can also edit
the exported JSON on disk.
In a custom app, studio_page/<scrubbed_title>/<scrubbed_title>.js refers to
the page's script field. In a standard app, the page script is a file on disk
with a .js or .ts extension.
Routes and preview
The app's route is its URL prefix. Page routes start with / and are relative
to this prefix. Each page route must be unique within the app. app_home holds
a page document ID.
Use /dev/<app_route> to preview either app type. It uses the editor's renderer
and shows draft blocks and unpublished pages. No build is needed. The user
must have read access on Studio Page.
/<app_route> serves the published build. Pages must be published to use this
route. Guest access also requires allow_guest.
Working across an app
Read an existing page's tree before building a new sibling page. Reuse its
colors, spacing, and section structure. Complete one page before starting the
next. There should be some consistency across pages in terms of layout and
design. When you add a page, update navigation on the pages that link to it.
Build the page
Data
- Resources are stored in
Studio Page.resources. Read the actual DocType
fields before configuring a Document List or Document source. A list exposes
{{ source.data }}. A document exposes {{ source.doc }}. Repeater children
use dataItem for the current row.
- Filters accept
{"status": "Open"} or {"status": ["!=", "Closed"]}.
Use ["in", [...]] for multiple values. Do not use a bare list.
Blocks
draft_blocks holds the editor's JSON array. It contains one root block.
blocks holds the published copy.
[
{
"componentId": "root",
"componentName": "div",
"originalElement": "body",
"baseStyles": {"display": "flex", "flexDirection": "column"},
"children": [
{
"componentId": "div-x1y2z3",
"componentName": "div",
"originalElement": "div",
"baseStyles": {"padding": "20px"},
"mobileStyles": {"padding": "12px"},
"children": [
{
"componentId": "Button-a1b2c3",
"componentName": "Button",
"componentProps": {"label": "{{ saveLabel }}", "variant": "solid"},
"componentEvents": {
"click": {"action": "Run Script", "event": "click", "script": "save()"}
},
"componentSlots": {
"prefix": {
"slotName": "prefix",
"slotContent": [
{
"componentId": "Icon-d4e5f6",
"componentName": "Icon",
"componentProps": {"icon": "lucide-check"}
}
]
}
}
}
]
}
]
}
]
- Set
originalElement to "body" on the root and "div" on containers.
Without this field, the block and its children render blank. Do not set
originalElement on component blocks.
- Each
componentId must be unique in the page. Studio generates
<componentName>-<random string>.
tabletStyles works like mobileStyles. Both hold only the properties that
change from baseStyles.
- Put a slot's blocks in
slotContent, not directly under the slot name.
- Blocks can also have
classes, blockName, and visibilityCondition. Follow
an existing export when writing JSON files directly.
Component families
Some components are a family of blocks, not one block. Examples are List,
Sidebar, SettingsDialog, RadioGroup, and the charts. The editor adds a
family as a complete working tree from a template.
- Copy the tree from the family's template in
studio/frontend/src/utils/blockTemplate/familyTemplates.ts. Do not write
its structure by hand.
- The family members and their props are in
studio/frontend/src/data/componentFamilies.ts.
List
A List does not accept table-style rows and columns objects.
- Set
List.columns to CSS grid track sizes.
- Put
ListHeader and ListRows directly inside List.
- Bind records to
ListRows.items. Put one ListRow template in the
ListRows default component slot.
- The slot exposes
item, index, and value. Bind cells with
{{ item.<field> }}. Bind the row's value prop with {{ value }}.
Page code
A page script is optional. It is a module, and its default export works like a
Vue component's setup() function, not <script setup>: return what the page
uses.
import { ref, onMounted } from "vue"
import { createListResource, toast } from "frappe-ui"
export default function setup({ router }) {
const search = ref("")
const tasks = createListResource({
doctype: "ToDo",
fields: ["name", "description"],
auto: true,
})
function openTask(name) {
router.push({ name: "Task", params: { name } })
}
onMounted(() => toast.success("Ready"))
return { search, tasks, openTask }
}
Vue's setup() rules apply:
- Return each script-defined value or handler used by bindings and events.
- Lifecycle hooks and
watch work. Register them before the first await.
Hooks registered after an await do not run, and watchers are not disposed
automatically.
{{ }} bindings unwrap a returned ref. Event scripts do not: write
search.value there.
Studio differs from Vue in these points:
- The argument is
context. It supplies page resources, variables, route,
router, and socket (the app's socket.io connection).
- Vue and Frappe UI APIs are not injected. Import them, including
call and
toast.
- The page renders nothing until an async
setup() resolves. Load data with an
auto-fetching resource such as createListResource and return it. Use
await only if the page cannot render without the result.
- Keep state in code instead of Studio variables.
- Store shared code in the app's files and import it with
@app/.... This
includes stores, composables, and a standard app's .vue components.
Tailwind CSS
Tailwind classes are supported only in standard apps. The editor and preview
use the editor's stylesheet, which scans standard apps on disk but not a
custom app's files. In a custom app, set appearance in block style values.
Text size classes and lucide-* icon classes are the exception. They work in
both app types.
Tailwind runs at build time. Publishing builds every app and includes its
Tailwind classes in the CSS.
If a build fails or has not run, the app uses the shared Studio renderer.
Its stylesheet contains only the classes included in that renderer's build.
Publish the app again to include the app's own classes.
In a standard app, Tailwind scans only <frappe_app>/studio/<studio_app>/.
Classes in imported code outside that folder are not included. For example,
this can affect a shared/ package also used by the Frappe app's frontend.
To scan extra paths in a standard app, add tailwind.config.ts or
tailwind.config.js next to tsconfig.json. List the paths in content as
an array of globs. Paths are relative to the config file. Studio skips
node_modules in these paths.
Studio uses only content and safelist. It ignores theme and plugins.
The editor combines all app configs into one stylesheet. Keep safelist
short. Restart the Vite dev server after adding or changing the config.
export default {
content: ["../../shared/src/**/*.{vue,ts}"],
safelist: ["prose-sm"],
}
Vue components
A standard app can use its own Vue components as blocks. A custom app cannot.
Export the app first. Choose the smallest tool that does the job:
- Built-in component: use it when it already does the job. Do not write a
Vue component only to restyle a built-in component.
- Studio Component (
studio_components/*.json): use it for a reusable
layout made of ordinary blocks.
- Vue component: use it only when built-in components and block
compositions cannot express the UI cleanly. This means a stateful widget (a
rating input, a drag-and-drop board, a canvas or SVG drawing), a third-party
library, or markup that needs dozens of blocks and heavy script glue.
To add a Vue component:
Put the single-file component at
<frappe_app>/studio/<studio_app>/components/<ComponentName>.vue.
Studio finds .vue files anywhere inside <frappe_app>/studio/<studio_app>/.
The file name becomes the block's componentName.
The file name must be unique in the app and must not match a built-in
component such as Button. Studio skips a conflicting file without showing
an error in the editor.
Write a normal Vue single-file component. Use Tailwind classes and espresso
tokens from DESIGN.md. Use one root element where possible, or
bind $attrs to the element that should receive block styles.
Set isCustomVueComponent: true on its block. Do not set originalElement.
Props, {{ }} bindings, and {"$type": "variable"} v-model bindings work as
they do for built-in components. Use componentEvents for emitted events
and componentSlots for named slots:
{
"componentId": "RatingInput-ab12cd",
"componentName": "RatingInput",
"isCustomVueComponent": true,
"componentProps": {"max": 5, "modelValue": {"$type": "variable", "name": "rating"}},
"componentEvents": {
"change": {"action": "Run Script", "event": "change", "script": "saveRating()"}
}
}
With the Vite dev server running, .vue file changes update the component
panel and canvas without a restart. This includes adding and removing files.
A page script can also import the component directly and render it with h():
import Board from "@app/components/Board.vue".
Verify
- You need not build or publish to verify a change. Do not run
bench build or
build-studio-app after an edit. The editor and preview show saved work
without a build, including draft blocks and unpublished pages.
- Check the page in preview at
/dev/<app_route><page_route>.
- Check desktop, mobile, and tablet styles.
- Page script, event script, and binding errors go to
console.error. The page
still renders. The editor also shows a page script error while that script is
open.
- Build only to check the published route
/<app_route>. Publish the app, or
run bench --site <site> build-studio-app <app_name>.
1---2name: studio-app-building3description: Build or edit Frappe Studio apps and pages. Covers block trees, data bindings, page scripts, design, and standard (exported) apps. Use for Studio App or Studio Page work. Excludes ordinary Vue frontends.4metadata:5 source: https://skillmd.com/skills/frappe/studio-app-building6---78# Building Frappe Studio apps910A Studio app contains `Studio Page` documents. Each page has a JSON block tree,11optional `Studio Page Resource` rows, and page logic.1213- Read [RULES.md](RULES.md) before writing bindings, events, or styles.14- Read [DESIGN.md](DESIGN.md) before building or restyling a page.15- Read [ROUTING.md](ROUTING.md) when working on navigation, redirects, guards,16 or `boot` data.17- Check `studio/frontend/src/data/components.ts` and18 `studio/frontend/src/data/componentFamilies.ts` for available components.1920## Custom and standard apps2122Read `is_standard` on the Studio App before editing it. This field controls23source storage, compilation, editing, and preview. Read the matching Custom apps24or Standard apps section. The later sections apply to both types unless they25name one type.2627| Detail | Custom app (`is_standard` 0) | Standard app (`is_standard` 1) |28| --- | --- | --- |29| Source files | `Studio App File` records, plus each page's own `script` field | Files under `<frappe_app>/studio/<studio_app>/` |30| Compiled in the editor and preview | The browser | Vite's dev server |31| Compiled on publish | Vite, from a copy of the source files | Vite |32| Languages | `.js`, `.json`, `.css` | `.js`, `.json`, `.css` + `.ts`, `.vue` |33| Edit | In Studio, on any site | The files or Studio, in developer mode only |3435## Custom apps3637- Insert `Studio App` and `Studio Page` documents, or create them in Studio.38 Then write the source files.39- No build is needed while editing. After you save a file, it runs on the next40 render in the editor and preview. Publishing builds the app with Vite.41- The browser compiles and runs the source as written. A custom app rejects42 `.ts` and `.vue` files, `tsconfig.json`, Tailwind config files, and dotfiles.43 TypeScript syntax inside a `.js` file is a runtime syntax error.44- Use Studio Components for reusable layouts. Export the app if you need your45 own `.vue` files.46- The app can import `vue`, `vue-router`, `pinia`, `frappe-ui`,47 `frappe-ui/list`, `frappe-ui/charts`, and its own files. There is no npm.48 Export the app if it needs another package. Export makes the app standard.49- Preview and publishing insert CSS without changes. Use public asset URLs,50 such as `/files/logo.png`. CSS references cannot read the server filesystem.5152### Module rules5354- Use ESM `import` and `export`. Relative paths and `@app/` are supported.55 Dynamic `import()` requires a literal path.56- A JSON file exports its object as the default export. Its top-level keys are57 also named exports. Import CSS for its side effects. CSS has no default58 export.59- Import queries such as `?raw` and `?url` are not supported. Import fragments60 and attributes are also not supported. Use identifiers for import and export61 names. Do not use string names.62- `require`, `module`, and `exports` are not available. These names are also63 reserved as top-level bindings.64- Top-level `await` and `import.meta` are not supported. Put asynchronous work65 in `setup()` or an event handler. For cyclic imports, read imported values66 inside `setup()` instead of during module execution.6768## Standard apps6970- Developer mode is required to save a standard app, page, or component71 (`validate_standard_app_change`). Document saves export only in developer72 mode (`can_export`). Both checks are in `frappe/studio/export.py`.73- Create the app as standard: insert a `Studio App` with `is_standard` set to 174 and `frappe_app` set to an installed Frappe app. `frappe_app` is mandatory75 when `is_standard` is set. The save writes the export folder. To convert an76 existing custom app, see [Switching app types](#switching-app-types).77- Files are stored under the linked Frappe app. Before creating files directly,78 inspect an existing export such as `helpdesk/studio/helpdesk/`:7980 ```text81 <frappe_app>/studio/<studio_app>/<studio_app>.json82 <frappe_app>/studio/<studio_app>/studio_page/<scrubbed_title>/<scrubbed_title>.json83 <frappe_app>/studio/<studio_app>/studio_page/<scrubbed_title>/<scrubbed_title>.ts84 <frappe_app>/studio/<studio_app>/studio_components/<component_name>.json85 ```8687- Page scripts are optional. Use TypeScript (`.ts`) for new page scripts. Keep88 existing `.js` files in JavaScript. Do not create both extensions for one89 module.90- In page JSON, top-level `name` is the scrubbed page title. `page_name` is the91 document ID used by Studio and the script bundle. Keep `page_name` unchanged.92- If you change a page title on disk, rename its folder, JSON file, and script93 file to match `frappe.scrub(page_title)`.94- In exported resource rows, fields such as `fields` and `filters` contain95 JSON-encoded strings.9697### Sync and run9899- For local editing, run `bench --site <site> watch-studio` beside100 `bench start`. `bench start` runs Studio's Vite dev server, which serves page101 scripts and vue components to the editor and preview. If the dev server is102 not running, start it with `yarn dev` in `studio/frontend`.103- The watcher imports changed app, page, and component JSON automatically. It104 finds `studio/` folders at startup. Restart it if you create a folder later.105 The watcher does not sync deletions. Vite hot-reloads page scripts and vue106 components.107- The watcher imports your edits. You do not need to run `bench migrate`.108- Saving a standard document in Studio can export it to disk. Wait for disk109 changes to sync before editing the same document in Studio. If the editor110 reports an external change, refresh before saving.111112## Switching app types (standard/custom)113114Both types use the same source paths. Do not copy files by hand. A copy does115not update `is_standard` or `frappe_app`.116117Call `StudioApp.enable_app_export(target_app)` to make a custom app standard.118This sets `is_standard` and `frappe_app`, writes the JSON files, and moves the119source files to disk. Existing page scripts become `.js` files, the language120they were written in. Use `rename_studio_file` to change one to `.ts`.121122Call `disable_app_export` to make the app custom again. A custom app cannot123keep some exported files, including `.ts` and `.vue`. If these files exist,124`disable_app_export` stops unless you confirm their deletion.125126## Source files127128Use the `frappe.studio.api` file APIs for source files. `list_studio_files` and129`read_studio_file` read them. `write_studio_file`, `create_studio_file`,130`rename_studio_file`, and `delete_studio_file` change them. All of these take131`frappe_app` and `studio_app` and work for both app types. A custom app does132not use `frappe_app`.133134The APIs support scripts, stylesheets, and shared code. They reject writes to135the app, page, and component JSON generated by Studio. Change the document136fields for blocks, resources, and routes. In a standard app, you can also edit137the exported JSON on disk.138139In a custom app, `studio_page/<scrubbed_title>/<scrubbed_title>.js` refers to140the page's `script` field. In a standard app, the page script is a file on disk141with a `.js` or `.ts` extension.142143## Routes and preview144145The app's `route` is its URL prefix. Page routes start with `/` and are relative146to this prefix. Each page route must be unique within the app. `app_home` holds147a page document ID.148149Use `/dev/<app_route>` to preview either app type. It uses the editor's renderer150and shows draft blocks and unpublished pages. No build is needed. The user151must have read access on Studio Page.152153`/<app_route>` serves the published build. Pages must be published to use this154route. Guest access also requires `allow_guest`.155156## Working across an app157158Read an existing page's tree before building a new sibling page. Reuse its159colors, spacing, and section structure. Complete one page before starting the160next. There should be some consistency across pages in terms of layout and161design. When you add a page, update navigation on the pages that link to it.162163## Build the page164165### Data166167- Resources are stored in `Studio Page.resources`. Read the actual DocType168 fields before configuring a Document List or Document source. A list exposes169 `{{ source.data }}`. A document exposes `{{ source.doc }}`. Repeater children170 use `dataItem` for the current row.171- Filters accept `{"status": "Open"}` or `{"status": ["!=", "Closed"]}`.172 Use `["in", [...]]` for multiple values. Do not use a bare list.173174### Blocks175176`draft_blocks` holds the editor's JSON array. It contains one root block.177`blocks` holds the published copy.178179```json180[181 {182 "componentId": "root",183 "componentName": "div",184 "originalElement": "body",185 "baseStyles": {"display": "flex", "flexDirection": "column"},186 "children": [187 {188 "componentId": "div-x1y2z3",189 "componentName": "div",190 "originalElement": "div",191 "baseStyles": {"padding": "20px"},192 "mobileStyles": {"padding": "12px"},193 "children": [194 {195 "componentId": "Button-a1b2c3",196 "componentName": "Button",197 "componentProps": {"label": "{{ saveLabel }}", "variant": "solid"},198 "componentEvents": {199 "click": {"action": "Run Script", "event": "click", "script": "save()"}200 },201 "componentSlots": {202 "prefix": {203 "slotName": "prefix",204 "slotContent": [205 {206 "componentId": "Icon-d4e5f6",207 "componentName": "Icon",208 "componentProps": {"icon": "lucide-check"}209 }210 ]211 }212 }213 }214 ]215 }216 ]217 }218]219```220221- Set `originalElement` to `"body"` on the root and `"div"` on containers.222 Without this field, the block and its children render blank. Do not set223 `originalElement` on component blocks.224- Each `componentId` must be unique in the page. Studio generates225 `<componentName>-<random string>`.226- `tabletStyles` works like `mobileStyles`. Both hold only the properties that227 change from `baseStyles`.228- Put a slot's blocks in `slotContent`, not directly under the slot name.229- Blocks can also have `classes`, `blockName`, and `visibilityCondition`. Follow230 an existing export when writing JSON files directly.231232### Component families233234Some components are a family of blocks, not one block. Examples are `List`,235`Sidebar`, `SettingsDialog`, `RadioGroup`, and the charts. The editor adds a236family as a complete working tree from a template.237238- Copy the tree from the family's template in239 `studio/frontend/src/utils/blockTemplate/familyTemplates.ts`. Do not write240 its structure by hand.241- The family members and their props are in242 `studio/frontend/src/data/componentFamilies.ts`.243244#### List245246A `List` does not accept table-style `rows` and `columns` objects.247248- Set `List.columns` to CSS grid track sizes.249- Put `ListHeader` and `ListRows` directly inside `List`.250- Bind records to `ListRows.items`. Put one `ListRow` template in the251 `ListRows` `default` component slot.252- The slot exposes `item`, `index`, and `value`. Bind cells with253 `{{ item.<field> }}`. Bind the row's `value` prop with `{{ value }}`.254255## Page code256257A page script is optional. It is a module, and its default export works like a258Vue component's `setup()` function, not `<script setup>`: return what the page259uses.260261```js262import { ref, onMounted } from "vue"263import { createListResource, toast } from "frappe-ui"264265export default function setup({ router }) {266 const search = ref("")267 const tasks = createListResource({268 doctype: "ToDo",269 fields: ["name", "description"],270 auto: true,271 })272273 function openTask(name) {274 router.push({ name: "Task", params: { name } })275 }276277 onMounted(() => toast.success("Ready"))278279 return { search, tasks, openTask }280}281```282283Vue's `setup()` rules apply:284285- Return each script-defined value or handler used by bindings and events.286- Lifecycle hooks and `watch` work. Register them before the first `await`.287 Hooks registered after an `await` do not run, and watchers are not disposed288 automatically.289- `{{ }}` bindings unwrap a returned ref. Event scripts do not: write290 `search.value` there.291292Studio differs from Vue in these points:293294- The argument is `context`. It supplies page resources, variables, `route`,295 `router`, and `socket` (the app's socket.io connection).296- Vue and Frappe UI APIs are not injected. Import them, including `call` and297 `toast`.298- The page renders nothing until an async `setup()` resolves. Load data with an299 auto-fetching resource such as `createListResource` and return it. Use300 `await` only if the page cannot render without the result.301- Keep state in code instead of Studio variables.302- Store shared code in the app's files and import it with `@app/...`. This303 includes stores, composables, and a standard app's `.vue` components.304305## Tailwind CSS306307- Tailwind classes are supported only in standard apps. The editor and preview308 use the editor's stylesheet, which scans standard apps on disk but not a309 custom app's files. In a custom app, set appearance in block style values.310 Text size classes and `lucide-*` icon classes are the exception. They work in311 both app types.312- Tailwind runs at build time. Publishing builds every app and includes its313 Tailwind classes in the CSS.314- If a build fails or has not run, the app uses the shared Studio renderer.315 Its stylesheet contains only the classes included in that renderer's build.316 Publish the app again to include the app's own classes.317- In a standard app, Tailwind scans only `<frappe_app>/studio/<studio_app>/`.318 Classes in imported code outside that folder are not included. For example,319 this can affect a `shared/` package also used by the Frappe app's frontend.320- To scan extra paths in a standard app, add `tailwind.config.ts` or321 `tailwind.config.js` next to `tsconfig.json`. List the paths in `content` as322 an array of globs. Paths are relative to the config file. Studio skips323 `node_modules` in these paths.324- Studio uses only `content` and `safelist`. It ignores `theme` and `plugins`.325 The editor combines all app configs into one stylesheet. Keep `safelist`326 short. Restart the Vite dev server after adding or changing the config.327328 ```js329 export default {330 content: ["../../shared/src/**/*.{vue,ts}"],331 safelist: ["prose-sm"],332 }333 ```334335## Vue components336337A standard app can use its own Vue components as blocks. A custom app cannot.338Export the app first. Choose the smallest tool that does the job:339340- **Built-in component**: use it when it already does the job. Do not write a341 Vue component only to restyle a built-in component.342- **Studio Component** (`studio_components/*.json`): use it for a reusable343 layout made of ordinary blocks.344- **Vue component**: use it only when built-in components and block345 compositions cannot express the UI cleanly. This means a stateful widget (a346 rating input, a drag-and-drop board, a canvas or SVG drawing), a third-party347 library, or markup that needs dozens of blocks and heavy script glue.348349To add a Vue component:350351- Put the single-file component at352 `<frappe_app>/studio/<studio_app>/components/<ComponentName>.vue`.353 Studio finds `.vue` files anywhere inside `<frappe_app>/studio/<studio_app>/`.354 The file name becomes the block's `componentName`.355- The file name must be unique in the app and must not match a built-in356 component such as `Button`. Studio skips a conflicting file without showing357 an error in the editor.358- Write a normal Vue single-file component. Use Tailwind classes and espresso359 tokens from [DESIGN.md](DESIGN.md). Use one root element where possible, or360 bind `$attrs` to the element that should receive block styles.361- Set `isCustomVueComponent: true` on its block. Do not set `originalElement`.362 Props, `{{ }}` bindings, and `{"$type": "variable"}` v-model bindings work as363 they do for built-in components. Use `componentEvents` for emitted events364 and `componentSlots` for named slots:365366 ```json367 {368 "componentId": "RatingInput-ab12cd",369 "componentName": "RatingInput",370 "isCustomVueComponent": true,371 "componentProps": {"max": 5, "modelValue": {"$type": "variable", "name": "rating"}},372 "componentEvents": {373 "change": {"action": "Run Script", "event": "change", "script": "saveRating()"}374 }375 }376 ```377378- With the Vite dev server running, `.vue` file changes update the component379 panel and canvas without a restart. This includes adding and removing files.380 A page script can also import the component directly and render it with `h()`:381 `import Board from "@app/components/Board.vue"`.382383## Verify384385- You need not build or publish to verify a change. Do not run `bench build` or386 `build-studio-app` after an edit. The editor and preview show saved work387 without a build, including draft blocks and unpublished pages.388- Check the page in preview at `/dev/<app_route><page_route>`.389- Check desktop, mobile, and tablet styles.390- Page script, event script, and binding errors go to `console.error`. The page391 still renders. The editor also shows a page script error while that script is392 open.393- Build only to check the published route `/<app_route>`. Publish the app, or394 run `bench --site <site> build-studio-app <app_name>`.