@pugpigjs/create-wp-project

CLI tool to scaffold WordPress plugins and themes from a template repo.

Quick Start

The easiest way to scaffold a new WordPress project:

npm create @pugpigjs/wp-project -- init --git-url <repository-url> --directory <target-directory>

Note: Both --git-url and --directory are required for all commands.

How It Works

This CLI tool uses a placeholder-based templating system to scaffold WordPress projects:

1. Clone template - Fetches the template repository
2. Interactive prompts - Asks for namespace, project name, and description
3. Placeholder replacement - Automatically replaces TPL_*/tpl_* and pkg_* markers in all template files
4. Generate config - Creates a customised docker-compose.yml for your project
5. Validation - Ensures naming conventions and prevents common mistakes

Template Placeholders

The template uses case-insensitive placeholder markers throughout all files. You can use either uppercase (TPL_*) or lowercase (tpl_*) variants. For JSON files or schemas that require lowercase keys, simply use the lowercase form.

| Placeholder | Example Value | Description | |----------------------------------|-------------------------------|--------------------------------------------------------------------| | TPL_NAMESPACE | Pugpig | Namespace in PascalCase | | TPL_NAMESPACE_LOWER | pugpig | Lowercase namespace | | TPL_PROJECT_NAME | my_plugin | Project name in snake_case | | TPL_PROJECT_NAME_PASCAL | MyPlugin | Project name in PascalCase | | TPL_PROJECT_NAME_SLUG | my-plugin | Project name in kebab-case (for NPM/URLs) | | TPL_PROJECT_NAME_FLAT | myplugin | Project name with no separators | | TPL_FULL_PROJECT_NAME | pugpig_my_plugin | Full project name with namespace (snake_case) | | TPL_FULL_PROJECT_NAME_SLUG | pugpig-my-plugin | Full project name in kebab-case | | TPL_FULL_PROJECT_NAME_TITLE | Pugpig My Plugin | Full project name in Title Case | | TPL_FULL_PROJECT_NAME_UPPER | PUGPIG MY PLUGIN | Full project name in UPPERCASE | | TPL_DESCRIPTION | A human-readable description| Human-readable description | | pkg_* (wildcard) | pkg_example_theme → pugpig-my-theme | Any package name starting with pkg_ gets replaced with the full project name slug |

Use lowercase keys for compatibility with JSON schemas or config files that require them.

Usage Examples:

// PHP - uppercase convention
namespace TPL_NAMESPACE\TPL_PROJECT_NAME_PASCAL;

// composer.json - lowercase convention
"name": "tpl_namespace_lower/tpl_project_name_flat"

// package.json - wildcards
"name": "pkg_example_theme"  // becomes "pugpig-my-theme"

The CLI automatically computes all these variations from your namespace and project name inputs.

Commands

init - Initialise a New Project

npm create @pugpigjs/wp-project -- init --git-url <repository-url> --directory <target-directory>

This interactive CLI will:

1. Clone the template repository
2. Let you choose between Rich Plugin, Simple Plugin, or Theme templates
3. Prompt for namespace (e.g., "Pugpig"), project name (e.g., "my_plugin"), and description
4. Validate inputs (prevents namespace duplication, ensures snake_case format)
5. Copy configuration files to your directory
6. Generate a customised docker-compose.yml
7. Replace all TPL_*/tpl_* and pkg_* markers throughout the project with computed values

add - Add Another Template to Existing Project

If you've already initialised a project and want to add another plugin or theme:

npm create @pugpigjs/wp-project -- add --git-url <repository-url> --directory <target-directory>

This will:

1. Clone the template repository
2. Let you choose which template to add
3. Prompt for namespace, project name, and description
4. Validate inputs and replace all placeholders
5. Copy the template to a new directory (e.g., namespace_project_name)
6. Update your docker-compose.yml with the new service

remove - Remove a Template from Project

To remove a plugin or theme from your project:

npm create @pugpigjs/wp-project -- remove --directory <target-directory>

This will:

1. Show you a list of existing projects in the directory
2. Ask you to confirm the removal
3. Remove the service from docker-compose.yml (with backup)
4. Delete the project directory

Note: This action cannot be undone. A backup of docker-compose.yml is created automatically.

