Configuration 101: a
A YAML configuration file called a
Juicefile can be used to store commonly used build scripts, similar in spirit to
npm scripts. Each command can be mapped to any build script you like, allowing you to define a set of commands that can be used for your project. This is a great feature for teams because designers don't need to worry about learning the command line to utilize all of a project's development tools.
If you plan to deploy using Theme Juice, this file will also house your project's deployment configuration.
For reference, below is an example
# Project configuration project: name: example url: example.dev # Manage command aliases for the current project commands: # Run project install scripts install: - npm install - grunt build # Manage build tools dev: - grunt %args% # Manage front-end dependencies asset: - npm %args% # Manage back-end dependencies vendor: - composer %args% # Create a backup of the current database with a nice timestamp backup: - mkdir -p backup - wp @development db export backup/$(date +'%Y-%m-%d-%H-%M-%S').sql # Manage deployment settings for the current project deployment: # … stages: # …
Each command within the above example can be run from your project's dashboard. For example, we can run the
dev command from within our project's dashboard, which will in turn run the command
grunt. If you happened to have noticed in the example above, there are a few sub-commands that contain
%args%; these are called placeholders. Each sub-command list is run within a single execution via joining:
cmd1 && cmd2 && cmd3 && ..., with all placeholders (
%argN%) replaced with their corresponding argument index, when available.
Here's a few example commands utilizing placeholders:
commands: example-command-1: # Will contain all arguments joined by a space - echo "%args%" example-command-2: # Will contain each argument mapped to its respective index - cat '%arg1% %arg2% %arg3%' # Will only map argument 4, while ignoring 1-3 - pbcopy < "%arg4%"
To clarify a little bit more using our first example config, we could run the
dev task from our project dashboard with the argument
build, and since our
dev command contains
%args%, that will in turn run the command
grunt build; if we run our
dev command with the arguments
some:other task, that would be interpreted and run as
grunt some:other task.
You can specify an unlimited number of commands with an unlimited number of arguments within your
Juicefile; however, you should be careful with how this is used. Don't go including
sudo rm -rf %arg1% in a command, while passing
/ as an argument. Keep it simple. These are meant to make your life easier by helping you manage build tools, not to do fancy scripting.
You may define ERB template strings within a project starter template's
Juicefile. These will be replaced when creating a new project.
# Project configuration project: name: <%= name %> url: <%= url %>
will be replaced with,
# Project configuration project: name: example-project url: example-project.dev
if those were the options chosen during a project creation.
Available variables for use
name: Project name
location: Project location
url: Project URL
xip_url: Project xip.io URL
template: Project template repository URL
repository: Initialized repository URL, if available
db_host: Project database host
db_name: Project database name
db_user: Project database user
db_pass: Project database password
db_import: Path to imported database file
vm_box: Virtual machine box URL
vm_ip: Virtual machine IP address
vm_revisionRevision hash or branch of VM
vm_path: Virtual machine location on the host machine
vm_root: Web root of the VM on the host machine
vm_location: Project location within the VM on the host machine
vm_srv: Project location within the VM on the guest machine
vm_prefix: Virtual machine project location prefix
In closing, a
Juicefile is a powerful file that you are encouraged to take advantage of. If you find yourself forgetting what arguments or flags to use for a command you use often, it might be a great candidate for a
Juicefile command. In our next guide, we'll be covering how to create your own starter template, utilizing a custom-tailored