Frappe Builder Documentation

To deploy a production-ready instance of Frappe Builder, use the easy-install.py script. This process sets up the necessary configurations in approximately 5 minutes.

1. Download the installation script:

   wget https://frappe.io/easy-install.py

2. Run the deployment command with your specific parameters:

   python3 ./easy-install.py deploy \
       --project=builder_prod_setup \
       --email=email@example.com \
       --image=ghcr.io/frappe/builder \
       --version=stable \
       --app=builder \
       --sitename subdomain.domain.tld

Parameters:

• --email: Your contact email address.
• --sitename: The domain name where Builder will be hosted (e.g., subdomain.domain.tld).
• --image: Use ghcr.io/frappe/builder.
• --version: Use stable for production.
• --app: Use builder.

If you are contributing to or customizing the Builder frontend, follow these steps to run the Vite development server:

1. Navigate to the builder app directory:

   cd frappe-bench/apps/builder

2. Install dependencies and start the dev server:

   yarn install
   yarn dev --host

3. The frontend will be available at http://builder.localhost:8080.

Note: All frontend source code is located in frappe-bench/apps/builder/frontend.

For a quick development environment using Docker, ensure you have docker, docker-compose, and git installed.

1. Create a directory and download the required configuration files:

   mkdir frappe-builder && cd frappe-builder
   wget -O docker-compose.yml https://raw.githubusercontent.com/frappe/builder/develop/docker/docker-compose.yml
   wget -O init.sh https://raw.githubusercontent.com/frappe/builder/develop/docker/init.sh

2. Start the containers:

   docker compose up

Wait for the terminal to indicate Current Site set to builder.localhost.

Access Details:

• URL: http://builder.localhost:8000
• Username: Administrator
• Password: admin

To install Frappe Builder into an existing frappe-bench environment:

1. Start your bench: bench start.
2. In a new terminal, within the frappe-bench directory, run:

   bench get-app builder
   bench new-site builder.localhost --install-app builder
   bench browse builder.localhost --user Administrator
   bench --site builder.localhost set-config ignore_csrf 1

   Note: ignore_csrf 1 is required to prevent CSRFToken errors when using the Vite dev server.
3. Access the builder at builder.localhost:8000/builder.

A template group is a collection of highly-functional pages (e.g., landing, contact) that share a common set of Builder Components and Builder Variables.

Filesystem Structure

Template groups are stored in builder/builder_templates/<group>/:

• template.json: The UI manifest containing title, description, preview, and page order.
• pages/<page>/<page>.json: Page configuration.
• components/<component_id>/<component_id>.json: Shared component configuration.
• variables/<uuid>/<uuid>.json: Shared variables.
• client_scripts/<name>/<name>.json: Client-side scripts.
• fonts/<name>/<name>.json: Font configurations.

Asset Management

Group assets (images, page previews, font files) are committed to builder/www/builder_assets/<group>/ and served at the public route /builder_assets/<group>/.

The Block class is the fundamental building block of the Frappe Builder. It represents an element in the document tree and manages its own styles, attributes, children, and component relationships.

Key properties include:

• blockId: A unique identifier for the block.
• element: The HTML tag name (e.g., div, section, img).
• baseStyles, mobileStyles, tabletStyles: Responsive style maps for different breakpoints.
• attributes: A map of HTML attributes.
• children: An array of child Block instances.
• extendedFromComponent: If set, this block inherits properties and structure from a reusable component.
• isRepeaterBlock: Indicates if the block is part of a repeater pattern.
• visibilityCondition: Logic determining when the block should be visible.
• props: A collection of properties used for data binding or component configuration.

You can run Frappe Builder locally using the provided docker-compose.yml file. This setup orchestrates three main services: frappe (the application), mariadb (the database), and redis (the cache/broker).

To use this configuration, ensure you have Docker and Docker Compose installed, then run:

docker-compose up

Use the scheduler_events hook to define cron jobs. Frappe Builder uses these to ingest analytics data into DuckDB.

Example configuration for running tasks every 10 minutes:

scheduler_events = {
	"cron": {
		"*/10 * * * *": [
			"builder.builder_analytics.ingest_web_page_views_to_duckdb",
			"builder.builder_analytics.ingest_clicks_to_duckdb",
		],
	},
}

You can hook into specific DocType lifecycle events using doc_events. This allows you to execute logic after certain actions occur on a document.

Example: Capturing a user invitation after it is inserted into the 'User Invitation' DocType.

doc_events = {
	"User Invitation": {
		"after_insert": "builder.user_invitation.capture_user_invited",
	}
}

The reset stylesheet is used for published Builder pages to ensure consistent rendering of native form controls and base font rules. It is built using npm run build:reset.

Unlike the standard frappe-ui preset, this configuration avoids dumping the entire design-token set (e.g., --surface-*, --ink-*) into :root to keep the file size small, as published pages use inline styles rather than frappe-ui components. However, it retains core Tailwind plugins to ensure necessary CSS variables (like --tw-ring-* and --tw-shadow) are available for @tailwindcss/forms focus styles.

import forms from "@tailwindcss/forms";

export default {
	content: ["./src/reset.css"],
	plugins: [forms],
};

To make the Builder application visible in the Frappe Apps screen, use the add_to_apps_screen list. This requires providing the app name, a logo path, a title, a route, and a permission check function.

add_to_apps_screen = [
	{
		"name": "builder",
		"logo": "/assets/builder/frontend/builder_logo.png",
		"title": "Builder",
		"route": f"/{builder_path}",
		"has_permission": "builder.api.check_app_permission",
	}
]

When running via Docker Compose, the frappe service exposes the following ports on your host machine:

• 8000: Primary application port
• 9000: Secondary service port
• 8080: Alternative service port