Getting started

To get started with our child-theme, follow these instructions to quickly set up and utilize the theme’s capabilities.

The theme is a child theme of Blocksy. It uses Vite to bundle the assets, Blade for templating and Composer for the PHP dependencies.

It is already part of our default install on default.best4u.dev, which is the starting point for every new project — so in most cases the theme is simply there and you can skip straight to Setup. If you do have to add it to an existing site manually, place it in wp-content/themes as blocksy-child.

The directory name matters

The theme directory must be named blocksy-child. The Vite dev server URL is built from /wp-content/themes/blocksy-child/, so assets won’t load if it’s renamed.

Requirements

• Node.js — the version in the theme’s .nvmrc (currently v26.4.0). With nvm installed, run nvm use in the theme directory to switch to it.
• A package manager — npm (ships with Node.js) or pnpm.
• Composer
• PHP 8.2 or higher
• The Blocksy parent theme, installed and present in wp-content/themes/blocksy.

npm or pnpm?

The theme ships a package-lock.json, so npm is the default. pnpm works as a drop-in replacement and is noticeably faster — if you use it, commit the resulting pnpm-lock.yaml and remove package-lock.json so the project only ever has one lockfile. Never commit both.

Setup

Go to the theme directory and run these three commands. The order matters — see the note below.

npm

composer install # Installs the PHP dependencies
npm install      # Installs the node dependencies
npm run prod     # Builds the assets (CSS, JS, images)

pnpm

composer install # Installs the PHP dependencies
pnpm install     # Installs the node dependencies
pnpm prod        # Builds the assets (CSS, JS, images)

Both steps are required before activating the theme

• functions.php calls wp_die() when vendor/autoload.php is missing, so the theme will not load until composer install has run.
• The theme reads assets/public/.vite/manifest.json to resolve the built assets and throws a ManifestFileDoesNotExistException when it is absent, so you have to run a build (npm run prod / pnpm prod) at least once.

Starting development

When you want to start developing, just run the dev script. Vite will launch the development server on https://localhost:3334 and the theme will automatically include the files from the development server instead of the built assets.

npm

npm run dev

pnpm

pnpm dev

Note

The dev server is only used when the theme considers the environment local — that is when wp_get_environment_type() returns local, or the request comes from 127.0.0.1. See Environment Type for how to set this. On any other environment the theme always serves the built assets from assets/public/.

Development server SSL certificate

The browser could block the assets from being included because it doesn’t trust a self-signed certificate. If this occurs, you’ll have to access the asset through the browser itself (check the JavaScript console) and trust the certificate. You’ll only have to do this once.

Available scripts

Node scripts

Prefix these with npm run (or pnpm).

Script	What it does
dev	Starts the Vite development server on https://localhost:3334.
prod	Bundles/compiles the code and assets into assets/public/.
prod:watch	Same as prod, but rebuilds on every change.
lint	Read-only check: Biome CI (JS/TS/JSON formatting + linting) and Prettier for SCSS.
format	Fix mode: applies Biome formatting, lint fixes and import sorting, plus Prettier for SCSS.
typecheck	Runs TypeScript type checking (tsc --noEmit).

Composer scripts

Prefix these with composer.

Script	What it does
translate	Generates the translation file for the theme (wp i18n make-pot ., requires WP-CLI).
format	Formats the PHP codebase with Mago.
format:check	Checks the PHP formatting with Mago without writing changes.

Tip

There is no test framework in the theme. To verify a change, run lint, typecheck, composer format:check and make sure prod builds successfully.

Theme structure

Below is an overview of the key folders and files in the theme. While the theme contains additional files and directories, the ones listed here are the most relevant for development. It is recommended to modify only these unless you are certain about changes to other parts of the theme.

• Directoryapp/ PHP classes, PSR-4 autoloaded as Best4u\BlocksyChild\

  • App.php
  • Blade.php
  • Environment.php
  • Templates.php
  • Vite.php
  • helpers.php
  • …
• Directoryacf-json/ ACF Local JSON field groups

  • …
• Directoryassets

  • Directorysrc

    • Directorycss

      • Directoryabstracts/

        • …
      • Directorybase/

        • …
      • Directorycomponents/

        • …
      • Directorylayout/

        • …
      • Directorypages/

        • …
      • Directoryvendors/

        • …
      • backend.scss
      • frontend.scss
    • Directoryimages/

      • …
    • Directoryjs

      • backend.js
      • frontend.js
      • helpers.ts
  • Directorysvg/ used by the svg() helper and @svg directive

    • …
  • Directorypublic/ generated build output, gitignored

    • …
