Production Bundling & Exports

The dev theme and the shipped theme are different artifacts. npm run bundle compiles, optimizes, translates, prunes, and zips your theme into something you can install — or submit to WordPress.org. This post covers what the bundle does and how to configure it.

The bundle command

npm run bundle          # production build + optional .zip
npm run bundle:wporg    # bundle prepped for WordPress.org submission
npm run test:prod-build # verify the full production path (setup → bundle → tests)
  • Compiles everything: CSS (Lightning CSS, minified), JS/TS (esbuild, minified), blocks, and design tokens — generated artifacts (_tokens.generated.css, theme.json, Tailwind config) are regenerated fresh so the bundle always matches the committed inputs.
  • Optimizes images: sharp processes assets/images/src; JPEG/PNG sources additionally emit WebP + AVIF (see Performance & the Asset Pipeline).
  • Generates translations: the .pot file lands in languages/ (unless export.generatePotFile is false). Also available standalone: npm run rig:localize.
  • Prunes dev artifacts: non-essential files from the development theme — source maps, dev-only scripts, the Dev_Tools component, framework metadata — never reach the package.

Version stamping

Your theme’s version lives in config (theme.version) and is stamped into style.css and readme.txt at bundle time. The framework’s version (config/framework.json) is stripped — a built theme never carries it, fixing a leak where stale framework metadata reached production themes. Bump versions with:

npm run rig version:framework 3.5.0   # framework version (source only)
npm run rig version 1.0.0             # theme version
npm run rig version                   # print both

Export configuration

The export section of the config chain controls the bundle:

// config/config.json
{
  "export": {
    "compress": true,
    "generatePotFile": true,
    "includeWpCli": false,
    "filesToCopy": [
      "LICENSE",
      "readme.txt",
      "screenshot.png",
      "assets/css/vendor/**/*.css",
      "assets/js/vendor/**/*.js",
      "assets/svg/*.svg",
      "assets/icons/*.svg"
    ]
  }
}
  • compress — create a .zip alongside the bundle directory.
  • generatePotFile — translation template generation.
  • filesToCopy — glob list of extra files pulled into the package (vendor CSS/JS, SVGs, icons, screenshots, license files).

WordPress.org submission

npm run bundle:wporg produces the WordPress.org-flavored package: theme-check-clean metadata, Tested up to aligned with the supported WP version, .pot included, and no plugin-territory files. Pair it with the audit suite before submitting:

npm run audit:theme-review   # full WP.org-style review simulation
npm run audit:theme-check    # Theme Check rules
npm run audit:i18n           # internationalization audit

What never ships

  • config.local.json and all local dev state.
  • The developer toolbar (assets stripped, Dev_Tools component excluded — see WP Rig Tools).
  • Framework version metadata.
  • Source files, source maps, and dev build artifacts.

Performance & the Asset Pipeline (what the minified assets contain), Child Theming (version separation in children), and Theme Configuration (the export section in context).