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
    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:
        # …
    

    Commands

    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:

    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.

    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
    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_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

    Conclusion

    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!