Vue WebApp Creation in Custom_ERP
This skill guides you through creating a new Vue web application within the custom_erp Frappe app, from initial setup to production deployment.
Quick Reference
For a new app called my-app at route /my-app, you need:
| File/Directory | Purpose |
|---|---|
my-app/ | Source directory with index.html and src/ |
my-app/src/main.js | Vue app initialization |
my-app/src/App.vue | Root component with PWA setup |
my-app/src/router.js | Vue Router with auth guards |
my-app/src/MyApp.vue | Main page component |
custom_erp/www/my-app.html | Frappe production entry (hyphenated) |
custom_erp/www/my_app.py | Frappe context (underscored) |
public/manifest-my-app.json | PWA manifest |
public/icons/my-app/icon-512x512.png | App icon |
vite.config.js | Add to apps array |
build-apps.js | Add to apps array + theme config |
Naming Convention
CRITICAL: Follow this naming pattern exactly:
| Location | Format | Example |
|---|---|---|
| Directory & URL | hyphenated | my-app, /my-app |
| www/*.html | hyphenated | my-app.html |
| www/*.py | underscored | my_app.py |
| vite.config.js | hyphenated | 'my-app' |
| build-apps.js | hyphenated | 'my-app' |
| manifest | hyphenated | manifest-my-app.json |
| Router base | hyphenated | /my-app |
Step-by-Step Creation Process
Step 1: Create Directory Structure
bash1cd frappe-bench/apps/custom_erp 2mkdir -p my-app/src
Step 2: Create Source Files
Create all files in this order. See templates.md for complete file contents.
my-app/index.html- Dev entry pointmy-app/src/main.js- Vue initializationmy-app/src/App.vue- Root componentmy-app/src/router.js- Router with authmy-app/src/MyApp.vue- Main component
Step 3: Update Build Configurations
vite.config.js - Add to apps array:
javascript1const apps = [ 2 'qrpay', 3 'my-app', // ADD HERE 4 // ... other apps 5]
build-apps.js - Add to apps array AND appThemes:
javascript1const apps = [ 2 'qrpay', 3 'my-app', // ADD HERE 4 // ... 5] 6 7const appThemes = { 8 // ... 9 'my-app': { 10 theme: '#3b82f6', // Primary color (hex) 11 bg: '#ffffff', // Background color 12 name: 'My App', // Display name 13 desc: 'App description' // PWA description 14 }, 15}
Step 4: Create Frappe WWW Files
custom_erp/www/my-app.html (placeholder - build will update):
html1<!DOCTYPE html> 2<html lang="en"> 3 <head> 4 <meta charset="UTF-8" /> 5 <link rel="icon" href="/assets/custom_erp/frontend/my-app/favicon.png" /> 6 <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" /> 7 <title>My App - Description</title> 8 <meta name="theme-color" content="#3b82f6" /> 9 <meta name="mobile-web-app-capable" content="yes" /> 10 <link rel="manifest" href="/api/method/custom_erp.api.pwa.get_manifest?app_name=my-app" /> 11 </head> 12 <body> 13 <div id="app"></div> 14 <script> 15 {% for key in boot %} 16 window["{{ key }}"] = {{ boot[key] | tojson }}; 17 {% endfor %} 18 </script> 19 </body> 20</html>
custom_erp/www/my_app.py (NOTE: underscored filename):
python1import frappe 2 3def get_context(context): 4 """Context for my-app""" 5 context.no_cache = 1 6 return context
Step 5: Create PWA Manifest
public/manifest-my-app.json:
json1{ 2 "id": "/my-app/", 3 "name": "My App", 4 "short_name": "MyApp", 5 "description": "App description", 6 "start_url": "/my-app/", 7 "scope": "/my-app/", 8 "display": "standalone", 9 "orientation": "portrait-primary", 10 "background_color": "#ffffff", 11 "theme_color": "#3b82f6", 12 "icons": [ 13 { 14 "src": "/assets/custom_erp/icons/my-app/icon-512x512.png", 15 "sizes": "512x512", 16 "type": "image/png", 17 "purpose": "any maskable" 18 } 19 ], 20 "categories": ["business", "finance"], 21 "prefer_related_applications": false 22}
Step 6: Add App Icon
bash1mkdir -p public/icons/my-app 2cp public/icons/qrpay/icon-512x512.png public/icons/my-app/
Or create a custom 512x512 PNG icon.
Testing & Deployment
Local Development
bash1cd frappe-bench/apps/custom_erp 2yarn dev 3# Access at http://localhost:8080/my-app
Build for Production
bash1cd frappe-bench/apps/custom_erp 2node build-apps.js
Commit & Push
bash1git add -A 2git commit -m "feat: add my-app Vue web application" 3git push origin main
Deploy to Server
bash1# On production server: 2cd ~/frappe-bench/apps/custom_erp 3git pull origin main 4node build-apps.js 5cd ~/frappe-bench 6bench build --app custom_erp 7bench restart
Checklist
Copy this checklist when creating a new app:
New Vue App: [APP_NAME]
Directory & Source Files:
- [ ] Created [app-name]/ directory
- [ ] Created [app-name]/index.html
- [ ] Created [app-name]/src/main.js
- [ ] Created [app-name]/src/App.vue
- [ ] Created [app-name]/src/router.js (base path: /[app-name])
- [ ] Created [app-name]/src/[AppName].vue
Build Configuration:
- [ ] Added to vite.config.js apps array
- [ ] Added to build-apps.js apps array
- [ ] Added theme config to build-apps.js appThemes
Frappe Files:
- [ ] Created custom_erp/www/[app-name].html
- [ ] Created custom_erp/www/[app_name].py (underscored!)
PWA Assets:
- [ ] Created public/manifest-[app-name].json
- [ ] Added icon to public/icons/[app-name]/icon-512x512.png
Testing:
- [ ] Tested locally with yarn dev
- [ ] Built with node build-apps.js
- [ ] Verified at /[app-name] route
Deployment:
- [ ] Committed and pushed
- [ ] Pulled on server
- [ ] Ran node build-apps.js on server
- [ ] Ran bench build --app custom_erp
- [ ] Ran bench restart
Common Issues & Solutions
404 Errors for Assets
Cause: Build output doesn't exist or wrong paths
Fix: Run node build-apps.js - it generates correct asset hashes
PWA Manifest 404
Cause: App not in build-apps.js or manifest not generated Fix: Add to build-apps.js apps array and rebuild
Login Redirect Loop
Cause: Wrong router base path
Fix: Ensure createWebHistory("/my-app") matches your URL
Python File Not Found
Cause: Wrong filename format
Fix: WWW Python files use underscores: my_app.py (not my-app.py)
Additional Resources
- See templates.md for complete file templates
- See examples.md for real app examples
- Reference existing apps:
qrpay/,pay-dashboard/,qrpay-horlicks/
