DOCSEARCHbyAlgolia
Submit Docs

wpm Package Manager

website·Indexed 31 days ago

https://wpm.so/docs

An open source package manager for WordPress plugins and themes, built in Go for performance and reliability. It provides a CLI for managing dependencies via wpm.json and wpm.lock, supporting package installation, publishing to the wpm registry, and CI/CD integration.

Tokens
16.7K
Snippets
89
Records
143
Agent score
50%

What's inside wpm

  1. Overview of wpm package manager

    wpm is a native package manager for WordPress that treats plugins and themes as first-class packages. It provides a standardized workflow for installing, updating, and auditing dependencies, replacing fragmented methods like manual ZIP downloads, shell scripts, or Git submodules. Key features include a dedicated registry with a strict metadata schema (wpm.json), cryptographic verification of packages via SHA-256 digests, and a standalone Go binary that operates independently of the PHP runtime.

  2. Overview of wpm package manager

    wpm is an open-source package manager for WordPress plugins, themes, and mu-plugins. Built in Go, it provides reproducible installs via a wpm.lock file, automatic dependency resolution, and built-in package integrity and supply chain security checks. It uses a globally distributed registry powered by Cloudflare Workers.

  3. Overview of the wpm package manager

    wpm is a package manager for the WordPress ecosystem that treats plugins, themes, and must-use plugins as versioned packages. It follows a model similar to npm or Composer. A project is defined by the presence of a wpm.json manifest file. By default, installed packages are placed in the wp-content/ directory.

  4. Manage wpm registry sessions with wpm auth

    wpm auth is a group of subcommands used to manage your session with the wpm registry. Once authenticated, other registry-dependent commands (such as install, publish, whoami, and outdated) automatically reuse the stored token. Typically, wpm auth login only needs to be run once per machine.
    # Log in to the registry
wpm auth login

# Log out from the registry
wpm auth logout

  5. Understand the purpose and usage of wpm.lock

    wpm.lock records the exact dependency tree resolved for a project to ensure identical installs across different machines and CI environments. When running wpm install, the tool reads the lockfile first; if the requested versions in wpm.json match the lockfile, wpm skips the registry and installs directly from the lockfile. To ensure reproducibility, wpm.lock must be committed to version control.

  7. Specify package versions and tags during installation

    When adding packages via wpm install, you can use different specifier forms. Note that wpm pins the exact version resolved by the registry into wpm.json to ensure identical installs across environments.
    # Install latest version (resolved to a strict version in wpm.json)
wpm install name

# Install a strict SemVer version (X.Y.Z, no 'v' prefix)
wpm install name@1.7.2

# Install using a registry dist tag
wpm install name@beta

  8. Define package runtime requirements with `requires`

    The requires block in wpm.json specifies the minimum WordPress and PHP versions a package needs to function. These are SemVer constraint strings used by consumers to determine if their host environment is supported. By default, these are informational and not enforced by wpm unless the consumer has enabled strict runtime mode via config.runtime.
    {
  "requires": {
    "wp": ">=6.0",
    "php": ">=7.4 <8.4"
  }
}

  9. Enable strict runtime mode with `config.runtime`

    Set config.runtime in wpm.json to declare the specific WordPress and PHP versions your project is developed and tested against.

    Adding this block enables strict runtime mode: during wpm install, the tool checks the requires field of every dependency against these concrete versions. If a dependency's requirement is not satisfied by the runtime version, the installation will fail.

    Use this mode to catch dependencies that bump minimum versions in CI or to ensure a long-term-support branch doesn't drift.

    {
  "config": {
    "runtime": {
      "wp": "6.9",
      "php": "8.2"
    }
  }
}

  10. Initialize a new wpm project and install dependencies

    To start a new WordPress project with wpm, create a directory, initialize the project manifest, and install the desired plugins or themes. wpm downloads packages into the wp-content/plugins/ directory and records exact versions in wpm.lock for reproducibility.
    # Create and enter project directory
mkdir my-wp-project
cd my-wp-project

# Initialize project
wpm init -y

# Install specific plugins
wpm install akismet hello-dolly

# Inspect the dependency tree
wpm ls

  11. Troubleshoot wpm ls errors

    Common issues when running wpm ls:

    • no wpm.json found, so nothing to list: Ensure you are in the project root or run wpm init.
    • no wpm.lock found, you need to run 'wpm install' first: The lockfile is missing; run wpm install to generate it.
    • no dependencies found in wpm.json: No dependencies or devDependencies are declared in wpm.json.
    • UNMET DEPENDENCY appears: This usually happens after manually editing wpm.json. Run wpm install to synchronize the lockfile.

  12. Adopt wpm in an existing WordPress project

    Use the --existing flag to generate a wpm.json file by extracting metadata from an existing plugin or theme.

    Detection Logic:

    • Type: If style.css exists, it is marked as a theme; otherwise, it is a plugin.
    • Themes: Headers are parsed from style.css.
    • Plugins: All .php files in the directory are scanned for valid plugin headers.
    • Readme: If readme.txt (WordPress.org format) is present, its metadata is merged in, and a readme.md is automatically created if one does not exist.

    Extracted Fields:

    • name: Current directory name.
    • version: From plugin/theme headers.
    • description & license: From headers, falling back to readme.txt.
    • homepage: From Plugin URI or Theme URI.
    • team: From Author header or readme.txt Contributors.
    • requires.wp & requires.php: From headers and readme.txt.
    • dependencies: From Requires Plugins header (pinned to *).
    # Basic adoption
wpm init --existing

# Adoption with specific overrides
wpm init --existing --name corporate-theme --version 2.0.0 --license MIT