wp-toolkit

npm-based build and deploy toolkit for any WordPress plugin.

Compile SCSS and JavaScript, package a production zip, rsync to your server, and optionally publish to WordPress.org SVN — all driven by one config file in your plugin.

A modern, config-first alternative to Grunt.

Who is this for?

• Plugin authors replacing Grunt / custom shell scripts
• Teams that want one standard workflow across multiple plugins
• Free plugins on WordPress.org or commercial / private plugins (SVN is optional)

Install

In your WordPress plugin root:

npm install @alimir/wp-toolkit --save-dev

Package: @alimir/wp-toolkit on npm

While developing the toolkit itself, link it locally:

npm install /path/to/wp-toolkit --save-dev

Quick start

1. Create your plugin config (this is where your paths and settings go):

cp node_modules/@alimir/wp-toolkit/wp-toolkit.config.example.mjs wp-toolkit.config.mjs

Edit wp-toolkit.config.mjs — set your slug, asset paths, deploy targets, and release options.

2. Add environment variables (secrets never go in the config file):

cp node_modules/@alimir/wp-toolkit/.env.example .env

3. Add npm scripts to your plugin package.json:

{
  "scripts": {
    "build": "wp-toolkit build",
    "build:js": "wp-toolkit build:js",
    "build:css": "wp-toolkit build:css",
    "dev": "wp-toolkit dev",
    "i18n": "wp-toolkit i18n",
    "i18n:json": "wp-toolkit i18n:json",
    "product": "wp-toolkit product",
    "release": "wp-toolkit release"
  },
  "devDependencies": {
    "@alimir/wp-toolkit": "^2.0.1"
  }
}

4. Build:

npm run build

Output lands in build/<your-slug>/ plus build/<your-slug>.zip.

Commands

| Command | Description | |---------|-------------| | wp-toolkit build | Full production build + zip | | wp-toolkit build:js | Compile and minify JavaScript only | | wp-toolkit build:css | Compile SCSS and minify CSS only | | wp-toolkit dev | Watch SCSS/JS and rebuild on change | | wp-toolkit deploy <name> | Rsync build/ to a configured server (default: prod) | | wp-toolkit product [name] | Build, then deploy (default: prod) | | wp-toolkit release | Build, then publish to WordPress.org SVN | | wp-toolkit i18n | Generate .pot file (requires WP-CLI) | | wp-toolkit i18n:json | Generate JSON from .po files |

Release safety flags

WP_RELEASE_DRY_RUN=1 npm run release   # preview SVN changes, no commit
WP_RELEASE_YES=1 npm run release       # skip interactive confirmation
WP_RELEASE_MESSAGE="Release 1.2.0" npm run release

Configuration

All plugin-specific settings live in wp-toolkit.config.mjs. Every asset path is explicit — wp-toolkit does not guess filenames from your slug.

The config uses one lifetime structure. Required sections are validated on startup with clear errors when something is missing or invalid.

Config layout

| Section | Required | Purpose | |---------|----------|---------| | Identity | yes | slug, mainFile, textDomain | | assets | yes | js.bundles, css.sassEntries (use [] / {} when unused) | | build | yes | excludes and release packaging options | | release | no | WordPress.org SVN (enabled: true + svnUrl) | | deploy | no | Rsync targets for commercial / private plugins | | i18n | no | POT generation (domain + potFile when present) | | variants | no | Alternate builds (regional, white-label, …) |

Level 1 — Every plugin (start here)

export default {
  slug: 'my-plugin',
  mainFile: 'my-plugin.php',
  textDomain: 'my-plugin',

  assets: {
    js: {
      bundles: [
        {
          sources: ['assets/js/src/app.js'],
          output: 'assets/js/my-plugin.js',
          minOutput: 'assets/js/my-plugin.min.js',
        },
      ],
    },
    css: {
      sassEntries: {
        'assets/css/my-plugin.css': 'assets/sass/my-plugin.scss',
      },
    },
  },

  build: {
    excludes: ['assets/sass', 'assets/js/src'],
  },

  // WordPress.org:
  release: { enabled: true, svnUrl: 'https://plugins.svn.wordpress.org/my-plugin' },

  // Commercial / private:
  // release: { enabled: false },
  // deploy: { prod: { envPrefix: 'DEPLOY_PROD' } },
};

npm run build      # → build/my-plugin.zip
npm run dev        # watch assets
npm run release    # WP.org only
npm run product    # deploy only

validation.inheritExcludes is on by default — paths in build.excludes are automatically blocked from release zips.

Level 2 — Optional extras (only if you need them)

Version in zip + versioned zip name (commercial plugins):

build: {
  zipName: '{slug}.{version}.zip',
  versionFile: { enabled: true, includeInZip: true },
},

Deploy to multiple servers — add a name, add matching .env vars:

deploy: {
  prod: { envPrefix: 'DEPLOY_PROD' },
  staging: { envPrefix: 'DEPLOY_STAGING' },
},

wp-toolkit product staging

Pre/post build hooks — run your own commands as part of wp-toolkit build:

build: {
  hooks: {
    preBuild: ['npm run codegen'],
    postBuild: ['npm run notify:slack'],
  },
},

