Open-source project
roots/bedrock avatar
roots/bedrock

Bedrock keeps WordPress core in Composer and splits configuration per environment

WordPress boilerplate with Composer and Git, easier configuration, and an improved folder structure

6,591 stars1,169 forksPHPMIT

At a glance

What is it?
Bedrock is a MIT-licensed WordPress boilerplate that pulls core through Composer, keeps per-environment settings in config/, and loads environment variables from an example file. It hands the install step off to its own documentation rather than shipping the command that creates the project.
Who is it for?
Bedrock is the right base when a project has more than one environment and more than one developer, because its whole contribution is moving WordPress core, credentials and site addresses out of files people edit by hand and into Composer plus environment specific config files. It is the wrong base for a single site with one operator, where that separation buys nothing and the mu-plugins autoloader only removes your ability to switch a plugin off from the admin.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 14 days ago.
What is it written in?
Mainly PHP, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • roots/bedrock6,591 ★ · +18
Star history
Repository2026-09-232026-11-15
roots/bedrock6.6k6.6k

18 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

Tag 1.31.6 carries WordPress 7.1.2, not the other way round

Bedrock's release names are not free-floating. Each tag states which WordPress core version it was built against: 1.31.8 carries WordPress 7.1.4 and was published on 2026-10-28, 1.31.7 carries 7.1.3 from 2026-10-06, and 1.31.6 carries 7.1.2 from 2026-09-22.

That gives a Bedrock maintainer a fixed rule for when to cut a release. Three core patch numbers, three Bedrock patch numbers, one per core patch. The default branch is master and the last push to it was on 2026-11-01, so the trunk keeps moving between those tags rather than sitting still until the next one.

The naming also answers a question that a bare version string would not. When someone reports a defect, the tag in their composer.lock already answers what core they were on, without a second lookup. What the README does not say is how long a given tag stays current, whether two Bedrock releases can point at the same core patch, or what a project should do when core moves ahead of the tag it is pinned to.

Core arrives through Composer while web/ stays the document root

The central move is that WordPress core stops being a folder you download and paste. It becomes a dependency: a composer.json sits at the top level, the core package is roots/wordpress, and plugins and themes come from the WP Packages repository.

The tree above that matches. It is short enough to read in one pass, and it contains .devcontainer/, .editorconfig, .env.example, .gitattributes, .github/, .gitignore, LICENSE.md, README.md, composer.json, config/, phpunit.xml.dist, pint.json, tests/, web/ and wp-cli.yml. Only one entry, web/, is a candidate for a document root, so the improved folder structure the description refers to is a single web root next to a config directory rather than a scatter of directories.

Three of those files are development machinery rather than application code: phpunit.xml.dist for the test suite that tests/ holds, pint.json for code style, and .devcontainer/ for an editor environment.

The gap is that nothing in the repository explains the arrangement. The overview promises a better folder structure without saying what belongs where, and no file in the tree documents the boundary between code that ships and code that belongs to the project.

One DSN or four variables, with a comment about mysqli 2002

The example environment file offers two ways to describe the database, and it is unusually candid about the failure each one fixes.

The default is three required values plus an optional host:

bash
DB_NAME='database_name'
DB_USER='database_user'
DB_PASSWORD='database_password'
WP_ENV='development'

The alternative is a single data source name:

bash
DATABASE_URL='mysql://database_user:database_password@database_host:database_port/database_name'

The comment attached to it tells you what changes: when you use a DSN you can remove DB_NAME, DB_USER, DB_PASSWORD and DB_HOST. So the two forms are alternatives, not layers, and mixing them leaves you with two sources of truth for the same connection.

The second candid comment is the one that saves an afternoon. Two values are offered for the optional host, localhost and 127.0.0.1, with the instruction to use the numeric one if you hit mysqli 2002 or a socket connection problem. That error number is the only runtime failure the example file documents, and it appears only as a comment on a commented-out line in an example file.

WP_HOME keeps the root while WP_SITEURL adds /wp

The two site addresses in the example file are not duplicates. WP_HOME holds the address of the site itself and WP_SITEURL is written as ${WP_HOME}/wp, so the WordPress files sit one directory down from the address visitors use.

That arrangement is what makes web/ workable as the only document root in the repository. A site can be served from a domain while its PHP files live under a subdirectory, which is the arrangement you need as soon as anything else has to live at that domain.

WP_ENV sits next to them with the value development. Its only job in the example file is to name the environment, and the tree's config/ directory is the natural place for the per-environment files the overview refers to. A commented-out WP_DEBUG_LOG entry follows, taking a path rather than a switch, so the log destination is set as a path in the environment file.

What is missing is any per-environment override. The repository shows one .env.example and no local variant, so nothing states whether a developer machine is meant to add another file next to it or overwrite the one that is there.

Eight salts sit in the example file as 'generateme'

The last block of the example file is the WordPress secret set, and every value is a placeholder:

