Introduction: The Nightmare of "Core Hacking"

Imagine this scenario: A manufacturing company has implemented ERPNext for two years. The system runs smoothly, with custom features added to meet their unique business needs. However, when the IT team tries to upgrade to the latest version of ERPNext, everything falls apart. The upgrade process fails completely, causing days of downtime and unexpected additional costs. The cause? The previous developer had directly modified core files in the apps/frappe or apps/erpnext folders, without considering the long-term impact.

A simple analogy: Modifying core code is like modifying a car's engine by welding the hood shut. The car still runs for a while, but when it's time for service or an upgrade, you can't open it without damaging the entire structure. As a result, the system becomes fragile, hard to maintain, and highly susceptible to bugs when new versions are released.

The best solution to avoid this nightmare is to adopt "The Frappe Way" extending features through Custom Apps. This approach ensures that your modifications remain isolated, allowing ERPNext version upgrades to be done seamlessly without conflicts.

Philosophy of "App-Based Architecture"

The Frappe Framework, which forms the foundation of ERPNext, is designed with a robust modular architecture. ERPNext itself is just one "App" running on top of Frappe, similar to a plugin in a CMS platform. This concept allows developers to build extensions without touching the core system, thus maintaining integrity and scalability.

The main goals of a Custom App are:

Code Isolation: Unique code tailored to the client's company needs is separated from standard ERPNext code. This avoids conflicts when Frappe or ERPNext releases updates.
Portability: The Custom App can be easily installed on another site or server, without having to redo configurations from scratch.
Version Control: By storing the app in a Git repository, every change can be tracked, reviewed, and reverted if necessary.

This architecture is similar to dependency injection in modern frameworks, where modules depend on each other without tight coupling.

source : https://docs.frappe.io/framework/user/en/basics/architecture

Technical Step 1: Initializing a Custom App

To get started, use the command line tool from Frappe Bench. Run the following command to create a new app:

bench new-app custom_app_name

This will generate a standard folder structure in the apps/custom_app_name directory. Its main contents include:

__init__.py: A boilerplate file for initializing the Python package.
hooks.py: The crucial file that acts as an event listener, connecting your app to events in ERPNext (to be discussed further).
public/: Directory for static files like custom JavaScript (JS) or CSS.
templates/: Place to store Jinja templates for custom print formats or reports.

After creation, install the app to your ERPNext site with:

bench --site site_name install-app custom_app_name

This structure ensures your app is ready for development without disrupting the core.

Technical Step 2: The Power of Hooks (Server-Side Logic)

Hooks are bridges that connect events in ERPNext to your custom logic, similar to event listeners in JavaScript frameworks. This allows code injection without core modifications, keeping the system immutable from an update perspective.

Real-world scenario: A retail client wants validation that a Sales Order cannot be submitted if the customer has overdue receivables. Without hooks, an amateur developer might edit the core Sales Order file a fatal mistake.

Implementation:

In your custom app's hooks.py file, add an entry in doc_events to listen for the validate event on the Sales Order doctype:

doc_events = {
    "Sales Order": {
        "validate": "custom_app_name.module.validate_sales_order"
    }
}

Then, create a Python function in a separate file (e.g., module.py):

import frappe

def validate_sales_order(doc, method):
    """Validate overdue receivables before submitting Sales Order.
    
    This ensures financial integrity by preventing new sales
    if there are arrears, without altering ERPNext core code.
    """
    outstanding = frappe.db.get_value("Accounts Receivable", 
                                      {"customer": doc.customer, "status": "Overdue"},
                                      "sum(amount)")
    if outstanding and outstanding > 0:
        frappe.throw("Customer has overdue receivables amounting to {}. Please settle first.".format(outstanding))

Why this approach? Because hooks ensure the function runs automatically every time the event is triggered (like when the Save button is pressed), without needing manual calls. It's also secure as it runs on the server-side, uncannily bypassable by users.

Technical Step 3: Client Scripts & UI Customization

Fundamental difference: Server Scripts (Python via hooks) focus on security, database validation, and crucial business logic. Meanwhile, Client Scripts (JavaScript) are intended for UI interactivity, such as auto-filling fields or hiding/showing elements based on conditions.

Best practice: Avoid placing sensitive business logic in Client Scripts, as they can be bypassed through APIs or browser consoles. Use JS only to enhance User Experience (UX), like automatic data fetching.

Example: Hide the "Discount" field if the user is not in the Manager role, or fetch the customer's address when the name field is filled.

In ERPNext, add Client Scripts via the UI (Customize > Client Script), or store them in the custom app for version control:

frappe.ui.form.on('Sales Order', {
    refresh: function(frm) {
        // Hide field based on role
        if (!frappe.user.has_role('Manager')) {
            frm.set_df_property('discount_percentage', 'hidden', 1);
        }
    },
    customer: function(frm) {
        // Auto-fetch address
        frappe.db.get_value('Customer', frm.doc.customer, 'address')
            .then(r => {
                frm.set_value('shipping_address', r.message.address);
            });
    }
});

Why is this effective? Because it improves UX without sacrificing security validation remains on the server.

source : https://docs.frappe.io/erpnext/user/manual/en/client-scripts

Configuration Management with Fixtures (Expert Level)

Many amateur developers struggle to move Custom Fields or configurations from dev to production. The pro solution: Use fixtures to export database schemas to JSON/CSV files.

In hooks.py, register fixtures:

fixtures = [
    {"dt": "Custom Field", "filters": [["module", "=", "Custom App Name"]]},
    "Property Setter",
]

Workflow:

Make changes in dev (e.g., add a Custom Field).
Export: bench export-fixtures.
Commit the files to the Git repository.
In production: bench migrate to apply changes.

This ensures consistency without hardcoding all changes are traceable and reversible.

Version Control & Deployment Workflow

Every line of code we write is stored in Git (GitHub/GitLab) for tracking. Avoid hardcoding fixed values; create a Settings DocType so users can change variables via the UI, without calling a programmer.

Release cycle (Git Flow):

Dev Branch: Local coding and testing.
Staging: User Acceptance Testing (UAT).
Production: Deploy stable code via merge to master.

source : https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow

Conclusion

Clean code is a long-term investment. Although setting up a Custom App takes a bit more time upfront, it will save hundreds of hours in future maintenance, especially during version upgrades.

Is your ERPNext system hard to update or frequently error-prone? There might be issues with its code structure. Our team is ready to perform a Code Audit and Refactoring to restore your system's health. Contact us now!

read to : ERPNext Part 1

#ERPNext #FrappeFramework #CustomAppDevelopment #ERPDevelopmentBestPractices #HooksInERPNext #ClientScripts #ServerScripts #ERPNextCustomization #OpenSourceERP #SoftwareDevelopment #VersionControlWithGit #ERPUpgradeTips #CustomFixtures #ScalableERP #BusinessSoftwareSolutions

References

Here is a list of key references used to inform the content of the article. These are drawn from reliable sources on ERPNext and Frappe development best practices:

https://docs.frappe.io/erpnext/user/manual/en/client-scripts
https://discuss.frappe.io/t/getting-issue-while-calling-method-throught-doc-event/131743
https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow