Frappe frontend development

Frappe Frontend Development

Build modern frontend applications using Frappe UI (Vue 3 + TailwindCSS) and portal pages.

When to use

• Building a custom SPA frontend for a Frappe app
• Using Frappe UI components (Button, Dialog, ListView, etc.)
• Implementing data fetching with Resource, ListResource, DocumentResource
• Creating portal/public-facing pages
• Setting up Vue 3 frontend tooling inside a Frappe app

Inputs required

• App name and whether frontend already exists
• Frontend type (full SPA via Frappe UI, or portal pages)
• Authentication requirements (logged-in users, guest access)
• Key components and data resources needed

Procedure

0) Choose frontend approach

Approach	When to Use	Stack
Frappe UI SPA	Custom app frontend	Vue 3, TailwindCSS, Vite
Portal pages	Simple public pages	Jinja + HTML, minimal JS
Desk extensions	Admin UI enhancements	Form/List scripts (see frappe-desk-customization)

1) Scaffold Frappe UI frontend

# Inside your Frappe app directory
cd apps/my_app
npx degit frappe/frappe-ui-starter frontend

# Install dependencies
cd frontend
yarn

# Start dev server
yarn dev

2) Configure main.js

import { createApp } from 'vue'
import {
    FrappeUI,
    setConfig,
    frappeRequest,
    resourcesPlugin,
    pageMetaPlugin
} from 'frappe-ui'
import App from './App.vue'
import './index.css'

let app = createApp(App)

// Register FrappeUI plugin (components + directives)
app.use(FrappeUI)

// Enable Frappe response parsing
setConfig('resourceFetcher', frappeRequest)

// Optional: Options API resource support
app.use(resourcesPlugin)

// Optional: Reactive page titles
app.use(pageMetaPlugin)

app.mount('#app')

3) Fetch data with Resources

Generic Resource — for custom API calls:

import { createResource } from 'frappe-ui'

let stats = createResource({
    url: 'my_app.api.get_dashboard_stats',
    params: { period: 'monthly' },
    auto: true,
    cache: 'dashboard-stats',
    transform(data) {
        return { ...data, formatted_total: format_currency(data.total) }
    },
    onSuccess(data) { console.log('Loaded:', data) },
    onError(error) { console.error('Failed:', error) }
})

// Properties
stats.data       // Response data
stats.loading    // Boolean: request in progress
stats.error      // Error object if failed
stats.fetched    // Boolean: data fetched at least once

// Methods
stats.fetch()    // Trigger request
stats.reload()   // Re-fetch
stats.submit({ period: 'weekly' })  // Fetch with new params
stats.reset()    // Reset state

List Resource — for DocType lists with pagination:

import { createListResource } from 'frappe-ui'

let todos = createListResource({
    doctype: 'ToDo',
    fields: ['name', 'description', 'status'],
    filters: { status: 'Open' },
    orderBy: 'creation desc',
    pageLength: 20,
    auto: true,
    cache: 'open-todos'
})

// List-specific API
todos.data              // Array of records
todos.hasNextPage       // Boolean: more pages
todos.next()            // Load next page
todos.reload()          // Refresh list

// CRUD operations
todos.insert.submit({ description: 'New task' })
todos.setValue.submit({ name: 'TODO-001', status: 'Closed' })
todos.delete.submit('TODO-001')
todos.runDocMethod.submit({ method: 'send_email', name: 'TODO-001' })

Document Resource — for single document operations:

import { createDocumentResource } from 'frappe-ui'

let todo = createDocumentResource({
    doctype: 'ToDo',
    name: 'TODO-001',
    whitelistedMethods: {
        sendEmail: 'send_email',
        markComplete: 'mark_complete'
    },
    onSuccess(doc) { console.log('Loaded:', doc.name) }
})

// Document API
todo.doc                 // Full document object
todo.reload()            // Refresh document

// Update fields
todo.setValue.submit({ status: 'Closed' })

// Debounced update (coalesces rapid changes)
todo.setValueDebounced.submit({ description: 'Updated' })

// Call whitelisted methods
todo.sendEmail.submit({ email: '[email protected]' })

// Delete
todo.delete.submit()

4) Use Frappe UI components

<template>
    <div class="p-4">
        <Button variant="solid" theme="blue" @click="showDialog = true">
            Add Todo
        </Button>

        <ListView :columns="columns" :rows="todos.data">
            <template #cell="{ column, row, value }">
                <Badge v-if="column.key === 'status'" :theme="value === 'Open' ? 'orange' : 'green'">
                    {{ value }}
                </Badge>
                <span v-else>{{ value }}</span>
            </template>
        </ListView>

        <Dialog v-model="showDialog" :options="{ title: 'New Todo' }">
            <template #body-content>
                <TextInput v-model="newDescription" placeholder="Description" />
            </template>
            <template #actions>
                <Button variant="solid" @click="addTodo">Save</Button>
            </template>
        </Dialog>
    </div>
</template>

<script setup>
import { ref } from 'vue'
import { Button, ListView, Badge, Dialog, TextInput, createListResource } from 'frappe-ui'