bash
AUTH_KEY='generateme'
SECURE_AUTH_KEY='generateme'
LOGGED_IN_KEY='generateme'
NONCE_KEY='generateme'
AUTH_SALT='generateme'
SECURE_AUTH_SALT='generateme'
LOGGED_IN_SALT='generateme'
NONCE_SALT='generateme'

Eight names, four keys and four salts, with a comment above them pointing at https://roots.io/salts.html as the place to generate them. Shipping the placeholders rather than blank lines is a deliberate choice: a file with eight identical placeholders is obviously unfinished, and the comment says where the real values come from.

Placing them in an environment file also keeps them out of the repository. Once the real values live outside the tree, a deploy needs an environment that carries them, and a second environment needs a second set, because sharing one set across two sites means one compromise reaches both.

The example file does not say which of the two files that pair with it wins, or whether a developer's own values are supposed to sit in a separate file. That rule is left to the installation documentation.

Regular plugins run as mu-plugins through an autoloader

One bullet in the overview is easy to skim and hard to undo: an autoloader for mu-plugins, using regular plugins as mu-plugins. The plugin code stays an ordinary Composer-managed plugin, and the autoloader is what puts it in the must-use position where the admin cannot deactivate it.

That is a deliberate architectural choice rather than a convenience, and the README frames it honestly. The philosophy behind the whole project is taken from the Twelve-Factor App methodology, with a WordPress specific version of it linked alongside. Configuration through environment-specific files and dependencies through Composer both come from that line of thinking, and the mu-plugins autoloader is the same idea applied to code: do not let an operator's click decide whether required code runs.

The cost lands on anyone who wants a per-site switch. Nothing in the repository documents how the autoloader locates those plugins, so a project cannot tell from the boilerplate alone whether a normal plugin directory would be loaded twice.

Access to the project's own discussion is arranged the same way: the Discord channel requires a GitHub sponsorship, which is what funds the WP Packages repository the plugins come from.

The one step missing is the command that creates the project

The repository hands off at exactly the point where a reader needs it most. The Getting Started section is a single sentence pointing at the Bedrock installation documentation, and the README offers no command that creates a project.

That matters less than it looks, because the boilerplate is published rather than cloned: both roots/bedrock and roots/wordpress sit on Packagist, and the repository runs a ci.yml workflow on GitHub Actions. A Composer-installed project therefore does not need a copy of this repository at all, which is a defensible design and the reason the boilerplate is versioned as releases rather than as a template.

It still leaves the reader with nothing to type. Every other part of the project is specified in the repository: the example file gives exact variable names, exact placeholder values and an exact host comment for the mysqli 2002 case. The one command that produces a working site lives outside the tree, on roots.io.

What is also unstated is how the installation documentation and the release line relate. If a reader follows the documentation on a day when master is ahead of the last tag, nothing in the repository says whether the documentation describes the branch or the release.

Editorial conclusion

Bedrock is the right base when a project has more than one environment and more than one developer, because its whole contribution is moving WordPress core, credentials and site addresses out of files people edit by hand and into Composer plus environment specific config files. It is the wrong base for a single site with one operator, where that separation buys nothing and the mu-plugins autoloader only removes your ability to switch a plugin off from the admin. Before you commit to a tag, check two things: which WordPress core version that tag names, since 1.31.6 ships 7.1.2 and not the other way round, and how your host connects to the database, since the example file suggests DB_HOST='127.0.0.1' if you encounter mysqli 2002 / socket connection issues.

Frequently asked questions

What does Bedrock change about a WordPress project layout?

It moves WordPress core out of the tree and into Composer through the roots/wordpress package, keeps plugins and themes in the WP Packages repository, and leaves a single web root at web/ beside a config/ directory of environment specific files read through Dotenv.

Which WordPress version does a Bedrock release target?

Each release names it in the tag title: 1.31.8 ships WordPress 7.1.4, 1.31.7 ships 7.1.3 and 1.31.6 ships 7.1.2. The tag in your lock file therefore states the core version without a second lookup.

Where does a Bedrock project keep its own PHP code?

The top level of the repository holds composer.json, a config/ directory and a single web root at web/, and the overview tells you to write regular plugins and let the mu-plugins autoloader run them as must-use code, so plugin PHP is added as a dependency rather than dropped into a folder by hand.

How does Bedrock decide where WordPress runs?

Two separate values in the example environment file do it: WP_HOME holds the site address and WP_SITEURL is written as ${WP_HOME}/wp, which places the WordPress files one directory below the address visitors use.

Can Bedrock use a single database connection string?

Yes. A commented-out DATABASE_URL entry holds a mysql:// DSN, and the comment next to it says that DB_NAME, DB_USER, DB_PASSWORD and DB_HOST can all be removed once the DSN is in place. The optional DB_HOST value also carries a note to switch to 127.0.0.1 on a mysqli 2002 or socket connection error.

Official sources

  1. License: MIT
  2. Project website
  3. README
  4. Releases
  5. roots/bedrock on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/roots-bedrock.svg)](https://hysenlabs.com/projects/roots-bedrock)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/roots-bedrock.svg)](https://hysenlabs.com/projects/roots-bedrock)

Was this useful?