Theme JSON Compiler

Build WordPress theme.json by organizing your configuration files in a logical directory structure. The Theme JSON Compiler recursively merges JSON and JavaScript files into a single theme.json file.

What It Does

This tool takes a structured directory of Javascript or JSON files and compiles them into a single, unified theme.json file. Instead of maintaining one large JSON file, you can organize your theme configuration across multiple smaller files for better maintainability.

Key Features:

• 🗂️ Organize theme configuration in a logical directory structure
• 📦 Automatically compiles multiple JS/JSON files into a single theme.json
• 🔄 Recursively processes all subdirectories
• 💾 Use JavaScript to leverage variables, functions, and dynamic values instead of static JSON
• ⚙️ Works as a standalone Node.js script or as a Webpack plugin

Getting Started

Install the package:

npm install theme-json-compiler --save-dev

Integrate with Webpack:

// webpack.config.js
const { ThemeJsonCompiler } = require('theme-json-compiler');

module.exports = {
   plugins: [
      new ThemeJsonCompiler({
         dir: 'example/theme-json',
         output: 'theme.json',
      }),
   ],
};

Standalone Compiler:

const { compileJSON } = require('theme-json-compiler');
compileJSON({
   dir: 'example/theme-json',
   output: 'theme.json'
});

Directory Structure

Organize your files like this:

theme-json/
├── settings/
│   ├── _.js              # Spreads into parent level
│   ├── color.js
│   ├── layout.js
│   └── spacing/
│       ├── _.js
│       └── spacingSizes.js
└── styles/
    └── elements.js

This structure compiles to:

{
  "settings": {
    "appearanceTools": false,
    "useRootPaddingAwareAlignments": false,
    "color": { ... },
    "layout": { ... },
    "spacing": {
      "customSpacingSize": false,
      "spacingSizes": [ ... ]
    }
  },
  "styles": {
    "elements": { ... }
  }
}

Configuration

| Option | Description | Default | Type | |-----------|-------------------------------------------------------------|-------------------------------------------|----------| | dir | The relative directory path used to generate theme.json. | src/theme-json | string | | output | The output filename. | theme.json | string | | schema | The schema URL. | https://schemas.wp.org/trunk/theme.json | string | | version | The schema version. | 3 | number |

File Naming Rules

• Regular files (e.g., color.js): Becomes a key with that name (minus .js)
• Underscore files (e.g., _.js): Properties are spread into the parent object level
• Directories: Become nested keys in the output structure

Supported File Types

The compiler supports JavaScript and JSON files (.json, .js, ts).

// color.js
module.exports = {
  text: "var(--wp--custom--colors--site-foreground)",
  background: "var(--wp--custom--colors--site-background)"
};

Note: JavaScript files must export a valid object using module.exports.

This allows you to use dynamic values, import external configs, or leverage JavaScript logic in your theme configuration.