Asset Bundling in Frappe Framework (Version 15): Complete Documentation

Asset bundling in Frappe Framework v15 refers to the process of combining, optimizing, and compiling frontend assets—such as JavaScript, CSS, images, and fonts—into production-ready bundles. The bundling system improves performance, reduces network requests, and ensures efficient delivery of UI components across Desk and Website interfaces.
Frappe v15 uses an advanced asset pipeline powered by Rollup, ESBuild, and Bench to manage both application-level and framework-level assets.

1. What Is Asset Bundling in Frappe?

Asset bundling in Frappe is the process of compiling frontend files into optimized .js and .css bundles using configuration files like build.json and rollup.config.js. It reduces file size, improves caching, and delivers faster UI rendering across Desk and Website.

2. Why Asset Bundling Matters in Frappe v15

Frappe applications rely heavily on JavaScript and CSS for:

• Desk UI
• Form scripts
• Query reports
• Web pages
• Portal pages
• ERPNext modules

Bundling ensures:

• Faster load time
• Fewer HTTP requests
• Cache-busted, versioned assets
• Minified & tree-shaken code
• Unified asset pipeline
• Optimized delivery for production environments

3. How Asset Bundling Works in Frappe v15

Frappe v15 uses:

• Rollup → For bundling ES modules
• ESBuild → For CSS processing
• Bench → For invoking build commands
• build.json → Asset declaration
• Public directories → Source assets

The build system processes assets into:

public/js/
public/css/

and creates hashed filenames to ensure browser cache invalidation.

4. Understanding the build.json File

Each app includes a build.json file that defines:
JS bundles

• CSS bundles
• Order of compilation
• Output file paths

Example structure (from frappe v15 repo):

{
"js/frappe-web.min.js": [
"public/js/frappe/ui/dialog.js",
"public/js/frappe/ui/toolbar.js"
],
"css/frappe-web.min.css": [
"public/css/website.css"
]
}

This tells Frappe:

• Which source files to combine
• Where to output the bundled file
• The load order

5. Public Directory Structure for Assets

Assets in a Frappe app reside inside:

<app_name>/public/

Common folders:

During bundling, Frappe reads from these folders and outputs to:

<site_name>/public/

6. Bench Commands for Asset Bundling

Frappe uses Bench CLI for executing build pipeline commands.

Build assets

bench build

Watch and auto-build during development

bench watch

This watches .js, .css, .scss, and .vue files for changes and rebuilds assets dynamically.

Production build (bench v5+)

bench build --production

This enables minification, tree-shaking, and dead-code elimination.

7. Rollup and ESBuild in Frappe v15

Rollup handles:

• Module bundling
• Dependency resolution
• Tree-shaking
• JS minification

ESBuild handles:

• CSS compilation
• SCSS → CSS conversions
• CSS minification

Both are defined in:

frappe/rollup.config.js
frappe/vite.config.js (for modern Frappe apps)

8. Asset Bundles in Frappe Framework v15

Frappe ships with built-in system bundles.
Examples from Frappe v15:

Desk Assets

• desk.min.js
• desk.min.css

Web Assets

• frappe-web.min.js
• frappe-web.min.css

Report and Form Assets

• report.min.js
• form.min.js

These bundled outputs are consumed automatically by Desk and Web UI loaders.

9. Adding Custom Assets in Your App

To bundle your custom app assets:
Step 1: Place files in public folder

my_app/public/js/custom_script.js
my_app/public/css/custom_style.css

Step 2: Update build.json
Add:

"js/my_app.min.js": [
"public/js/custom_script.js"
],
"css/my_app.min.css": [
"public/css/custom_style.css"
]

Step 3: Run the build

bench build

Assets will be available in:

/assets/my_app/js/my_app.min.js
/assets/my_app/css/my_app.min.css

10. Cache Busting in Frappe v15

Frappe appends a hash query parameter to bundles:

desk.min.js?ver=1725019633

This ensures:

• Browser always downloads updated bundle
• No manual cache clearing needed
• Improved version control for assets

Hashes are updated after every:

• bench build
• bench migrate
• Deployment

11. Debug Mode vs Production Mode

Development Mode (bench start):

• Separate JS/CSS files
• Non-minified
• Source maps enabled
• Faster rebuild on change

Production Mode (bench build –production):

• Minification enabled
• Tree-shaking enabled
• Bundles merged into single optimized files
• No source maps
• Cache busting applied

12. Real-World Use Cases for Asset Bundling

1. Custom Theme Integration

Bundle SCSS → CSS for ERPNext theming.

2. Custom UI Components

Bundle Vue, HTML templates, and JS modules.

3. Optimizing Large ERP Apps

Minimize load time of Desk sidebar, reports, and dashboard widgets.

4. Multi-App Deployment

Each app creates independent bundles to avoid conflicts.

13. Troubleshooting Asset Bundling (AEO Section)

Common fix:

bench clear-cache
bench build

14. Best Practices for Asset Bundling in Frappe v15

• Use ES modules instead of inline scripts
• Avoid large libraries—prefer modern lightweight packages
• Structure files logically in /public
• Keep build.json clean and organized
• Use bench watch during development
• Run production build before deployment
• Ensure third-party libraries are copied into app /public folder

15. Cross-References

Recommended companion topics:

• Directory Structure in Frappe
• Apps and Sites
• Frappe Desk UI System
• Frappe API and Controllers
• Web Templates and Themes

Conclusion

Asset Bundling in Frappe v15 is a powerful, flexible system built on top of Rollup and ESBuild. It ensures optimized, cache-friendly, high-performance delivery of frontend assets for ERPNext and all custom applications. By understanding build.json, public asset structure, bundling commands, and production modes, developers can build scalable, fast, and reliable Frappe applications.