WP Blank Scripts

CLI and build tool for Wordpress projects.

Upgrade to v3

Surprisingly there are no breaking changes.

v3 Warnings

Sass division outside of calc() deprecated

Deprecation Using / for division outside of calc() is deprecated and will be removed in Dart Sass 2.0.0. Recommendation: math.div(-$grid-gutter, 2) or calc(-1 * $grid-gutter / 2). More info and automated migrator: https://sass-lang.com/d/slash-div

Fix:

npm install -g sass-migrator
sass-migrator division **/*.scss

Project Structure

/
├── config
│   ├── .htaccess{-environment}
│   ├── robots{-environment}.txt
│   └── wp-config{-environment}.php
├── src
│   ├── assets
│   │   ├── admin
│   │   ├── css
│   │   ├── fonts
│   │   ├── img
│   │   └── js
│   ├── functions.php
│   ├── inc
│   ├── screenshot.png
│   ├── style.css
│   └── templates
├── sql
├── tasks
│   └── overrides.js
├── vendor
├── wordpress
└── wp-content

Usage

Typically you'll use this in your npm scripts (or package scripts):

{
  "scripts": {
    "start": "wp-scripts dev",
    "build": "NODE_ENV=production wp-scripts build",
    "import": "wp-scripts import",
    "backup": "wp-scripts backup",
    "setup": "wp-scripts setup",
    "export": "wp-scripts export",
    "deploy": "wp-scripts deploy",
    "pull": "wp-scripts pull",
    "clone": "wp-scripts clone"
  }
}

CLI

backup

Backup wp-content from dev project to local file system.

build

Build the project to the output directory

Env variables:

• BUILD_ENV=local|staging|production to set the build environment

Options:

environment local|staging|production (required)

The environment to deploy to, defaults to process.env.BUILD_ENV

dev

Run the project in dev mode with live reload server.

Env variables:

• PORT=3001 to change dev server port to 3001
• HTTPS=1 to enable https for the dev server

deploy

Build and deploy the project via SSH, with optional SQL.

All environment information should be in project/config/settings.json.

Options:

environment staging|production (required)

The environment to deploy to.

mode Site|wp-content|Theme|Plugins|SQL only (required)

What should be deployed, Site is the entired build directory.

sql boolean

Should SQL be deployed, this is assumed true if mode is SQL only.

serverPassword string

The password for the configured user on the server. This is only required if sql is true and no serverPrivateKey is provided.

serverPrivateKey string

Path to the private key for the configured user on the server. This is only required if sql is true and no serverPassword is provided.

Example:

wp-scripts deploy --mode="wp-content" --environment="staging"

export

Export the local SQL database to the project/sql directory.

Options:

environment local|staging|production (required)

The environment you are exporting for. If not local urls will be replaced to those found in the config file for that environment.

Example:

wp-scripts export --environment="staging"

import

Import a local SQl file to the local database.

Will automatically create the database if it does not exist.

Options:

file path/to/file (required)

The path to the file to import.

Pass latest instead of a file path to automatically import the most recent SQL file from the ./sql directory.

replace boolean

Should urls be replaced in the SQL before importing. This will not mutate the original file.

environment local|dev|staging|production

The environment you are replacing the urls from. This is only required if replace is true.

currentEnvironment local|dev|staging|production

The environment you are replacing the urls to. This is only required if replace is true.

Example:

wp-scripts import --file="./sql/database.sql"
# Import file and replace urls from staging to dev
wp-scripts import --file="./sql/database.sql" --replace="true" --environment="staging" --currentEnvironment="dev"
# Use the latest file
wp-scripts import --file="latest"

pull

Pull from an environment database to the project/sql directory.

Options:

environment staging|production (required)

The environment you are pulling for. This will not replace urls in the file.

serverPassword string

The password for the configured user on the server. This is only required if no serverPrivateKey is provided.

serverPrivateKey string

Path to the private key for the configured user on the server. This is only required if no serverPassword is provided.

Example:

wp-scripts pull --environment="staging" --serverPrivateKey="~/.ssh/id_rsa"

setup

Setup a new blank project.

Options:

projectLocation string (required)

Default: process.cwd

The location of the project relative to your MAMP server directory.

project string (required)

The project name

productionDomain string (required)

The production domain name

agency string (required)

The name of the agency

agencySlug string (required)

The slug version of the agency name

agencyWebsite string (required)

The agency website url

tablePrefix string (required)

The table prefix for wordpress tables

Example:

wp-scripts setup --project="Hello"  --productionDomain="example.com" --agency="Mitch" --agencySlug="mitch" --agencyWebsite="mitch.app" --tablePrefix="mh_"

hooks

Run a git hook

Options:

type string (required)

The type of git hook to run.

Example:

wp-scripts hooks --type="pre-commit"

Upgrading from v0.3

There are multiple breaking changes since v0.3, including a new build system.

Run the upgrade script in the project:

node_modules/.bin/wp-scripts upgrade

Note: Make sure you have committed everything before upgrading.

Overrides

You can export custom functions to override the default build behaviour.

Just create an tasks/overrides.js file in the project.

copyFiles

Add extra files to the build copy task.

See copy-webpack-plugin for more details.

exports.copyFiles = (paths) => {
  // The paths object contains source, theme and build paths.
  const {
    sourceDir, // Relative
    themeDir, // Relative
    sourcePath, // Absolute
    buildPath, // Absolute
    themePath, // Absolute
  } = paths;

  return [
    {
      // Copy an entire directory to the theme
      from: path.join(sourceDir, 'new-directory'),
      to: path.join(themePath, 'new-directory'),
    },
    {
      // Copy files inside a directory the the theme
      from: path.join(sourceDir, 'new-directory'),
      to: themePath,
    },
    {
      // Copy file from a directory to the root directory
      from: path.join(sourceDir, 'directory-file-was-in', 'file.txt'),
      to: '',
    },
    {
      // Copy all files from vendor (except vivo-digital & johnpbloch) to the theme/inc/vendor
      from: path.join(__dirname, "..", "vendor"),
      to: path.join(themePath, "inc", "vendor"),
      globOptions: {
        ignore: [
          path.join("@(vivo-digital|johnpbloch)", '**')
        ],
      }
    }
  ];
}

webpackConfig

Overide the default webpack config.

exports.webpackConfig = () => {
  return {
    // Disable sourcemaps completely
    devtool: false,
  }
}

loaderOptions

Overide default loader options. This is useful in cases where you want to alter an existing loader and cannot use a custom webpackConfig.

Available loaders: css, js, images, fonts

exports.loaderOptions = () => {
  return {
    js: {
      // Don't run js files from node_modules OR vendor directories through the JS (babel) loader
      exclude: /(node_modules|vendor)/,
    }
  };
};

copyFx

You can change the path of fx packages (classes or modules) installed via composer. This is useful for local development.

This function should return an object with the package name as the key and local path as the value.

exports.copyFx = () => {
  return {
    'package-name': 'path/to/local/repository',
  };
}

checkProjectDependencies

Run a custom dependency check before the project builds.

exports.checkProjectDependencies = () => {
  const pck = JSON.parse(fs.readFileSync(projectPackage, 'utf8'));
  const { dependencies } = pck;

  if (!dependencies['some-required-package']) {
    console.log('Missing this package!');
  }
};

Node Version

Currently supports 18.8.0 for all projects running [email protected]