How to Create a Custom Theme in Frappe/ERPNext

ERPNext, built on the Frappe framework, is an incredibly versatile open-source ERP solution. While its core functionality addresses business needs right out of the box, the default UI may not always align with your brand identity or user experience goals.

That’s where custom theming comes in.

In this guide, we’ll walk you through the entire process of creating a custom theme in Frappe/ERPNext — from setting up your theme application, working with CSS, compiling assets, to tackling real-world challenges we’ve faced and solved.

📌 Why Create a Custom Theme?

Custom themes allow you to:

• Reflect your company’s branding and visual identity

• Improve usability by refining layouts, colors, and interactions

• Deliver a consistent UX across internal and external portals

• Stand out from other ERP implementations

🧰 Prerequisites

Before getting started, ensure you have:

• A running ERPNext instance (v13 or higher)

• Basic familiarity with the Frappe folder structure

• Terminal and filesystem access

• Experience with SCSS/CSS

• Node.js and Yarn installed (for asset compilation)

🚀 Step-by-Step Guide

1. Create a New Frappe App for Your Theme

Start by creating a new app that will host your theme:

Give your app a meaningful name like company_theme.

Then install it on your site:

2. Structure Your Theme Files

Navigate to your app’s public folder and create the CSS structure:

Inside theme.css, add your custom styles. For example:

3. Register Your Styles in hooks.py

Open your app’s hooks.py and add:

4. Configure build.json for CSS Compilation

Frappe uses a webpack-based build system to compile assets. Create a build.json file in your public directory:

This instructs Frappe to compile theme.css into custom_theme.css.

5. Build the Assets

To compile your theme CSS into usable CSS:

During development, you can use:

to auto-compile on file changes.

6. Activate the Theme on Your Site

You can either:

• Add it to site_config.json:

• Or run:
  

🧗 Common Challenges & How We Solved Them

🔄 Styles Not Reflecting

Issue: Changes in theme.css were not visible.
Cause: build.json was missing or outdated.
Fix: Createdbuild.json, ran bench build, cleared the cache and did a hard refresh (Ctrl+Shift+R).

⚠️ Styles Applied Only on Website, Not on Desk

Issue: Styles are applied to web pages but not the ERP UI.
Fix: Added both app_include_css and web_include_css in hooks.py.

🧪 Styles Not Reflecting in Development Mode

• Issue: Styles did not update during development.

• Cause: Developer mode was disabled.

• Fix: Enabled developer mode using the following command:

🚫 Theme Works Locally, Not on Production

Issue: Styles missing post-deployment.
Fix:

• Rebuilt assets using bench build --production

• Restarted services with bench restart

• Ensured the theme app is listed in apps.txt

💡 Pro Tips

• Use CSS variables for easy theming toggles.

• Create multiple themes (e.g., light, dark) and switch them using different CSS entry points.

• Use browser dev tools to inspect ERPNext’s DOM structure before overriding styles.

🧾 Final Thoughts

Creating a custom Frappe/ERPNext theme may seem daunting at first, but with the right structure, tools, and practices, it becomes a powerful way to align your ERP system with your organization’s brand and vision.

A clean, professional UI not only improves user experience but also builds trust and engagement among users.

📣 Join the Community

Have questions or want to share your theme? Join the conversation:

• Frappe Forum

• ERPNext GitHub

• Frappe Framework Docs