Find solutions to potential issues and answers to frequently asked questions
Installation
Why do errors appear when running npm’s install script?
If you run npm install and you encounter errors or the installation fails, you might be using an older version of Node.js that is incompatible with one or more of _tw’s dependencies.
Please check the latest LTS version of Node.js and install it if your version of Node.js is outdated.
Why do I encounter an error when uploading the theme to WordPress?
If you attempt to install your development theme by uploading it as a zip file in the WordPress administration area, you will receive the following error:
The package could not be installed. The theme is missing the style.css stylesheet.Code language: plaintext (plaintext)You must manually unzip and copy the development theme into your development environment’s wp-content/themes folder. Please see the installation instructions for details.
(However, the zip file generated by the npm run bundle command is suitable for uploading directly to WordPress to install on a staging or production server.)
Development
Why aren’t the Tailwind classes I added in the WordPress block editor working?
When Tailwind generates the CSS files for your theme, it only adds the classes present in your theme repository. This means that if you attempt to add arbitrary classes in the WordPress block editor, they’ll only work if they also appear in your theme. If you need to use classes in the block editor that don’t otherwise appear in your theme, you could do one of the following:
- Safelist classes in your Tailwind configuration file (if you know in advance what the classes will be)
- Use Twind’s shim module to translate Tailwind utility classes into CSS using JavaScript
Why isn’t Tailwind rebuilding my CSS files after I make changes?
If you’ve run npm run watch, but Tailwind isn’t rebuilding after you make changes either to CSS files in the ./tailwind folder or to PHP files in the ./theme folder, there are a number of possible culprits:
Errors during installation
If you’re setting up your project for the first time, please confirm there weren’t any installation errors that need to be resolved before proceeding further.
Working on a network drive or via Windows Subsystem for Linux
Tailwind’s process for monitoring files doesn’t work well (or at all) via network drives. This problem can often be resolved by changing the --watch flag to --poll for both Tailwind watch commands in your package.json file. This will cause Tailwind to check for changes to files on regular intervals rather than waiting for notifications that files have changed.
Unsupported characters in your project path
_tw uses the following glob pattern to match all of your theme’s PHP files:
./theme/**/*.phpCode language: plaintext (plaintext)When processing any glob pattern, certain characters in your path can cause the glob pattern not to expand as expected. I’ve specifically seen issues with parentheses in paths, but there are almost certainly other characters that could cause issues.
I generally recommend limiting the folder names in the path to your project to letters, numbers, underscores and hyphens.
Deployment
Why isn’t my automated deployment working?
Using npm run bundle, _tw is able to create a zip file containing your complete theme. However, if you need to deploy from your remote git repository, you’ll find that the repository itself doesn’t contain any of your theme’s generated CSS or JavaScript files.
If you’re using a tool like GitHub Actions, you may be able to run npm run prod as part of the action and then deploy the resulting ./theme folder, which will now contain all of the generated files you’ll need.
If this isn’t an option, you could simply remove the lines in your .gitignore file that correspond with the generated CSS and JavaScript files and begin committing them alongside the rest of your theme files.