update - Update Root Configuration Files

To refresh configuration files (like bitbucket-pipelines.yml, renovate.json, etc.) from the latest template:

npm create @pugpigjs/wp-project -- update --git-url <repository-url> --directory <target-directory>

This will:

1. Clone the latest template repository
2. Show you a list of available root configuration files
3. Let you select which files to update
4. Optionally create backups (.backup) of existing files before updating
5. Copy the selected files from the template

This is useful when:

• The template's pipeline configuration has been updated
• New ESLint rules or TypeScript configs are available
• Renovate configuration has changed
• You want to sync with the latest best practices

CLI Options

All commands (init, add, and update) require:

• -g, --git-url <url> - Git repository URL or local path to the template

  • Can be set via environment variable PUGPIG_WORDPRESS_TEMPLATE_REPO_URL to avoid passing it every time
  • Example: https://github.com/user/wp-template.git
  • Example: /path/to/local/template
  • Example: . (current directory for local development)

• -d, --directory <path> - (Required) Target/project directory

  • Must end with -server for safety (e.g., my-project-server)
  • Example: ./my-project-server
  • Example: /absolute/path/to/project-server

Optional:

• -t, --template-dir <path> - Template source directory within the repository (defaults to repo_template)
• -b, --branch <name> - Git branch to clone from (defaults to master)

Environment Variables

You can set the following environment variable to simplify usage:

• PUGPIG_WORDPRESS_TEMPLATE_REPO_URL - Default git repository URL
  • When set, the -g, --git-url flag becomes optional
  • Add to your shell config (~/.zshrc or ~/.bashrc):

    export PUGPIG_WORDPRESS_TEMPLATE_REPO_URL=https://github.com/your-org/your-wp-template.git

  • After setting, you can omit the -g flag:

    npm create @pugpigjs/wp-project -- init -d ./my-project-server

Examples

Initialise from a remote repository

npm create @pugpigjs/wp-project -- init \
  -g https://github.com/your-org/your-wp-template.git \
  -d ./my-project-server

Initialise from a local template (for development)

npm create @pugpigjs/wp-project -- init -g . -d ./test-server

Initialise from a specific branch

npm create @pugpigjs/wp-project -- init \
  -g https://github.com/your-org/your-wp-template.git \
  -d ./my-project-server \
  -b beta

Add another template to existing project

npm create @pugpigjs/wp-project -- add \
  -g https://github.com/your-org/your-wp-template.git \
  -d ./my-project-server

Update configuration files

npm create @pugpigjs/wp-project -- update \
  -g https://github.com/your-org/your-wp-template.git \
  -d ./my-project-server

Safety Features

This CLI tool includes multiple safety checks to prevent accidental data loss:

• ✅ Directory validation - Target directory must end with -server
• ✅ System directory protection - Blocks operations in /, /usr, /etc, home directory, etc.
• ✅ Sandboxed operations - Temporary files only created within project directory
• ✅ Backup creation - Creates .backup files before modifying docker-compose.yml
• ✅ File comparison - Only updates files that have actually changed
• ✅ Project directory check - Won't overwrite existing project directories

Requirements

• Node.js 24 or higher
• A directory ending with -server (e.g., my-project-server)

Template Types

• Rich Plugin: A full-featured plugin template with Vue.js, SCSS, and an advanced build setup. Includes Vite build system with hot module replacement (HMR), Vue.js component support, SCSS preprocessing, Composer dependencies managed with PHP-Scoper, and utilities for seamless WordPress integration.

• Simple Plugin: A lightweight plugin template with a simple Vite build setup, vanilla JavaScript, basic CSS, and minimal dependencies.

• Theme: A WordPress theme template with a modern Vite-based build system, supporting modern CSS/JS compilation and a standard theme template structure.

Development

For local development and testing from within this repository:

# From the repository root
node packages/create-wp-project/src/cli.js init -g . -d ./test-server

# Or test the add command
node packages/create-wp-project/src/cli.js add -g . -d ./test-server

# Or test the update command
node packages/create-wp-project/src/cli.js update -g . -d ./test-server

# Test with a specific branch
node packages/create-wp-project/src/cli.js init -g . -d ./test-server -b beta

License

ISC