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
bash
1cd 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:
javascript
1const apps = [
2 'qrpay',
3 'my-app', // ADD HERE
4 // ... other apps
5]
build-apps.js - Add to apps array AND appThemes:
javascript
1const 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):
html
1<!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):
python
1import 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:
json
1{
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
bash
1mkdir -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
bash
1cd frappe-bench/apps/custom_erp
2yarn dev
3# Access at http://localhost:8080/my-app
Build for Production
bash
1cd frappe-bench/apps/custom_erp
2node build-apps.js
Commit & Push
bash
1git add -A
2git commit -m "feat: add my-app Vue web application"
3git push origin main
Deploy to Server
bash
1# 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/
