@devgateway/upgrade-wp-customizer

@devgateway/upgrade-wp-customizer

Upgrade and modernize your WordPress Customizer projects to use the latest block-based structure and best practices, with automated code transformations and dependency management.

Features

• Automated migration of legacy WordPress Customizer projects to a modern block-based structure.
• Transforms import paths to use @devgateway/dvz-wp-commons and updates environment variable usage.
• Copies and merges template files (JS, PHP, CSS, config) into your project.
• Backs up your project before making changes, with easy rollback on cancel.
• Prompts for dependency installation in the new blocks directory.

Installation

npm install -g @devgateway/upgrade-wp-customizer
# or
yarn global add @devgateway/upgrade-wp-customizer
# or
pnpm add -g @devgateway/upgrade-wp-customizer

Usage

Navigate to the root of your WordPress Customizer project and run:

npx @devgateway/upgrade-wp-customizer

Options

• --force
  Proceed even if your git directory has uncommitted changes.

What does it do?

• Backs up your project (creates a backup directory with a timestamp).
• Checks for uncommitted git changes (unless --force is used).
• Prompts for confirmation before making changes.
• Copies template files (from the package's template/ updated directory) into your project, including:
  • blocks/ directory with a modern block setup (JS, PHP, CSS, Webpack config, etc.)
  • Updated index.php and other supporting files.
• Transforms your source files:
  • Updates import paths for commons and icons to use @devgateway/dvz-wp-commons.
  • Replaces process.env.BLOCKS_NS and process.env.BLOCKS_CATEGORY with direct imports.
  • Converts CommonJS require statements in blocks/index.js or index.jsx to ES imports.
• Deletes unused files.
• Prompts you to install dependencies in the new blocks directory (supports npm, yarn, pnpm, or skip).
• Cleans up the backup if migration is successful.

After Migration

• Your project will have a new blocks/ directory with a modern block setup.

• All relevant imports will use @devgateway/dvz-wp-commons.

• You may need to review and test your project to ensure everything works as expected.

• If you skipped dependency installation, run the following in the blocks/ directory:

  npm install
  npm install @devgateway/dvz-wp-commons
  # or use yarn/pnpm as appropriate
  

Template Structure

The template includes:

• blocks/
  • index.php – Registers the block and enqueues scripts/styles.
  • webpack.config.js – Webpack config for block JS.
  • package.json – With recommended dependencies and scripts for block development.
  • editor.css, style.css – Editor and frontend styles.
• index.php – Main entry for the plugin.

Safety & Rollback

• If you cancel during the migration, your original project is restored from backup.
• If anything goes wrong, you can manually restore from the backup directory created at the start of the process.

Requirements

• Node.js v20+ recommended.
• Your project should be under git version control for safety checks.

License

MIT