{"slug":"lubusin-frontend-development","name":"frontend-development","description":"Build modern Vue 3 frontend apps using Frappe UI with components, data fetching, and portal pages. Use when creating custom frontends, SPAs, or portal interfaces for Frappe applications.","long_description":"---\nname: frontend-development\ndescription: Build modern Vue 3 frontend apps using Frappe UI with components, data fetching, and portal pages. Use when creating custom frontends, SPAs, or portal interfaces for Frappe applications.\n---\n\n# Frappe Frontend Development\n\nBuild modern frontend applications using Frappe UI (Vue 3 + TailwindCSS) and portal pages.\n\n## When to use\n\n- Building a custom SPA frontend for a Frappe app\n- Using Frappe UI components (Button, Dialog, ListView, etc.)\n- Implementing data fetching with Resource, ListResource, DocumentResource\n- Creating portal/public-facing pages\n- Setting up Vue 3 frontend tooling inside a Frappe app\n\n## Inputs required\n\n- App name and whether frontend already exists\n- Frontend type (full SPA via Frappe UI, or portal pages)\n- Authentication requirements (logged-in users, guest access)\n- Key components and data resources needed\n\n## Procedure\n\n### 0) Choose frontend approach\n\n| Approach | When to Use | Stack |\n|----------|-------------|-------|\n| Frappe UI SPA | Custom app frontend | Vue 3, TailwindCSS, Vite |\n| Portal pages | Simple public pages | Jinja + HTML, minimal JS |\n| Desk extensions | Admin UI enhancements | Form/List scripts (see `desk-customization`) |\n\n### 1) Scaffold Frappe UI frontend\n\n```bash\n# Inside your Frappe app directory\ncd apps/my_app\nnpx degit frappe/frappe-ui-starter frontend\n\n# Install dependencies\ncd frontend\nyarn\n\n# Start dev server\nyarn dev\n```\n\n### 2) Configure main.js\n\n```javascript\nimport { createApp } from 'vue'\nimport {\n FrappeUI,\n setConfig,\n frappeRequest,\n resourcesPlugin,\n pageMetaPlugin\n} from 'frappe-ui'\nimport App from './App.vue'\nimport './index.css'\n\nlet app = createApp(App)\n\n// Register FrappeUI plugin (components + directives)\napp.use(FrappeUI)\n\n// Enable Frappe response parsing\nsetConfig('resourceFetcher', frappeRequest)\n\n// Optional: Options API resource support\napp.use(resourcesPlugin)\n\n// Optional: Reactive page titles\napp.use(pageMetaPlugin)\n\napp.mount('#app')\n```\n\n### 3) Fetch data with Resources\n\n**Generic Resource** — for custom API calls:\n\n```javascript\nimport { createResource } from 'frappe-ui'\n\nlet stats = createResource({\n url: 'my_app.api.get_dashboard_stats',\n params: { period: 'monthly' },\n auto: true,\n cache: 'dashboard-stats',\n transform(data) {\n return { ...data, formatted_total: format_currency(data.total) }\n },\n onSuccess(data) { console.log('Loaded:', data) },\n onError(error) { console.error('Failed:', error) }\n})\n\n// Properties\nstats.data // Response data\nstats.loading // Boolean: request in progress\nstats.error // Error object if failed\nstats.fetched // Boolean: data fetched at least once\n\n// Methods\nstats.fetch() // Trigger request\nstats.reload() // Re-fetch\nstats.submit({ period: 'weekly' }) // Fetch with new params\nstats.reset() // Reset state\n```\n\n**List Resource** — for DocType lists with pagination:\n\n```javascript\nimport { createListResource } from 'frappe-ui'\n\nlet todos = createListResource({\n doctype: 'ToDo',\n fields: ['name', 'description', 'status'],\n filters: { status: 'Open' },\n orderBy: 'creation desc',\n pageLength: 20,\n auto: true,\n cache: 'open-todos'\n})\n\n// List-specific API\ntodos.data // Array of records\ntodos.hasNextPage // Boolean: more pages\ntodos.next() // Load next page\ntodos.reload() // Refresh list\n\n// CRUD operations\ntodos.insert.submit({ description: 'New task' })\ntodos.setValue.submit({ name: 'TODO-001', status: 'Closed' })\ntodos.delete.submit('TODO-001')\ntodos.runDocMethod.submit({ method: 'send_email', name: 'TODO-001' })\n```\n\n**Document Resource** — for single document operations:\n\n```javascript\nimport { createDocumentResource } from 'frappe-ui'\n\nlet todo = createDocumentResource({\n doctype: 'ToDo',\n name: 'TODO-001',\n whitelistedMethods: {\n sendEmail: 'send_email',\n markComplete: 'mark_complete'\n },\n onSuccess(doc) { console.log('Loaded:', doc.name) }\n})\n\n// Document API\ntodo.doc // Full document object\ntodo.reload() // Refresh document\n\n// Update fields\ntodo.setValue.submit({ status: 'Closed' })\n\n// Debounced update (coalesces rapid changes)\ntodo.setValueDebounced.submit({ description: 'Updated' })\n\n// Call whitelisted methods\ntodo.sendEmail.submit({ email: 'user@example.com' })\n\n// Delete\ntodo.delete.submit()\n```\n\n### 4) Use Frappe UI components\n\n```vue\n\n\n\n```\n\n**Available component categories:**\n\n| Category | Components |\n|----------|------------|\n| Inputs | TextInput, Textarea, Select, Combobox, MultiSelect, Checkbox, Switch, DatePicker, TimePicker, Slider, Password, Rating |\n| Display | Alert, Avatar, Badge, Breadcrumbs, Progress, Tooltip, ErrorMessage, LoadingText |\n| Navigation | Button, Dropdown, Tabs, Sidebar, Popover |\n| Layout | Dialog, ListView, Calendar, Tree |\n| Rich Content | TextEditor (TipTap), Charts, FileUploader |\n\n### 5) Add directives and utilities\n\n```vue\n\n\n\n```\n\n### 6) Configure TailwindCSS\n\n```javascript\n// tailwind.config.js\nmodule.exports = {\n presets: [\n require('frappe-ui/src/utils/tailwind.config')\n ],\n content: [\n './index.html',\n './src/**/*.{vue,js,ts}',\n './node_modules/frappe-ui/src/components/**/*.{vue,js,ts}'\n ]\n}\n```\n\n### 7) Build for production\n\n```bash\n# Build frontend assets\ncd frontend && yarn build\n\n# Assets are served at /frontend by Frappe\n```\n\n### 8) Portal pages (alternative approach)\n\nFor simple public pages without a full SPA:\n\n```python\n# In your app's website/ or www/ directory\n# my_app/www/my_page.html\n\n{% extends \"templates/web.html\" %}\n{% block page_content %}\n

{{ title }}

\n

Welcome, {{ frappe.session.user }}

\n{% endblock %}\n```\n\n```python\n# my_app/www/my_page.py\ndef get_context(context):\n context.title = \"My Page\"\n context.data = frappe.get_all(\"ToDo\", filters={\"owner\": frappe.session.user})\n```\n\n## Verification\n\n- [ ] `yarn dev` starts without errors\n- [ ] Components render correctly\n- [ ] Data resources fetch and display data\n- [ ] CRUD operations work (insert, update, delete)\n- [ ] Authentication works (login redirect, session handling)\n- [ ] `yarn build` completes successfully\n- [ ] Production assets serve correctly from Frappe\n\n## Failure modes / debugging\n\n- **CORS errors**: Set `ignore_csrf` for local dev; ensure proper CSRF token in production\n- **404 on API calls**: Check method path; verify `@frappe.whitelist()` decorator\n- **Component not found**: Ensure import path is correct; check `frappe-ui` version\n- **Styles broken**: Verify TailwindCSS config includes `frappe-ui` component paths\n- **Auth issues**: Check session cookie; ensure site URL matches in dev proxy config\n\n## Escalation\n\n- For Desk UI scripting → `desk-customization`\n- For API endpoint implementation → `api-development`\n- For app architecture → `app-development`\n- For UI/UX patterns from official apps → `ui-patterns`\n\n## References\n\n- [references/frappe-ui.md](references/frappe-ui.md) — Frappe UI framework reference\n- [references/portal-development.md](references/portal-development.md) — Portal pages overview\n\n## Guardrails\n\n- **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.\n- **Use FrappeUI components**: Prefer `