Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
84 lines (58 loc) · 3.9 KB

CONTRIBUTING.md

File metadata and controls

84 lines (58 loc) · 3.9 KB
Raw

Contributing to Kadence Blocks

This guide covers how to set up the plugin for local development and build it from source.

Prerequisites

  • PHP 7.4+ and Composer — for PHP dependencies (managed with Strauss for namespace prefixing).
  • Bun — for JavaScript dependencies and build scripts. This project has migrated from npm to Bun.
  • A GitHub Personal Access Token — required to install the @stellarwp-scoped package, which is hosted on GitHub Packages rather than the public npm registry.

1. Create a GitHub auth token

The @stellarwp scope resolves to GitHub Packages (npm.pkg.github.com), which requires authentication. See bunfig.toml for the scope configuration.

  1. Create a classic Personal Access Token at https://github.com/settings/tokens/new with the read:packages scope.

  2. Create a .env file in the root of the plugin and add your token:

    BUN_AUTH_TOKEN=your_token_here
GITHUB_TOKEN=your_token_here

    Bun reads BUN_AUTH_TOKEN from this .env file when authenticating to the @stellarwp registry. GITHUB_TOKEN (the same token works) authenticates the github:stellarwp/... tarball fetches for the @kadence/* packages — without it those downloads hit GitHub's unauthenticated rate limit and fail with 504s. Do not commit .env.

2. Install PHP dependencies

composer install

This installs Composer packages and runs the Strauss post-install steps that prefix vendor namespaces into vendor/vendor-prefixed/.

Note: Never edit files in vendor/vendor-prefixed/ directly — they are regenerated on every composer install.

3. Install JavaScript dependencies

Migrating from a previous npm build? If you've built this plugin with npm before, delete the existing node_modules directory first so Bun installs cleanly:

rm -rf node_modules
bun install

The postinstall step builds the @kadence/* packages (helpers, icons, components) automatically.

Why this build step exists: The @kadence/* packages are pulled directly from GitHub (see the github:stellarwp/... entries in package.json), and those repos ship source only — not the compiled dist/ output that Kadence Blocks imports. So after install they must be transpiled with Babel. The build:packages script does this, but only for packages whose dist/cjs/index.js is missing (already-built packages are skipped).

The script uses npm install --omit=prod rather than bun install for this one step on purpose: @kadence/helpers declares @kadence/icons as a production git dependency, and a full install would try to git-clone it (which fails / rate-limits in CI). --omit=prod installs only the Babel devDependencies needed to transpile and skips that git dependency entirely.

4. Build the assets

For active development (webpack watch + gulp watch, run concurrently):

bun run start

For a one-off production build:

bun run build

Useful scripts

Command Description
bun run start Watch mode — rebuilds JS/CSS on change
bun run build Production build (wp-scripts build + gulp build)
bun run build-wp Webpack build only
bun run build-gulp Gulp build only (legacy JS/CSS)
bun run lint-js Lint JavaScript
bun run lint-js-fix Lint and auto-fix JavaScript
bun run format Format source files
composer lint PHP CodeSniffer
composer phpstan PHP static analysis

Troubleshooting

  • 401 Unauthorized on bun install — your BUN_AUTH_TOKEN is missing, expired, or lacks the read:packages scope. Confirm .env exists in the plugin root and the token is valid.
  • @kadence/* imports fail during the build — re-run bun install so the postinstall step rebuilds the local packages, and verify the node_modules/@kadence/* directories were fetched.