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.
Requires PHP 8.2 or newer, the JSON extension, and Composer. From your theme root:
composer require --dev italystrap/theme-json-generatorThe current package requires some development-branch dependencies. See installation for dependency stability, version selection, and global installation.
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 dumpThe 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.
- 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.phpentrypoints. - 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.
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.
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.
Copyright (c) 2021 Enea Overclokk, ItalyStrap. Licensed under the MIT license.