## What Is WordPlate? [WordPlate](https://github.com/vinkla/wordplate) is a Composer-managed WordPress boilerplate that brings modern PHP development practices to WordPress. Unlike a standard WordPress installation where you download a ZIP, edit `wp-config.php` by hand, and FTP files to a server, WordPlate treats WordPress as a dependency — just like any other PHP package. This means version-controlled configuration, environment-based settings via `.env` files, and a project structure that fits naturally into Git-based deployment workflows. If you have used [Bedrock](https://www.deployhq.com/guides/bedrock) (from the Roots ecosystem), WordPlate follows a similar philosophy but with a leaner setup and fewer opinions about your theme tooling. **Key differences from standard WordPress:** - **Composer-managed core and plugins** — WordPress itself is installed via `composer require`, not downloaded manually - **Environment configuration** — database credentials, salts, and site URLs live in `.env`, not `wp-config.php` - **Modern PHP** — requires PHP 8.1+ and uses `declare(strict_types=1)` throughout - **Vite for asset building** — replaces the older Laravel Mix setup with a faster, modern bundler - **Clean project root** — the WordPress installation lives inside `public/`, keeping your repository root free of WordPress core files --- ## Prerequisites Before starting, make sure you have the following installed: - **PHP 8.1 or higher** with common extensions (mbstring, xml, curl, mysql) - **Composer 2.x** — install from [getcomposer.org](https://getcomposer.org/download/) - **Node.js 18+** and npm — for Vite asset compilation - A **Git repository** (GitHub, GitLab, or Bitbucket) connected to your DeployHQ account --- ## Creating a WordPlate Project Create a new WordPlate project with Composer: ```bash composer create-project vinkla/wordplate your-project-name cd your-project-name ``` This scaffolds a complete WordPlate project with WordPress as a Composer dependency. ### Configuring Environment Variables Copy the example environment file and update it with your local database credentials: ```bash cp .env.example .env ``` Edit `.env` with your database details and site URL: ``` DB_NAME=wordplate_dev DB_USER=root DB_PASSWORD=secret DB_HOST=127.0.0.1 WP_ENV=development WP_HOME=http://localhost:8080 WP_SITEURL=${WP_HOME}/wordpress WP_PREFIX=wp_ ``` Generate secure WordPress salts: ```bash php artisan salts:generate ``` The `.env` file is excluded from version control by default. Each environment (local, staging, production) maintains its own `.env` with the correct credentials. This is critical for deployment — your production database password never touches your Git repository. --- ## WordPlate Project Structure Understanding the directory layout helps you configure deployments correctly: ``` your-project-name/ ├── public/ # Document root (point your web server here) │ ├── wordpress/ # WordPress core (Composer-managed, not committed) │ ├── themes/ # Your custom themes │ ├── plugins/ # Must-use and custom plugins │ └── uploads/ # Media uploads (excluded from Git) ├── config/ # WordPress configuration ├── vendor/ # Composer dependencies (not committed) ├── node_modules/ # Node dependencies (not committed) ├── vite.config.js # Vite build configuration ├── composer.json # PHP dependencies ├── package.json # Node.js dependencies └── .env # Environment config (not committed) ``` The `public/` directory is your web server's document root. This is an important distinction from standard WordPress where the document root is the project root itself. When configuring your server in DeployHQ, ensure your web server points to `public/`. --- ## Managing Plugins with Composer One of WordPlate's strongest advantages is managing WordPress plugins as Composer packages. This means plugins are version-locked in `composer.lock`, making deployments reproducible. WordPlate uses [WP Packages](https://wp-packages.org/) as a Composer repository. To install a plugin: ```bash composer require wp-plugin/advanced-custom-fields ``` To install a specific version: ```bash composer require wp-plugin/wordfence:^7.11 ``` WP Packages replaces the previous WPackagist repository — if you are upgrading an older WordPlate project, swap the `wpackagist-plugin/` and `wpackagist-theme/` prefixes for `wp-plugin/` and `wp-theme/` and run `composer update`. All plugin installations are tracked in `composer.json` and `composer.lock`. Never install plugins through the WordPress admin dashboard on production — it bypasses version control and will be overwritten on the next deployment. --- ## Asset Building with Vite WordPlate uses Vite for compiling front-end assets. During development: ```bash npm install npm run dev ``` For production-ready, minified assets: ```bash npm run build ``` The compiled output lands in your theme's build directory. These built assets must be generated during deployment — your repository should not contain compiled files. --- ## Deploying WordPlate with DeployHQ ### Step 1: Create a DeployHQ Project [Sign up for DeployHQ](https://www.deployhq.com/signup) if you have not already, then create a new project and connect your Git repository containing the WordPlate project. ### Step 2: Configure Your Server Add your production server connection (SSH or SFTP). Set the deployment path to the directory that serves your site. Remember that WordPlate's `public/` directory is the document root — your web server configuration (Apache or Nginx) should point to this subdirectory. ### Step 3: Set Up the Build Pipeline Create a `.deploybuild.yaml` file in your repository root to run Composer and Vite during each deployment. See the [.deploybuild.yaml documentation](https://www.deployhq.com/support/build-pipelines/deploybuild-dot-yaml) for full syntax details. ```yaml build: - composer install --no-dev --optimize-autoloader --no-interaction - npm ci - npm run build ``` The `--no-dev` flag skips development dependencies, and `--optimize-autoloader` generates a classmap for faster autoloading in production. Using `npm ci` instead of `npm install` ensures a clean, reproducible install from your lockfile. ### Step 4: Exclude Files from Deployment In your DeployHQ project settings, add these patterns to the excluded files list so development-only files are not uploaded to your server: ``` node_modules/ .env.example vite.config.js package.json package-lock.json tests/ ``` The `vendor/` directory and compiled assets are generated by the build pipeline and should be deployed. The `node_modules/` directory is only needed during the build step and should not be uploaded. ### Step 5: Configure Environment Files Use DeployHQ's [config files feature](https://www.deployhq.com/support) to manage your production `.env` file. Add a config file entry that deploys your production `.env` to the project root on the server. This keeps production credentials out of your repository while ensuring they are present on the server after each deployment. ### Step 6: Enable Zero-Downtime Deployments WordPlate projects benefit significantly from [zero-downtime deployments](https://www.deployhq.com/features/zero-downtime-deployments). Enable this in your DeployHQ server settings and configure shared paths for directories that must persist across releases: - **`public/uploads`** — media files uploaded through WordPress - **`.env`** — production environment configuration Without shared paths, every deployment would wipe uploaded media and require re-uploading the `.env` file. --- ## Database Management Between Environments WordPress stores content, settings, and site URLs in the database. When deploying WordPlate, keep these principles in mind: - **Never deploy the database** — code goes forward through Git and DeployHQ; content stays in each environment's database - **Use WP-CLI for migrations** — if you need to sync content between environments, export and import using `wp db export` and `wp db import` rather than copying raw SQL files - **Handle URL differences** — development uses `localhost`, production uses your live domain. After importing a database between environments, run `wp search-replace 'http://localhost:8080' 'https://yourdomain.com'` to update serialised URLs safely - **Run database updates post-deploy** — add a post-deployment SSH command in DeployHQ to trigger WordPress database updates when a WordPlate or plugin version bump requires schema changes: ```bash cd /path/to/your/project && wp core update-db ``` --- ## Troubleshooting Common WordPlate Deployment Issues **"Class not found" or autoloader errors after deployment** — The build pipeline may have failed silently, or `composer install` did not complete. Check your DeployHQ build logs. Ensure your build server has the correct PHP version (8.1+) and required extensions. **Blank page or 500 error on production** — Usually a missing `.env` file. Verify your DeployHQ config files are deploying `.env` to the correct path. Check that `WP_HOME` and `WP_SITEURL` match your production domain. **Uploads disappear after deployment** — You have not configured shared paths for `public/uploads`. Without this, each zero-downtime release creates a fresh directory. Add `public/uploads` as a shared path in your DeployHQ server settings. **Plugins installed via WordPress admin are lost on deploy** — This is expected. WordPlate manages plugins through Composer. Any plugin installed through the admin dashboard exists only on the server filesystem and will be overwritten on the next deployment. Always add plugins via `composer require` and commit the updated `composer.json` and `composer.lock`. **Vite build fails in the pipeline** — Check that Node.js 18+ is available in the build environment. Verify `package-lock.json` is committed to your repository — `npm ci` requires it. --- ## Next Steps With WordPlate and DeployHQ configured, every `git push` triggers a clean build and deployment. Your WordPress project benefits from version-controlled dependencies, reproducible builds, and zero-downtime releases. Explore more deployment [guides](https://www.deployhq.com/guides) for other frameworks, or check the [Bedrock guide](https://www.deployhq.com/guides/bedrock) if you are evaluating other modern WordPress stacks. Ready to automate your WordPlate deployments? [Start your free trial of DeployHQ](https://www.deployhq.com/signup). --- If you need help configuring your WordPlate deployment, reach out to our team at [support@deployhq.com](mailto:support@deployhq.com) or find us on [Twitter/X](https://x.com/deployhq).