• Directoryblocks/ custom blocks (ACF/LazyBlocks/block.json)

  • …
• Directoryinc

  • enqueue.php
  • generate-blocks.php
  • hooks.php
  • shortcodes.php
• Directorypatterns/ block patterns

  • …
• Directorytemplates/ per-post-type block templates

  • …
• Directoryviews/ Blade templates

  • …
• Directoryviews-cache/ generated compiled Blade views, gitignored

  • …
• style.css
• functions.php
• composer.json
• package.json
• vite.config.js
• biome.json
• mago.toml
• tsconfig.json
• .nvmrc

Note

assets/public/ and views-cache/ are created automatically — never edit or commit them. patterns/ and templates/ aren’t there by default; create them when you need them.

Additional information

/app

Contains the theme’s PHP classes, autoloaded through Composer under the Best4u\BlocksyChild\ namespace. The wiring lives in App.php, which boots the Theme, Vite, Blade, Patterns and Templates classes, registers i18n, and then loads inc/ and blocks/.

functions.php is a bootstrap file only — don’t edit it, and don’t put CSS in style.css.

/inc

All files that do not start with an _ from this directory will automatically be loaded by the theme, including subdirectories. This is where you should put all your custom PHP code. No namespace or class is needed here; plain procedural PHP is fine.

It’s preferable to use a clear structure inside this folder. For example, when using different custom post types don’t use just one file, but structure it like this;

• Directoryinc

  • Directoryproject

    • post-type.php
    • archive.php
    • single.php
  • Directoryproduct

    • post-type.php
    • archive.php
    • single.php

/blocks

Use this folder for custom blocks. Any subdirectory containing a block.json is registered automatically with register_block_type(), recursively — this is what ACF blocks use. For those, a view.scss (frontend) or editor.scss (editor) in the block folder is glob-imported into the theme’s bundles by frontend.scss / backend.scss, so it does go through Vite and Sass.

LazyBlocks Pro

For LazyBlocks Pro, set the output method of the block to Theme Template. After choosing this option it tells you exactly what folder to create inside the blocks folder — the block slug with the / replaced by a -, so lazyblock/hero becomes blocks/lazyblock-hero/.

Inside that folder LazyBlocks picks up a fixed set of filenames on its own:

• Directoryblocks

  • Directorylazyblock-hero

    • block.php the template, used on the frontend and in the editor
    • editor.php optional — overrides block.php when rendering in the editor
    • block.css frontend styles
    • editor.css optional — styles loaded in the editor only
    • view.js optional — frontend script, loaded in the footer

Only block.php is required; the rest are optional and are simply skipped when the file isn’t there.

These are plain .css and .js — not .scss

LazyBlocks registers block.css, editor.css and view.js itself, as the block’s style, editor_style and view_script. They are served straight from disk and do not go through Vite or Sass, so you cannot use SCSS syntax, the breakpoint mixins or the @css/@img aliases in them. Anything that needs the build pipeline belongs in assets/src/css/ instead.

The upside is that they are only loaded on pages where the block is actually used, instead of ending up in the global bundle.

Note

LazyBlocks resolves these files with locate_template(), so the child theme takes precedence over Blocksy — always put them in blocksy-child/blocks/.

/patterns

Use this folder for creating patterns in the child-theme to be used in Gutenberg. Just add a .php file with the pattern name and inside this file add the following comment

/**
 * Title: Name of the pattern
 * Slug: best4u/name-of-the-pattern
 * Post Types: page, post
 * Categories: best4u
 */

Note

inc/hooks.php unregisters every automatically registered pattern (core, plugin and parent theme) and disables the remote pattern directory. Only the patterns in this folder and patterns created manually under Appearance → Patterns remain available.

/templates

Holds per-post-type block templates. They are synced to a post-type-templates custom post type so editors can maintain them in the block editor, and the content is written back to <slug>.html in this folder.

/views

Contains the Blade templates, compiled to views-cache/. Render them with the global view() helper. See Blade for the details.

Code style

Formatting is enforced by tooling, not by hand:

• PHP — Mago (mago.toml, PSR-12 preset, 4 spaces). Run composer format.
• JS, TS, JSON — Biome (biome.json): tabs, single quotes, no semicolons, line width 120.
• SCSS — Prettier (.prettierrc.json), because Biome doesn’t support SCSS yet. The lint and format scripts run both tools back to back.

See IDE for the recommended extensions that hook these up in your editor.

Working with an AI coding agent?

The theme ships an AGENTS.md at its root describing the architecture, commands and conventions, plus a skill in .agents/skills/ for scaffolding ACF blocks. Point your agent at it.