Start Project
Make sure Docker is running before you start. WordPressify automatically checks for Docker and will show a clear error message if it is not active.
File Structure
src/theme/- Block theme files (HTML templates,theme.json, PHP).src/plugins/- Custom WordPress plugins.src/assets/css/- CSS stylesheets.src/assets/fonts/- Font files.src/assets/img/- Image assets.src/assets/js/- JavaScript files.
Configuration files, Docker files, and build scripts live in the project root.
Change Theme Name
Rename .env_example to .env to customize your settings. Both variables have sensible defaults, so the .env file is optional if you are happy with the defaults:
# If you want to connect to BrowserSync on a different port. Default: 3010
PROXY_PORT=3010
# Theme name. Default: "wordpressify"
THEME_NAME=wordpressifyThis name is used for the theme directory in WordPress and in the exported zip file.
Start Workflow
npm run startIf Node.js is not installed locally, use Docker directly:
docker compose upOnce the containers are up, your site is available at:
- http://localhost:3010 - Development site with live reload (BrowserSync proxy, port configurable via
PROXY_PORT). - http://localhost:8080 - Direct nginx access, without live reload.
- http://localhost:3001 - BrowserSync UI, for debugging the proxy.
To rebuild with a fresh WordPress installation and clean database:
npm run rebuildWithout local Node.js:
docker compose down -v && docker compose buildPlace custom plugins in the src/plugins/ directory. They are automatically copied into the WordPress plugins folder during the build.
Generate optimized distribution files:
npm run exportWithout local Node.js:
docker compose run --rm nodejs npm run prodThe theme is saved as a zip file in dist/wordpressify.zip.
All Commands
| Command | Description |
|---|---|
npm run start | Start the development server (docker compose up). |
npm run build | Rebuild the Docker images. Required after changing gulpfile.js or package.json. |
npm run rebuild | Tear down containers and volumes, then rebuild. Gives you a fresh WordPress install and clean database. |
npm run delete | Remove containers and volumes (docker compose down -v). Deletes the database. |
npm run export | Build production distribution files into dist/. |
npm run export:backup | Zip the entire build/ directory (full WordPress install) into backups/<date>.zip. |
npm run lintcss | Lint CSS files in src/ with Stylelint. |
Every command that talks to Docker first checks that the Docker daemon is running and prints a clear error if it is not.
Code Formatting and Linting
The project ships with pre-configured code quality tools:
- Prettier (
.prettierrc) - Formats HTML, JavaScript, and CSS (2-space indent, double quotes, 80 character line width). - PHP CS Fixer (
.php-cs-fixer.php) - Enforces consistent PHP code style. - Stylelint (
.stylelintrc) - Lints CSS. Run it withnpm run lintcss.
Debugging with Xdebug
The WordPress container ships with Xdebug installed and configured (config/php.ini), listening on port 9003. Profiler and trace output, the Xdebug log, and the WordPress error log (wp-errors.log) are written to the xdebug/ directory in your project root.