Configuration

Just config' it

Sake is built with convention over configuration in mind, so most plugins need little to no configuration at all. That said, the default setup may not be suitable for everything. For this reason, each multi-plugin repo and each individual plugin can provide it's own configuration file, sake.config.js to customize almost any aspect of Sake.

Note that CLI options are separate from configuration.

Check existing configuration

Before creating or adjusting a config file, it may be a good idea to check what the default configuration for a plugin looks like. Sake provides a convenient task, aptly named config just for that.

$ npx sake config

This will output the full configuration JSON (truncated here to save space):

{ paths:
   { src: 'src',
     assets: 'assets',
     css: 'assets/css',
     js: 'assets/js',
     images: 'assets/img',
     fonts: 'assets/fonts',
     build: 'build',
     tmp: '/tmp/sake',
     exclude: [],
     assetPaths:
      { css: 'src/assets/css',
        js: 'src/assets/js',
        images: 'src/assets/img',
        fonts: 'src/assets/fonts',
        javascriptSources: [Array] },
     vendor: 'vendor',
     framework: { base: 'lib/skyverge', general: [Object], gateway: [Object] },
     wpAssets: 'wp-assets' },
  framework: 'v5',
  deploy:
   { type: 'wp',
     dev:
      { url: '[email protected]:skyverge/jilt-for-woocommerce.git',
        owner: 'skyverge',
        name: 'jilt-for-woocommerce' },
     production:
      { url: 'http://plugins.svn.wordpress.org/jilt-for-woocommerce',
        user: 'SkyVerge',
        name: 'jilt-for-woocommerce' },
     docs:
      { url: '[email protected]:skyverge/plugin-docs.git'',
        owner: 'skyverge',
        name: 'plugin-docs' } },
  platform: 'wc',
  plugin:
   { name: 'Jilt for WooCommerce',
     id: 'jilt-for-woocommerce',
     changes: '...', // truncated
     version: '...', // truncated
     mainFile: 'jilt-for-woocommerce.php',
     frameworkVersion: '5.0.1' },
  composer: '...' // truncated
}

You can also provide a property name or path to see the configuration for that particular part only:

$ npx sake config --property=deploy.production

Will result in something like this:

{ url: 'http://plugins.svn.wordpress.org/jilt-for-woocommerce',
  user: 'SkyVerge',
  name: 'jilt-for-woocommerce' }

Providing a configuration file

Sake will look for a sake.config.js file in the directory it's being run, and if none is found, also one level up - in the parent directory. This is to facilitate multi-plugin repos, which individual plugins inherit and can also override when needed. To override the parent config file, simply place a sake.config.js file in the plugin subdirectory.

Example of a single-plugin repo:

// files are in jilt-for-woocommerce
src/jilt-for-woocommerce.php
src/readme.txt
composer.json
package.json
sake.config.js

sake.config.js

module.exports = {
  framework: 'v5',
  paths: {
    src: 'src'
  },
  deploy: 'wp'
}

Example of a multi-plugin repo:

// files are in wc-plugins
woocommerce-gateway-authorize-net-sim/woocommerce-gateway-authorize-net-sim.php
woocommerce-gateway-authorize-net-sim/changelog.txt
woocommerce-gateway-authorize-net-sim/sake.config.js
package.json
sake.config.js

Configuration files:

// sake.config.js
module.exports = {
  paths: {
    src: '.'
  },
  framework: 'v4',
  multiPluginRepo: true
}

// woocommerce-gateway-authorize-net-sim/sake.config.js
module.exports = {
  framework: 'v5'
}

In the example above, woocommerce-gateway-authorize-net-sim will inherit all settings from the main sake.config.js, but will override the framework value to v5.

Configuration options

While it's possible to customize almost any configuration value available, mostly only a few are needed. Here is a list of the commonly used options:

