Create Custom Fields During App Installation in Frappe Framework (v15)

Introduction: Why Create Custom Fields During App Installation?

Creating Custom Fields during app installation ensures that required schema changes are applied automatically when an app is installed on a site.
In Frappe Framework v15, this approach guarantees consistency across environments without manual configuration.

What Are Custom Fields in Frappe?

Custom Fields are user-defined fields added to existing DocTypes without modifying core code.
They are stored as records in the Custom Field DocType and are fully upgrade-safe.

Why Create Custom Fields via App Installation?

You should create Custom Fields during installation when:

• Your app depends on additional fields
• You want zero manual setup for users
• You are distributing reusable ERPNext apps
• You need repeatable deployments across sites

This is the recommended approach for production apps.

Technical Prerequisites

Before proceeding, ensure:

• Frappe Framework v15 is installed
• A custom app exists
• You have access to the app directory
• Bench and site are properly configured

How Does Frappe Create Custom Fields Automatically?

Frappe uses fixtures and hooks to export and re-create Custom Fields during app installation.

Step-by-Step: Create Custom Fields During App Installation

Step 1: Create Custom Fields Manually (Once)

First, create the required Custom Fields using the UI:

• Go to Customize Form
• Select the target DocType
• Add required fields
• Save the form

These fields are stored in the Custom Field DocType

Step 2: Export Custom Fields as Fixtures

In your app, edit hooks.py:

fixtures = [
{
"dt": "Custom Field",
"filters": [
["name", "in", [
"Sales Invoice-custom_reference",
"Customer-custom_rating"
]]
]
}
]

This ensures only selected Custom Fields are exported.

Step 3: Install or Migrate the App

Run the following command:

bench --site yoursite install-app your_app

or, if already installed:

bench --site yoursite migrate

Frappe automatically inserts the Custom Fields during installation or migration.

Where Are Custom Fields Stored?

In Frappe v15:

• Custom Fields are stored in the Custom Field DocType
• Metadata is synced during migrations
• Fields are applied at runtime without schema changes

How Frappe Applies Custom Fields Internally

During installation or migration, Frappe:

1. Loads fixture definitions
2. Inserts or updates Custom Field records
3. Clears metadata cache
4. Refreshes DocType schema

This process ensures fields appear immediately in the UI.

Best Practices for Custom Fields in Apps

• Always use fixtures, not patch scripts
• Export only required fields
• Avoid modifying core DocTypes directly
• Use meaningful fieldnames with app prefixes
• Test installation on a fresh site

Common Mistakes to Avoid

Exporting All Custom Fields

This can cause conflicts across apps.

Fix:

Always filter fields explicitly.

Editing Custom Fields After Export

Changes won’t sync automatically.
Fix:

Re-export fixtures after updates.

Using Database Schema Changes

Custom Fields do not require migrations.

Fix:

Rely on Frappe’s metadata system.

Advanced Usage: Conditional Custom Fields

You can control visibility using Depends On expressions:

eval:doc.customer_type == "Company"

This logic is fully supported in Frappe v15.

Integration Patterns

Creating Custom Fields during installation is commonly used in:

• ERPNext industry apps
• Accounting extensions
• Manufacturing customizations
• CRM enhancements

Target Audience

• Frappe Developers
• ERPNext Consultants
• App Developers
• System Integrators

Industry Relevance

This approach is critical in:

• Multi-site ERP deployments
• SaaS ERP platforms
• Managed ERPNext services
• Enterprise custom solutions

Summary: Automating Custom Fields the Right Way

In Frappe Framework v15, creating Custom Fields during app installation using fixtures is the safest, cleanest, and most maintainable approach.
It ensures consistency, avoids manual errors, and keeps your app upgrade-safe.