Hooks accept shell strings or objects:

{ command: 'node', args: ['scripts/generate.php'], cwd: 'tools' }

Level 3 — Alternate builds (variants)

Use when you need a second build with different strings or zip name.
Deploy on a variant is optional — omit it for build-only variants.

variants: {
  regional: {
    zipSuffix: '-regional',
    replacements: [{ from: 'example.com', to: 'example.ir' }],
    files: ['**/*.php'],
    deploy: 'staging',   // optional — name from deploy.{name} above
  },
},

wp-toolkit build --variant regional
wp-toolkit product --variant regional   # build + deploy (uses variant.deploy)

Add custom npm scripts for convenience:

"build:regional": "wp-toolkit build --variant regional",
"product:regional": "wp-toolkit product --variant regional"

Config reference

| Option | Purpose | |--------|---------| | slug | Plugin folder name, zip name, deploy path | | mainFile | Main plugin PHP file | | textDomain | Translation text domain | | assets.js.bundles | JS bundles — each needs sources, output, minOutput | | assets.js.minify | Standalone minify targets ({ input, output }) | | assets.css.sassEntries | SCSS input → CSS output map | | assets.css.minifySeparate | Keep unminified .css alongside .min.css | | assets.watch | Extra directories to watch in dev | | build.excludes | Paths excluded from build/ | | build.devOnlyFiles | Files stripped from the production zip | | build.preprocess | Flags for /* @if PRO */ conditional blocks | | build.hooks | preBuild and postBuild shell commands | | build.zipName | Zip filename template ({slug}, {version}, …) | | build.versionFile | Write a version txt beside or inside the zip | | build.trimTrailingWhitespace | Strip trailing spaces/tabs from text files in the release bundle (default: true) | | deploy | Named rsync targets (prod, staging, …) | | release | WordPress.org SVN (enabled: true requires svnUrl) | | i18n | POT generation (domain, potFile) | | validation.inheritExcludes | Merge build.excludes into release checks (default: true) | | validation.forbidden | Extra paths that must not appear in a release zip | | validation.checkMinifiedAssets | Warn if PHP enqueues unminified assets (default: true) |

WordPress.org plugins

In wp-toolkit.config.mjs:

release: {
  enabled: true,
  wpAssets: 'wp-assets',
  svnUrl: 'https://plugins.svn.wordpress.org/my-plugin',
},

In .env:

WP_SVN_USER=your-wordpress-org-username
WP_SVN_PASSWORD=your-application-password
WP_SVN_URL=https://plugins.svn.wordpress.org/my-plugin

Release behaviour:

• Sparse SVN checkout (fast; avoids flooding output with old tags)
• Blocks re-releasing the same version tag
• Asks you to type yes before committing

Commercial / private plugins

release: { enabled: false },
deploy: { prod: { envPrefix: 'DEPLOY_PROD' } },

npm run product

Advanced (power users)

Multiple JS bundles — add more entries under assets.js.bundles:

assets: {
  js: {
    bundles: [
      { sources: ['assets/js/src/app.js'], output: 'assets/js/my-plugin.js', minOutput: 'assets/js/my-plugin.min.js' },
      { sources: ['admin/assets/js/src/admin.js'], output: 'admin/assets/js/admin.js', minOutput: 'admin/assets/js/admin.min.js' },
    ],
  },
},

Custom rsync args — add to any deploy target:

deploy: {
  staging: {
    envPrefix: 'DEPLOY_STAGING',
    rsync: { args: ['-avzP', '--delete-after'] },
  },
},

Variant deploy override — only if you need different rsync per variant:

variants: {
  regional: {
    deploy: { target: 'staging', rsync: { args: ['-avzP', '--delete-after'] } },
  },
},

Environment variables

Copy .env.example to .env in your plugin root. Never commit .env.

Deploy target names in config use envPrefix. That prefix becomes your .env keys:

| Config | .env keys | |--------|-------------| | deploy.prod.envPrefix: 'DEPLOY_PROD' | DEPLOY_PROD_HOST, DEPLOY_PROD_DEST, DEPLOY_PROD_PORT |

| Variable | Used by | |----------|---------| | DEPLOY_<NAME>_HOST | Rsync SSH host | | DEPLOY_<NAME>_PORT | SSH port (optional) | | DEPLOY_<NAME>_DEST | Remote plugin directory (absolute path) | | WP_SVN_USER | WordPress.org SVN username | | WP_SVN_PASSWORD | WordPress.org application password | | WP_SVN_URL | SVN repository URL | | WP_RELEASE_DRY_RUN | Preview release without committing | | WP_RELEASE_YES | Skip confirmation prompt | | WP_RELEASE_MESSAGE | Custom SVN commit message |

Requirements

• Node.js 18+
• zip and rsync on PATH
• svn — only for WordPress.org release
• wp (WP-CLI) — only for i18n commands
• Optional: pngquant, jpegoptim for image compression during build

Project layout

your-plugin/
├── wp-toolkit.config.mjs   ← your plugin settings (commit this)
├── .env                    ← secrets (gitignored)
├── package.json
├── assets/
├── build/                  ← generated (gitignored)
└── node_modules/

License

MIT