module.exports = {
  // sets up the plugin folder structure, default values shown below
  paths: {
    // Path to plugin source files - this is where the main plugin entry file is located. Set this to a dot (.)
    // if the main plugin file and sake.config.js are in teh same directory. The path is relative to the current
    // working directory. Mostly, this is the only path a plugin/repo needs to explicitly set
    src: '.',
    // where plugin assets are located, relative to `src`
    assets: 'assets',
    // where plugin CSS/SCSS assets are located, relative to `src`
    css: 'assets/css',
    // where plugin JS/COFFEE assets are located, relative to `src`
    js: 'assets/js',
    // where plugin image assets are located, relative to `src`
    images: 'assets/img',
    // where plugin font assets are located, relative to `src`
    fonts: 'assets/fonts',
    // the directory where plugin files are copied during the build task, relative to current working directory
    build: 'build',
    // path to the directory where production (WC and WP.org SVN) repos are cloned, may be an absolute path or
    // relative to current working directory
    tmp: '/tmp/sake',
    // array of paths that should be excluded from the build
    exclude: []
  },

  // Task-specific settings, set the key to task name and provide any settings as needed. Since sake uses Gulp
  // behind the scenes and Gulp prefers code over configuration, there isn't a lot to do here. As you can see,
  // some of these values can be defined as environment variables, as this makes more sense - ie whether you
  // want to use browsersync or not is specific to your local dev environment and workflow, not to a particular repo.
  tasks: {
    makepot: {
      reportBugsTo: 'https://woocommerce.com/my-account/marketplace-ticket-form/'
    },
    watch: {
      useBrowserSync: process.env.USE_BROWSERSYNC || false
    },
    browserSync: {
      url: process.env.BROWSERSYNC_URL || 'plugins-skyverge.test'
    }
  },

  // which framework version this plugin uses - valid values: 'v5', 'v4', or pass boolean `false` to indicate a
  // non-frameworked plugin
  framework: 'v5',
  // which deploy type does this plugin use - either 'wc' or 'wp', defaults to 'wc', specify `false` for
  // no automated deploy
  deploy: 'wc',
  // alternatively, the deploy property can be an object for more fine-grained control:
  deploy: {
    // the deploy type
    type: 'wc',
    // The development repo for this plugin or multi-plugin repo. You should almost NEVER need to set this manually,
    // as it's automatically detected up from your local git repo. Used when fetching and creating release issues 
    // and milestones. This means that if you're working with a personal testing fork of a plugin repo, such as 
    // 'ragulka/wc-plugins', this will automatically be detected, so that any commits, release issues, etc will be 
    // created on your test fork. For possible values, see `production` below.
    // Note that DEPLOY_DEV env variable will take precendence.
    dev: process.env.DEPLOY_DEV || 'skyverge/wc-plugins',
    // The production repo for this plugin. Sake will intelligently determine this for you based on the deploy type
    // and plugin ID, for example, deploy.type = 'wc' and plugin folder 'woocommerce-memberships' will result in
    // 'woocommerce/woocommerce-memberships'. Sometimes, however, the production repo must be customized, when
    // example, if the WC repo has a different name. In this case, you can either set both the owner and repo 
    // name, or just the repo name. For SVN deploys (such WP.org deploys), only the repo name or a full path
    // to the svn repo must be provided.
    //
    // Valid values:
    // * 'plugin-slug' // works for either WC (assumes 'woocommerce' is the owner) or WP deploys
    // * 'owner/plugin-slug' // works only for WC deploys
    // * '[email protected]:owner/plugin-slug.git' // works only for WC deploys
    // * 'http://plugins.svn.wordpress.org/plugin-slug' // works only for SVN deploys
    // * 'file:///Users/ragulka/Code/skyverge/plugin-slug' // this is great for testing SVN deplopys
    //
    // Note that DEPLOY_PRODUCTION env variable will take precendence.
    // Alias for `deploy.repo`
    production: process.env.DEPLOY_PRODUCTION || 'skyverge/wc-plugins-test'
    // The docs repo for this plugin. Sake offers to create documentation issues after a version of the plugin
    // that includes new features or tweaks existing behavior is deployed.
    //
    // Sake will always attempt to parse the docs repo unless `deploy.docs` is set to `false` in the config file. It will throw an error if no value is defined or the value is invalid.
    //
    // Valid values:
    // * 'owner/plugin-slug'
    // * '[email protected]:owner/plugin-slug.git'
    // * false // do not ask to create a doc issue
    docs: process.env.DEPLOY_DOCS || 'skyverge/wc-plugin-docs'
  },
  // the e-commerce platform this plugin is for, 'wc' or 'edd' - currently this only affects whether the
  // "WC tested up to" version will be automatically bumped on deploy or not
  platform: 'wc',
  autoload: false // whether the plugin uses autoloading. If true, 'vendor/composer/' and 'vendor/autoload.php' will be retained during deploy

  // The following optional `bundle` property will instruct Sake to fetch specific files from `node_modules` and copy them into destination folders within the plugin repo; this is helpful when, for example, we want to bundle an external JS dependency such as a frontend or vendor dependency inside the plugin assets. Note that you should have the corresponding `source` defined in the plugin's `package.json` own `dependencies`.
  bundle: {
        scripts: [
            {
                source: '@my-vendor/my-package/dist',
                file: 'example-block.js',
                destination: 'assets/js/blocks',
            }
        ],
        styles: [
            {
                source: '@my-vendor/my-package/dist',
                file: 'exmaple-block.css',
                destination: 'assets/css/blocks',
            }
        ],
    },

}

Note

When using the bundle configuration option you should have defined the corresponding sources listed in the bundle property in the plugin's package.json file - following the above example:

"dependencies": {
   "@my-vendor/my-package": "1.2.3"
}

Please ensure this package is installed before the npx sake bundle step runs.