Bedrock WordPress: What It Is, Who It's For and How to Migrate

Bedrock is a WordPress boilerplate from Roots that treats a WordPress site like a modern software project. WordPress core and plugins are installed with Composer, settings live in environment files, and the folder layout keeps secrets out of the public web folder. It suits sites with a development team, a Git workflow and more than one environment. It is overkill for a small brochure site that one person updates from the dashboard.

This guide explains what Bedrock is, who it makes sense for, the honest pros and cons, and the problems that come up when you move an existing site onto it.

What Bedrock is

Standard WordPress is installed by copying files to a server and updating them from the admin. Bedrock replaces that with three ideas.

1. Composer manages WordPress and plugins

Composer is the standard dependency manager for PHP. In Bedrock, WordPress core, plugins and themes are listed in a composer.json file with their versions, and Composer installs them. Free plugins from the WordPress.org directory come from WP Packages, a repository Roots runs, under the wp-plugin/ prefix:

composer require wp-plugin/wordpress-seo

Bedrock’s Composer documentation covers the details. Older Bedrock projects use WPackagist and a wpackagist-plugin/ prefix instead.

The result is that the exact version of everything is recorded in Git. Every environment gets the same code, and you can roll back an update by reverting a commit.

2. Configuration lives in environment files

Instead of a hand-edited wp-config.php, Bedrock reads database details, site URLs and security keys from a .env file. That file is different on each server and never committed to Git. A variable called WP_ENV tells the site whether it is running in development, staging or production. Each environment can have its own settings file. For example, staging tells search engines not to index the site.

3. A different folder structure

The server’s document root points at the web/ folder. Configuration, Composer’s vendor/ folder and the .env file sit one level above it, where a browser cannot reach them.

Bedrock also ships with safer defaults. In production it disables the theme and plugin file editor and blocks installing or updating plugins from the admin. It also turns off WordPress’s automatic updater. The installation guide lists current requirements. At the time of writing, that is PHP 8.3 or later and Composer.

Who Bedrock makes sense for

Bedrock pays off when the way you build and change the site matters as much as the site itself:

• Sites with a development team or an agency making regular code changes.
• Sites with custom plugins or themes that you want versioned, reviewed and tested.
• Businesses that need local, staging and production environments that match each other.
• Teams using continuous integration and deployment (CI/CD), where every change goes through a pull request and an automated deployment. See our guide to WordPress CI/CD with GitHub Actions.
• Agencies running many similar sites, where a shared, repeatable setup saves time.
• Sites with compliance or security requirements, where locking down production and recording every change is useful.

When it is not worth it

• A small site that one person manages from the dashboard. If nobody on the team uses Git or the command line, Bedrock adds steps without adding value.
• Hosts that cannot support it. Some managed WordPress hosts do not let you change the document root or run Composer, and they expect the standard layout.
• Teams that rely on installing plugins from the admin. Bedrock deliberately stops that in production. If that habit cannot change, the setup will fight you.

Pros and cons

The last con matters most. Bedrock turns off automatic updates, so a Bedrock site with nobody running composer update gets out of date quietly. That is technical debt building up, which we explain in how to measure WordPress technical debt. The usual fix is a bot such as Dependabot or Renovate that opens a pull request when a new version is available, plus automated tests that run on it.

What makes migrating to Bedrock hard

Moving a new, empty site onto Bedrock is easy. Moving a live site with years of content and plugins is where the work is. These are the problems we plan for.

Hosting and deployment

The host must point the document root at web/ and either run composer install on deployment or accept a build that already includes the vendor/ folder. Confirm this before anything else. If the current host cannot do it, the migration becomes a host move too. See how to change WordPress hosts with zero downtime.

Turning every plugin into a Composer package

Each plugin needs a source Composer can install from:

• Free plugins come from WP Packages with the wp-plugin/ prefix.
• Some premium plugins have their own Composer repository. Advanced Custom Fields (ACF) Pro, for example, installs with Composer using your license key in an auth.json file that stays out of Git.
• Other premium plugins need a private Git repository or a private package server. Roots lists options such as SatisPress and Private Packagist in its guide to commercial plugins.
• Custom plugins and the theme move into your own repository.

Expect a few plugins with no clean source, such as an old premium plugin with an expired license. Those need a decision: renew, replace or remove. This step is a good time for a cleanup, because each plugin now has to justify its place.