const showDialog = ref(false)
const newDescription = ref('')

const todos = createListResource({
    doctype: 'ToDo',
    fields: ['name', 'description', 'status'],
    auto: true
})

const columns = [
    { label: 'Description', key: 'description' },
    { label: 'Status', key: 'status', width: 100 }
]

function addTodo() {
    todos.insert.submit(
        { description: newDescription.value },
        { onSuccess() { showDialog.value = false; newDescription.value = '' } }
    )
}
</script>

Available component categories:

Category	Components
Inputs	TextInput, Textarea, Select, Combobox, MultiSelect, Checkbox, Switch, DatePicker, TimePicker, Slider, Password, Rating
Display	Alert, Avatar, Badge, Breadcrumbs, Progress, Tooltip, ErrorMessage, LoadingText
Navigation	Button, Dropdown, Tabs, Sidebar, Popover
Layout	Dialog, ListView, Calendar, Tree
Rich Content	TextEditor (TipTap), Charts, FileUploader

5) Add directives and utilities

<script setup>
import { onOutsideClickDirective, visibilityDirective, debounce } from 'frappe-ui'

const vOnOutsideClick = onOutsideClickDirective
const vVisibility = visibilityDirective

const debouncedSearch = debounce((query) => {
    // Search logic
}, 500)
</script>

<template>
    <div v-on-outside-click="closeDropdown">...</div>
    <div v-visibility="onVisible">Lazy loaded content</div>
</template>

6) Configure TailwindCSS

// tailwind.config.js
module.exports = {
    presets: [
        require('frappe-ui/src/utils/tailwind.config')
    ],
    content: [
        './index.html',
        './src/**/*.{vue,js,ts}',
        './node_modules/frappe-ui/src/components/**/*.{vue,js,ts}'
    ]
}

7) Build for production

# Build frontend assets
cd frontend && yarn build

# Assets are served at /frontend by Frappe

8) Portal pages (alternative approach)

For simple public pages without a full SPA:

# In your app's website/ or www/ directory
# my_app/www/my_page.html

{% extends "templates/web.html" %}
{% block page_content %}
<h1>{{ title }}</h1>
<p>Welcome, {{ frappe.session.user }}</p>
{% endblock %}

# my_app/www/my_page.py
def get_context(context):
    context.title = "My Page"
    context.data = frappe.get_all("ToDo", filters={"owner": frappe.session.user})

Verification

• yarn dev starts without errors
• Components render correctly
• Data resources fetch and display data
• CRUD operations work (insert, update, delete)
• Authentication works (login redirect, session handling)
• yarn build completes successfully
• Production assets serve correctly from Frappe

Failure modes / debugging

• CORS errors: Set ignore_csrf for local dev; ensure proper CSRF token in production
• 404 on API calls: Check method path; verify @frappe.whitelist() decorator
• Component not found: Ensure import path is correct; check frappe-ui version
• Styles broken: Verify TailwindCSS config includes frappe-ui component paths
• Auth issues: Check session cookie; ensure site URL matches in dev proxy config

Escalation

• For Desk UI scripting → frappe-desk-customization
• For API endpoint implementation → frappe-api-development
• For app architecture → frappe-app-development
• For UI/UX patterns from official apps → frappe-ui-patterns

References

• references/frappe-ui.md — Frappe UI framework reference
• references/portal-development.md — Portal pages overview

Guardrails

• ALWAYS use Frappe UI for custom frontends: Never use vanilla JS, jQuery, or custom frameworks for app frontends — Frappe UI (Vue 3 + TailwindCSS) is the standard. This ensures consistency with CRM, Helpdesk, and other official Frappe apps.
• Use FrappeUI components: Prefer <Button>, <Input>, <FormControl> over custom HTML for consistency
• Follow CRM/Helpdesk app shell patterns: For CRUD apps, follow frappe-ui-patterns skill which documents sidebar navigation, list views, form layouts, and routing patterns from official Frappe apps
• Handle loading states: Always show loading indicators during API calls; use resource.loading
• Validate API responses: Check for errors before accessing data; handle exc responses
• Configure proxy correctly: Dev server must proxy API calls to Frappe backend
• Handle authentication: Check $session.user and redirect to login when needed

Common Mistakes

Mistake	Why It Fails	Fix
Missing CORS/proxy setup	API calls fail in development	Configure Vite proxy to forward /api to Frappe site
Not handling auth state	App crashes for logged-out users	Check call('frappe.auth.get_logged_user') on mount
Wrong resource URLs	404 errors on API calls	Use createResource with correct method paths
Hardcoded site URL	Breaks across environments	Use relative URLs or environment variables
Not including CSRF token	POST requests fail	Use frappe.csrf_token or configure session properly
Missing TailwindCSS config	Frappe UI styles broken	Include frappe-ui in Tailwind content paths
Using vanilla JS/jQuery	Inconsistent UX, maintenance burden	Always use Frappe UI for custom frontends
Custom app shell design	Inconsistent with ecosystem	Follow CRM/Helpdesk patterns for navigation, lists, forms