May 2020: version 3.0 just released! Completely new architecture for the Gutenberg / Block era.
@wordpress/scripts
and custom Webpack configsFabrica Dev Kit is compatible with recent versions of Mac OS X. It has a few dependencies:
Optional but recommended:
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.
fdk init
. This will create a template setup.yml
file for your basic project settings.setup.yml
to 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 setup
from 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.config.yml
folder (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 config.yml
:
default:
plugins:
- ../../plugins/fabrica-shared-block
themes:
- ./src/themes/fdk-theme
ftp:
- host: fdkserver.dev
- user: fdk
- password: fdk
- path: /public-html
staging: plugins:
2. 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.resolve` and the current folder, for example `path.resolve(__dirname, 'src/js/front.js')`
fdk start
in 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 build
to 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
.
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
.
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 wordpress
.
(You can type fdk
in any FDK project folder to see this list.)
Command | Description |
---|---|
init [options] [slug] |
Start a new project folder called [slug] containing the setup.yml configuration file. [slug] must be unique and no other Docker Compose project should share this name. All optional arguments will be set in the setup.yml file and can be modified there before running setup . |
setup [options] |
Setup project based on setting on setup.yml file |
config:url |
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 |
config:resources [project] |
Configure Docker volumes to match resources' paths in the config.yml settings file if there are new resources under [project] . If no [project] is passed, resources under default will be checked |
config:all [project] |
Run all project configuration tasks (config:url and config:resources ) |
urls |
Output current access URLs and ports |
deploy [project] |
Deploy resources to server according to configuration in config.yml file. If no [project] is passed, settings under default will be loaded. Files and folders matching patterns in resource .distignore file will be ignored |
start |
Run Webpack in development mode. All available resources' Webpack configurations are loaded, and changed files are watched |
build |
Run Webpack in production mode and build source for all available resources Webpack configurations |
dc |
Run docker-compose commands, eg. fdk dc ps |
sh |
Start shell on WP container |
shroot |
Start shell as root on WP container |
wp |
Run WP Cli. eg. fdk wp option list |
logs |
Tail WP container logs |
remove |
Stop all project containers, remove their volumes and WP project image |