Upload URLs change from wp-content to app

Every image and file link stored in your posts points to /wp-content/uploads/. After the move, files live at /app/uploads/. You have two options.

Option 1: keep the old path. Bedrock defines the content folder in one constant, CONTENT_DIR. You can set it back to /wp-content, rename the folder and update the install paths in composer.json to match, so no URL changes. This is the lowest-risk choice for sites with a lot of search traffic to images and documents.

Option 2: change the path properly. Update the database with WP-CLI, which handles serialized data safely, and always run a dry run first:

wp search-replace '/wp-content/uploads/' '/app/uploads/' --all-tables --dry-run

Then add permanent redirects so old links from other sites, emails and image search still work. On nginx:

rewrite ^/wp-content/uploads/(.*)$ /app/uploads/$1 permanent;

On Apache:

RedirectMatch 301 ^/wp-content/uploads/(.*)$ /app/uploads/$1

Our WordPress migration SEO checklist covers redirects and search checks in more depth.

Hardcoded paths in themes and plugins

Older themes and custom code often assume WordPress lives in the web root. Look for code that builds paths with wp-content or wp-includes written out as text, scripts that load wp-load.php from a fixed location, and assets linked with relative paths. These break quietly, often on a page nobody checks on launch day. Search the codebase for these patterns, and use WordPress functions such as content_url() and plugins_url() instead.

The admin URL moves

The dashboard moves to /wp/wp-admin/. Editors’ bookmarks, password managers and documentation need updating. Security plugins that hide or rename the login page, and firewall rules that protect /wp-admin/, need to be checked and updated too.

Configuration that lived in wp-config.php

Custom constants in the old wp-config.php move into config/application.php, an environment file or .env. Pay attention to the security keys and salts. If you copy the existing values into .env, users stay logged in. If you generate new ones, everyone is logged out, which can be a good thing after a security incident but should be planned.

Multisite networks

Bedrock supports multisite, but it needs extra configuration so that site URLs work with core living in /wp/. Test logins, domain mapping and media for each site in the network before launch. See WordPress multisite migration for the wider issues.

A new way of working

This is the difficulty people underestimate. After the move, nobody can install or update a plugin on production from the dashboard. That is the point, but it surprises site owners and marketing teams. Agree who requests plugins, who updates them and how often, and how releases are tested. Without that agreement, someone will eventually look for a way around the lock.

How we migrate a site to Bedrock

1. Assess. We list every plugin, custom code path, integration and server requirement, and confirm the host can support Bedrock.
2. Build the project. We create the Bedrock repository, map each plugin to a Composer source and move custom code into version control.
3. Rehearse locally and on staging. We import the content into Docker environments, run the search-replace, fix hardcoded paths and test forms, checkout, logins and media.
4. Set up deployment. Composer installs on build, environment files go on each server, and updates arrive as pull requests that run automated tests. Our guide to automated testing with Playwright and PHPUnit explains the tests.
5. Cut over. We freeze content briefly, run the final sync and switch at a low-traffic time.
6. Verify and hand over. We check redirects, logs and search reports, and document how updates and releases now work.

Planning a move to Bedrock?

Bedrock migrations are part of our WordPress migration service. If your host cannot support it, our server setup and management team can prepare one that does. Contact us with your site address and what you want to get out of the move, and we will tell you whether Bedrock is the right fit.

Frequently asked questions

What is Bedrock WordPress?

Bedrock is a free, open-source WordPress boilerplate from Roots. It installs WordPress core and plugins with Composer, keeps settings and secrets in environment files instead of wp-config.php, and uses a folder structure that keeps configuration and code outside the public web folder.

Is Bedrock still WordPress?

Yes. The admin, the database, themes and plugins all work as usual. Bedrock changes how WordPress is installed, configured and deployed, not how editors use it.

Can I install plugins from the WordPress admin on a Bedrock site?

Not in production by default. Bedrock turns off plugin and theme installs and updates in the admin outside development. Plugins are added with Composer and released through your deployment process.

Will moving to Bedrock break my image URLs?

It can. Bedrock moves wp-content to /app, so upload URLs change from /wp-content/uploads/ to /app/uploads/. A proper migration updates the database and adds 301 redirects, or keeps the old content path so nothing changes.

Does every host support Bedrock?

No. The host must let you point the document root at Bedrock's web folder and run Composer during deployment, or accept a build that already includes it. Check this before you start.