Skip to main content
Since 2024 we started preferring the Block theme instead of the Hybrid theme. You can still use the Hybrid theme if your project calls for it. The Hybrid theme and the Block theme are both based on the same principles and are designed to be used in the same way. The main difference is that one expects us to use Full Site Editing capabilities and the other does not. One uses .php files and the other does not.

​
Package.json scripts

CommandDescription
npm startThis will compile your files and will keep watching for changes.
npm run buildThis will compile your files for production.
npm run setupThis will install all the dependencies.
npm run resetThis will remove all the dependencies and install them again.
npm run cleanThis will remove all the files in the build folder.
npm run formatThis will format your files.
npm run lint:cssThis will lint your CSS files.
npm run lint:jsThis will lint your JS files.
npm run lint:phpThis will lint your PHP files.
npm run potThis will generate a .pot file for your theme.
npm run pot:jsonThis will generate a .json file for your theme.
npm run pot:moThis will generate a .mo file for your theme.
npm run packages-updateThis will update all the packages.
npm run test:playwrightThis will run the Playwright tests.
npm run test:playwright:helpThis will show the Playwright help.
npm run test:playwright:debugThis will run the Playwright tests in debug mode.
npm run styleguideThis will generate a styleguide based on your Tailwind CSS configuration.

​
TailwindCSS Configuration

Our TailwindCSS Configuration tracks the theme’s theme.json file for things like colors, font families, and font sizes. You can read more on how it works here. TailwindCSS is how we style our themes and blocks. Your theme’s TailwindCSS is configured to look for your block plugins by following a specific naming convention. By default the names we look for are {prefix}-blocks and {prefix}-blocks-blockName. This feature is not enabled by default because it causes issues when you don’t have a plugin with these names. You can go to your tailwind.config.js file and uncomment the line in the content array. It may look something like this: 
content = [
	...content,
	// `../../plugins/<%= prefix %>-block{s,s-*}/src/**/*.{php,html,js,jsx,ts,tsx}`,
];

​
TypeScript

We’ve introduced TypeScript to our stack and we encourage you to use it. You can learn more about the advantages and read more about it here.

​
Templates and parts

Block themes are a lot leaner than classic themes. You will build all your layouts using the editor. In order to keep things version controlled, after we are done making changes to a template or a template part we should copy the code and add to a file in the theme. There is a plugin to help with this. Just be careful to only use it to update the files you need and not all other files. Templates in block themes work the same as the templates from classic themes. You can add those to your theme templates/ folder and follow the same naming convention. Read more about theme hierarchy here. Here’s a very good resource to learn about block themes