Skip to content

Developer Guide

Jump to bottom
shabib-m edited this page Oct 26, 2026 · 1 revision

Developer Guide

This guide is intended for developers who want to modify the theme's source code, add new features, or customize the build process.

📦 Build Commands & Workflow

This theme uses Tailwind CSS v3 and relies on Node.js for compilation. All commands should be run from the root directory of the theme (themes/tailwindcss).

1. Install Dependencies

Before making any changes, install the required Node modules:

npm install
  1. Development Mode (Watch)

To actively develop the theme (e.g., adding new HTML classes or modifying the CSS), use the watch command. This will monitor your files and automatically recompile the CSS whenever you save a change.

npm run watch

This command generates an unminified CSS file at css/tailwindcss.css for easier debugging.

  1. Production Build (Minify)

When you are ready to deploy your changes to a live site, run the build command. This will generate a compressed, minified CSS file to ensure optimal performance.

npm run build

This command outputs the final CSS to css/tailwindcss.min.css. 🎨 Customizing Colors via Theme Settings

One of the most powerful features of this theme is the ability to add custom Tailwind classes directly from the Backdrop admin panel without touching any code.

How it works:

The theme settings page (admin/appearance/settings/tailwindcss) includes fields for:

Site Background

Header Background

Footer Background

📝Important Instructions for Developers:

You do not need to modify .tpl.php files to apply new colors. The PHP logic in template.php automatically reads these settings and injects the classes into the page.

Writing Classes: When entering classes in the settings fields, you can combine colors for Light and Dark modes.

Example: To set a white background that turns dark gray in Dark Mode, enter:

bg-white dark:bg-gray-900

Example: For a gradient background:

bg-gradient-to-b from-sky-100 to-white dark:bg-none dark:bg-gray-900

Tailwind's Scanner: Tailwind CSS scans your theme's files to generate the necessary CSS. When you type a class into the settings (which is saved in a JSON file), Tailwind's watch command will not see it immediately because it's not in a .tpl file.

⚠️ Adding New Classes (Safelist)

Because Tailwind doesn't read the database/JSON settings directly, any new class you add via the settings must be explicitly included in the build process. You have two options to do this:

Option A (Recommended): Use src/safelist.txt Add the new class (one per line) to the src/safelist.txt file. Tailwind will automatically scan this file and generate the CSS.

Example for src/safelist.txt:

bg-white
dark:bg-gray-900
bg-red-500

Option B: Use tailwind.config.js Alternatively, you can add the classes to the safelist array inside tailwind.config.js.

// Inside tailwind.config.js
module.exports = {
  // ...
  safelist: [
    'bg-white', 'dark:bg-gray-900',
    'bg-red-500', // <--- Add your new classes here
  ],
}

🔄 The Workflow for Adding New Colors:

Choose your preferred method: Add the new class to src/safelist.txt OR to tailwind.config.js.

Run npm run watch (or npm run build).

Go to the theme settings page in Backdrop, and use the new class in the appropriate field.

Save the settings. The class is now applied instantly to the site.

No .tpl file modifications are required!

Next Step: If you encounter any issues or have questions, please check the Issues page.

Clone this wiki locally