A toolkit for faster, smoother WordPress 5 development
May 2020: version 3.0 just released! Completely new architecture for the Gutenberg / Block era.
- Super fast setup of project-specific local development servers using Docker
- Allows simultaneous development of multiple blocks, plugins and themes: FDK's master watch / build script runs all resources' build steps together in one process
- Compatible with
@wordpress/scriptsand custom Webpack configs
- Starter theme and block available, but works with yours; agnostic on code frameworks
- Instantly build and deploy to multiple environments
FDK 3 features in detail
Installs and configures an independent local development environment for each project
- Using Docker, creates an independent development environment for your project running the Nginx web server and the latest version of PHP-FPM. Docker's efficient architecture means that each Fabrica Dev Kit project runs and is stored separately (unlike MAMP, where all projects share space and servers), while avoiding the bloat of a Vagrant-like solution (where each project has a capacious virtual machine to itself).
- Automatically installs all the software required to develop, including the latest version of WordPress and your plugins of choice (you just list them in the initial setup file), as well as deployment tools.
- Setup of a new project takes a matter of seconds (after the first-time installation of dependencies and Docker images).
Reduces friction to accelerate development and deployment
- Automatically syncs individual development resources with the project's Docker machine; new resources can easily be added or removed
- Magic master Webpack script processes each all resources' Webpack configs simultaneously, meaning you only have to run one watch / build for the whole project
- Allows deployment of all development resources with a single terminal command to staging or production servers (using lftp mirror). Only the resources in your config are deployed / mirrored; other themes or plugins are left intact.
Requirements + dependencies
Fabrica Dev Kit is compatible with recent versions of Mac OS X. It has a few dependencies:
- Docker – download and run the installer by following the link for Mac OS X from the Docker downloads page (Stable channel is fine).
- Node.js – download and run the installer by following the link to the Recommended Version from the Node.js homepage.
Optional but recommended:
- If you want to use FTP for deployment, you'll need lftp (installation instructions).
Installing Fabrica Dev Kit
First make sure you have all the required dependencies (see above). Then run
npm install fabrica-dev-kit -g to install Fabrica Dev Kit onto your system ready to use globally via the
fdk shell command.
Starting a new project
- Create a folder for your project. In this folder run
fdk init. This will create a template
setup.ymlfile for your basic project settings.
setup.ymlto configure basic parameters for your project. Third-party plugins you want to be installed automatically in your local development environment can be listed here.
fdk setupfrom the same folder. This will set up your virtual machine and install everything required: Nginx, PHP-FPM, WordPress, any third-party plugins and our development and deployment tools.
Configuring your development resources
- Tell FDK which local resources (ie. themes and plugins) you want to be available for development in the current project by editing
config.ymlfolder (in the project root) to specify the local resource paths. These can be within the current project folder (eg. in a
src/folder) or anywhere else on your system, if you plan to share resources like blocks between projects. You can also specify server details for deployment, and you can specify multiple environemnts configs in the same file. Example entries for a
default: plugins: - ../../plugins/fabrica-shared-block themes: - ./src/themes/fdk-theme ftp: - host: fdkserver.dev - user: fdk - password: fdk - path: /public-html staging: plugins: - ../../plugins/fabrica-shared-block themes: - ./src/themes/fdk-theme ftp: - host: staging.fdkserver.dev - user: staging - password: staging - path /staging
- FDK will invoke each resource's individual Webpack config to build resources (if it needs a build step; otherwise the folder will just be mirrored as it is). To make sure this works correctly, any paths in your Webpack config should be resolved fully with
path.resolveand the current folder, for example
Running the master Webpack during active development
- To start developing, run
fdk startin the project folder. FDK will tell you which dynamic port the site front-end, admin and database are accessible at for this session, for example:
[FDK] 🏭 FDK Project (fdk-project) access URLs: [FDK] 🏭 ------------------------------------------- [FDK] 🏭 🌍 WordPress: http://localhost:32773/ [FDK] 🏭 🔧 Admin: http://localhost:32773/wp-admin/ [FDK] 🏭 🗃 Database: localhost:32774 [FDK] 🏭 -------------------------------------------
- FDK will then run its master Webpack watch monitoring and compiling all of your specified resources at once, using each one's own Webpack settings respectively.
- You can escape Webpack with ctrl + c. While Webpack is not running, changes requiring a build step will not be reflected on the server.
- You can also run
fdk buildto run Webpack in build mode, eg. prior to deployment.
To deploy your resources, run
fdk build (runs Webpack for all resources in build mode) and then
fdk deploy. This will deploy using the resources and server specified in the
default section of
config.yml; if you want to deploy to a different environment, simply add its name, eg.
fdk deploy staging.
Troubleshooting and housekeeping
If you run into any problems during development, restarting the Docker machine may help. Stop FDK with ctrl + c and then run
fdk dc restart followed by
fdk start again.
Multiple projects' Docker servers running simultaneously can hog system resources, so you can safely suspend any projects not currently being developed with
fd dc stop in the project folder (or from the Docker Dashboard). Equally it is safe to run
fdk remove which removes the project's containers altogether (the local database is preserved); to set them up again you can run
fdk setup --reinstall.
Local database access
For direct MySQL access to the development database, you can use an app such as Sequel Pro while the development machine is up. The database server is accessible at
127.0.0.1, and with the dynamic port which you'll be told when you run
fdk start (see example output above). The username, password and database name are are
All available FDK commands
(You can type
fdk in any FDK project folder to see this list.)
||Start a new project folder called
||Setup project based on setting on
||Update URLs in DB to match changes to WP container port set automatically by Docker (except for multisite projects, where a custom local host/domain is used). Output current access URLs and ports|
||Configure Docker volumes to match resources' paths in the
||Run all project configuration tasks (
||Deploy resources to server according to configuration in
||Run Webpack in development mode. All available resources' Webpack configurations are loaded, and changed files are watched|
||Run Webpack in production mode and build source for all available resources Webpack configurations|
||Start shell on WP container|
||Start shell as root on WP container|
||Run WP Cli. eg.
||Tail WP container logs|
||Stop all project containers, remove their volumes and WP project image|