README

Write WordPress theme.json configuration in PHP. Define settings, presets, and styles through a fluent API, share configuration between variations, and generate JSON during development or CI.

The package is experimental. These docs describe the current repository API; choose an installed version containing the features you need and review changes before upgrading.

Install

Requires PHP 8.2 or newer, the JSON extension, and Composer. From your theme root:

composer require --dev italystrap/theme-json-generator

The current package requires some development-branch dependencies. See installation for dependency stability, version selection, and global installation.

Generate your first configuration

Create theme.json.php in a theme containing style.css with a Theme Name: header:

<?php

use ItalyStrap\ThemeJsonGenerator\ThemeJson;

return static function (ThemeJson $themeJson): void {
    $themeJson->schema('https://schemas.wp.org/wp/6.6/theme.json');
    $themeJson->version(3);
    $themeJson->title('Example Theme');

    $themeJson->settings()->color()->addColor('primary', 'Primary', '#2457ab');
    $themeJson->settings()->typography()->addFontSize('body', 'Body', '1rem');

    $themeJson->styles()->color()->text('color.primary');
    $themeJson->styles()->typography()->fontSize('fontSize.body');
};

Choose a schema and format version for your target WordPress release. Then run:

vendor/bin/theme-json dump

The command writes theme.json beside the entrypoint, resolving preset keys to CSS variables. Edit PHP and regenerate; direct changes to generated JSON are overwritten. To import an existing theme.json into a PHP entrypoint, run init. For a complete walkthrough, follow the quick start.

What you can build

Configure editor controls, layout, typography, and reusable presets.
Apply global styles or target blocks, elements, states, and block style variations.
Organize configuration classes into ordered pipelines.
Generate variation JSON from styles/*.json.php entrypoints.
Add custom CSS or compile embedded SCSS into JSON.
Export SCSS references for use in a separate Sass build.
Start a customizable GitHub Actions generation workflow.

Generate JSON and assets before deployment. WordPress consumes the output; this generator does not need to run during production requests.

Documentation

Start at the documentation homepage, or open a topic directly:

Task	Guide
Understand inputs, outputs, and generation	Workflow
Configure settings and reusable values	Settings · Presets
Style a theme or block	Styles and scopes · Custom CSS
Split configuration into classes	Configurators · Autoloading
Add alternative theme styles	Style variation files
Work with generated references or palettes	SCSS export · Colors
Automate a build	Build integration · GitHub Actions
Look up a command or method	CLI · API
Upgrade or solve a problem	Migration · Troubleshooting

Prefer typed configuration APIs. For unsupported paths, use the root ThemeJson::set(), get(), and appendTo() methods with explicit array paths; string paths use Config dot notation. Root metadata methods such as schema(), version(), title(), and slug() are covered in the entrypoint guide. slug() is primarily for style variation metadata.

Contributing

See Contributing for development checks, source architecture, and documentation maintenance. For schema/API planning, make report/api-inventory generates Markdown and CSV reports in report/. See the inventory instructions to map schema paths to typed methods.

italystrap / theme-json-generator

Package info

Security

Statistics