WP Blank Scripts

CLI and build tool for WordPress projects at ViVO Digital.

Requirements

• Node >=18
• MAMP (optional — skipped automatically if not installed)

Project Structure

New projects (v4+)

/
├── config/
│   ├── .htaccess{-environment}
│   ├── robots{-environment}.txt
│   └── wp-config{-environment}.php
├── src/
│   ├── blocks/
│   ├── parts/
│   ├── index.js
│   ├── style.scss
│   └── ...theme files
├── sql/
├── tasks/
│   └── overrides.js
├── vendor/
└── wp-content/

Legacy projects (pre-v4)

/
├── src/
│   ├── assets/
│   │   ├── admin/
│   │   ├── css/
│   │   ├── fonts/
│   │   ├── images/
│   │   └── js/
│   └── ...theme files
└── ...

Both structures are auto-detected — no configuration required.

Usage

Add to your project's package.json scripts:

{
  "scripts": {
    "dev": "wp-scripts dev",
    "build": "wp-scripts build",
    "build:staging": "wp-scripts build --environment=staging",
    "build:production": "wp-scripts build --environment=production",
    "import": "wp-scripts import",
    "backup": "wp-scripts backup",
    "setup": "wp-scripts setup",
    "export": "wp-scripts export",
    "deploy": "wp-scripts deploy",
    "pull": "wp-scripts pull"
  }
}

CLI Commands

dev

Run the project in dev mode with live reload.

Env variables:

• PORT=3001 — change dev server port
• HTTPS=1 — enable HTTPS for the dev server
• react mode is controlled via package.json: "wp-blank-scripts": { "react": true }

build

Build the project to the output directory.

Options:

• --environment local|staging|production — build environment (required)

When building for staging or production, output goes to dist-{environment} so it doesn't overwrite your local dev build. The deploy command handles cleanup automatically.

deploy

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

All environment info must be in config/settings.json.

Options:

• --environment staging|production (required)
• --mode Site|wp-content|Theme|Plugins|SQL only (required)
• --sql boolean — deploy SQL (assumed true if mode is SQL only)
• --serverPassword string — SSH password (if not using key)
• --serverPrivateKey string — path to SSH private key (defaults to ~/.ssh/id_rsa)

Example:

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

export

Export the local SQL database to the sql/ directory.

Options:

• --environment local|staging|production (required) — if not local, URLs are replaced with those from the config for that environment

Example:

wp-scripts export --environment="staging"

import

Import a SQL file into the local database. Creates the database if it doesn't exist.

Options:

• --file path/to/file (required) — pass latest to use the most recent file in ./sql
• --replace boolean — replace URLs before importing (does not mutate the original file)
• --environment local|dev|staging|production — environment to replace URLs from
• --currentEnvironment local|dev|staging|production — environment to replace URLs to

Examples:

wp-scripts import --file="./sql/database.sql"
wp-scripts import --file="latest"
wp-scripts import --file="./sql/database.sql" --replace="true" --environment="staging" --currentEnvironment="local"

pull

Pull a remote database to the sql/ directory.

Options:

• --environment staging|production (required)
• --serverPassword string
• --serverPrivateKey string

Example:

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

setup

Set up a new blank project by replacing template placeholders.

Options:

• --projectLocation string — path relative to MAMP document root
• --project string — project name
• --productionDomain string — production domain (e.g. example.com)
• --tablePrefix string — WordPress table prefix

Running without options launches an interactive prompt.

backup

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

hooks

Run a git hook action.

Options:

• --type string — hook type (e.g. post-merge)

config

Add deployment config for an environment.

Options:

• --environment staging|production

migrate-sass

Migrate legacy SCSS to Dart Sass 3.0 compatible syntax using the official sass-migrator.

Dart Sass 3.0 removes @import, deprecated color functions (darken, lighten), / for division, and global built-in functions (map-get, nth). This command runs the official migrations in a safe order.

Options:

• --migration division|color|module — run a single specific migration (omit to run all three in order)
• --glob string — SCSS file glob (default: src/**/*.scss)
• --dry-run — preview changes without writing files

Migrations (run in this order):

| Migration | What it does | Risk | |-----------|-------------|------| | division | Replaces / division with math.div(), adds @use 'sass:math' | Low | | color | Replaces darken()/lighten() etc. with color.adjust()/color.scale(), adds @use 'sass:color' | Low | | module | Converts @import → @use/@forward, namespaces variables/mixins/functions | High — review carefully |

Recommended workflow:

Node modules are resolved automatically (--load-path=. is passed to sass-migrator), so imports like @import 'node_modules/swiper/css/swiper.min' are handled correctly.

# 1. Preview what will change
wp-scripts migrate-sass --dry-run

# 2. Run the safe migrations first
wp-scripts migrate-sass --migration=division
wp-scripts migrate-sass --migration=color

# 3. Verify your build still works, then commit
yarn build

# 4. Run the module migration separately — requires manual review
#    Variables will be namespaced (e.g. $var → variables.$var)
wp-scripts migrate-sass --migration=module

The module migration is complex and almost always requires manual cleanup — especially if partials are imported in multiple places. Run it last and review every changed file before committing.

Overrides

Create a tasks/overrides.js file in your project to customise the build.

copyFiles

Add extra files to the webpack copy task.

exports.copyFiles = (paths) => {
  const { sourceDir, themeDir, sourcePath, buildPath, themePath } = paths;

  return [
    {
      from: path.join(sourceDir, 'my-directory'),
      to: path.join(themePath, 'my-directory'),
    },
  ];
};

webpackConfig

Override the default webpack config (merged via webpack-merge).

exports.webpackConfig = () => {
  return {
    devtool: false,
  };
};

loaderOptions

Override default loader options. Available loaders: css, js, images, fonts.

exports.loaderOptions = () => {
  return {
    js: {
      exclude: /(node_modules|vendor)/,
    },
  };
};

checkProjectDependencies

Run a custom dependency check before the project builds.

exports.checkProjectDependencies = async () => {
  const pck = JSON.parse(fs.readFileSync('package.json', 'utf8'));
  if (!pck.dependencies['some-required-package']) {
    console.warn('Missing some-required-package!');
  }
};