Sage Child Theme

Warning

This is not yet an officially recommended project and is strictly for testing purposes at this time. See roots/docs#450 for background and discussion.

A minimal WordPress child theme for Sage.

Installation

1. Clone or copy this theme into your themes directory alongside Sage
2. Run composer install from the child theme directory
3. Run npm install from the child theme directory
4. Build the child theme assets
5. Activate the child theme from the WordPress admin

composer install

npm install

npm run build

How it works

• WordPress loads both functions.php files — child first, then parent
• The child's functions.php registers its own Composer autoloader
• The parent's functions.php boots Acorn as usual
• Acorn's view config automatically searches both child and parent resources/views/ directories, so any Blade view you add to the child theme will override the parent's version
• The parent's view composers are registered via an after_setup_theme hook in the child's functions.php, since Acorn's auto-discovery only scans the child theme directory

Assets

The child theme has its own Vite build, separate from the parent theme. Both builds run independently and output to different directories:

• Parent: /app/themes/sage/public/build/
• Child: /app/themes/sage-child/public/build/

The parent's assets are loaded via @vite() in layouts/app.blade.php. The child's assets are enqueued via wp_enqueue_style and wp_enqueue_script in functions.php, which reads the child's Vite manifest to resolve hashed filenames. The child's assets load after the parent's, so child styles naturally take precedence.

Add your CSS to resources/css/app.css and JS to resources/js/app.js.

Note: The child's assets are enqueued by reading the Vite manifest, so npm run dev alone won't hot-reload child assets. Run npm run build after making changes, or modify the enqueue logic to support Vite's dev server.

theme.json

The child theme has its own theme.json which is processed by the wordpressThemeJson Vite plugin during build. This is required because Acorn's public_path() resolves to the child theme directory, so the parent's setup.php filter for theme.json will look for the built file in the child's public/build/assets/ directory.

Edit theme.json in the child theme root to customize block editor settings (content width, spacing, colors, etc.), then rebuild.

Editor assets

The child theme must include resources/css/editor.css and resources/js/editor.js entrypoints. The parent's setup.php loads these via the Vite facade, which reads the child's manifest. Without these entries in the child's manifest, the block editor will throw a ViteException.

Overriding views

Add a Blade view to resources/views/ using the same path as the parent theme. For example, to override the footer:

resources/views/sections/footer.blade.php

The child theme's view will be used instead of the parent's.

Adding view composers

Create composers in app/View/Composers/ just like you would in Sage. Acorn auto-discovers composers in the child theme directory, so they work out of the box.

After adding a new composer, regenerate the autoloader:

composer dump-autoload

Note: Overriding a parent composer by creating a child composer with the same class name is not supported. Both themes share the App\ namespace and the resulting behavior is undefined.

Important constraints

• Do not create app/setup.php or app/filters.php in the child theme. The parent's functions.php uses locate_template() to load these files, which checks the child theme first. If these files exist in the child, they will replace (not extend) the parent's versions.