Configuration 101: a Juicefile

    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 Juicefile:

    # Project configuration
      name: example
    # Manage command aliases for the current project
      # Run project install scripts
        - npm install
        - grunt build
      # Manage build tools
        - grunt %args%
      # Manage front-end dependencies
        - npm %args%
      # Manage back-end dependencies
        - composer %args%
      # Create a backup of the current database with a nice timestamp
        - mkdir -p backup
        - wp @development db export backup/$(date +'%Y-%m-%d-%H-%M-%S').sql
    # Manage deployment settings for the current project
      # …
        # …


    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 (%args%/%argN%) replaced with their corresponding argument index, when available.

    Here's a few example commands utilizing placeholders:

        # Will contain all arguments joined by a space
        - echo "%args%"
        # 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.

    Template Strings

    You may define ERB template strings within a project starter template's Juicefile. These will be replaced when creating a new project.

    For example,

    # Project configuration
      name: <%= name %>
      url: <%= url %>

    will be replaced with,

    # Project configuration
      name: example-project

    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 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_revision Revision 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 Juicefile config.

    Happy coding!