ForgeWP

Contribution Guidelines & Testing

Step-by-step contribution workflows, local setup, test execution, template synchronization, and pull request requirements for ForgeWP.

We welcome contributions to ForgeWP. Whether you are fixing a compiler edge case, improving data hooks, enhancing CLI generators, or refining documentation, this guide details our development standards, testing workflows, and pull request process.

Flowchart
Rendering diagram...

1. Getting Started Locally

Prerequisites

Ensure your development machine meets these requirements before cloning:

  • Node.js: Match the installed dependency engines. For current compiler dependencies, use 22.18+ in the 22.x line or 24.11+ in the 24.x line; see System Requirements.
  • PNPM: v9.0.0 or higher (npm install -g pnpm).
  • Git: Installed and configured.

Fork & Clone

Terminal
# Clone your fork
git clone https://github.com/<your-username>/forgewp.git
cd forgewp

# Install dependencies across all workspace packages
pnpm install

# Start the local development testbed
pnpm dev

The dev server will boot packages/starter at http://localhost:5173. Any changes made inside packages/react/src or packages/compiler/lib will trigger instant Hot Module Replacement (HMR).

2. Testing Workflows

ForgeWP enforces strict automated testing and manual verification before merging changes.

Automated Test Suites

Run the compiler adapter and runtime test suites:

Terminal
# Run adapter contract and typing tests
pnpm test:compiler-adapters

# Test create-forgewp interactive scaffolder
pnpm test:create

# Test create-forgewp HTML adapter scaffolder
pnpm test:create-html

To run package-specific test suites using Vitest:

Terminal
# Run compiler unit tests
cd packages/compiler
pnpm test

Production Export Testing

Whenever you modify @forgewp/compiler or @forgewp/react, you must verify that the production export pipeline completes cleanly:

Terminal
# Run production export in the testbed
pnpm export

Inspect the generated output in packages/starter/.forgewp/out/:

  1. Check that style.css contains correct theme headers.
  2. Check that theme.json contains valid v3 JSON syntax.
  3. Check that functions.php properly enqueues styles and scripts without PHP syntax errors.
  4. Verify that generated templates (index.php, single.php, archive.php) produce valid PHP tags.

Verification in Live WordPress

For runtime changes (e.g. hydration islands, Gutenberg blocks, form endpoints), test the exported theme in a local WordPress environment (such as LocalWP, WordPress Studio, or Docker):

Terminal
# Install and activate the exported theme using WP-CLI
wp theme install packages/starter/.forgewp/out/*.zip --activate

Verify:

  • Theme activates without PHP errors or warnings.
  • The homepage and subpages render without White Screen of Death (WSOD).
  • Custom Gutenberg blocks appear in the editor inserter and save without block validation errors.
  • Client hydration islands activate upon their designated trigger conditions.

3. Starter Template Synchronization

When users scaffold a new project with npm create forgewp@latest, the CLI copies files from packages/create-forgewp/template/.

To ensure the published template stays synchronized with the canonical testbed in packages/starter/, you must run the template sync script after editing starter files:

Terminal
pnpm sync:template

If you modified the HTML adapter template (packages/html-starter/), run:

Terminal
pnpm sync:template-html
Important

Never edit files in packages/create-forgewp/template/ directly. Always make changes in packages/starter/ and execute pnpm sync:template. The sync script automatically normalizes workspace dependencies and preserves template-specific .gitignore rules.

4. Coding Standards & Conventions

TypeScript Strictness

  • All framework code in @forgewp/react and framework interfaces must be strictly typed.
  • Avoid using any where explicit generic constraints or union types are possible.
  • All code must pass type checking with zero errors:
Terminal
pnpm typecheck

Zero Runtime Overhead in @forgewp/react

  • @forgewp/react is designed to be a lightweight data bridge, not a heavyweight monolithic framework.
  • Avoid adding third-party dependencies to packages/react/package.json.
  • Keep bundle size minimal: functions intended for compile-time AST translation must compile cleanly with 0 KB client footprint.

WordPress PHP Safety & Escaping

When authoring compiler PHP generators in packages/compiler/lib/:

  • Always escape dynamic output using WordPress escaping functions:
    • Text: esc_html() or esc_html__()
    • HTML attributes: esc_attr() or esc_attr__()
    • URLs: esc_url()
    • Post body content: wp_kses_post() or the_content()
  • Always sanitize submitted user input with sanitize_text_field(), sanitize_email(), or sanitize_textarea_field().
  • Use WordPress nonce verification (check_ajax_referer or REST permission callbacks) on sensitive endpoints.

Documentation Standards

  • Zero Emojis: Do not use emojis in documentation markdown files or error messages.
  • Code Block Titles: Always include a title="..." attribute on fenced code blocks (e.g. tsx title="src/components/Card.tsx").
  • Clickable File Links: Use GitHub-style markdown file links with the file:// scheme when referencing local files.

5. Pull Request & Release Process

Branch Naming Conventions

Create a descriptive branch for your work:

  • feat/feature-name: New features or capabilities.
  • fix/issue-description: Bug fixes or edge-case corrections.
  • docs/topic-name: Documentation additions or revisions.
  • refactor/component-name: Code refactoring without behavior changes.

Pre-PR Checklist

Before opening a pull request, run the following verification sequence:

Terminal
# 1. Typecheck all workspace packages
pnpm typecheck

# 2. Compile all packages
pnpm build

# 3. Run adapter tests
pnpm test:compiler-adapters

# 4. Sync starter template (if starter files were modified)
pnpm sync:template

# 5. Run testbed export
pnpm export

Submitting Your Pull Request

  1. Push your branch to your fork on GitHub.
  2. Open a Pull Request against the main branch of forgewp.
  3. Provide a clear description detailing:
    • Context: What problem does this PR solve?
    • Changes: Summary of modifications made across packages.
    • Testing: How was this change tested and verified?
  4. Link any related GitHub issues using keywords (e.g. Closes #42).

Documentation Complete

Congratulations! You have completed the comprehensive documentation suite for ForgeWP. Return to the Documentation Overview to explore any topic or start building modern React-powered WordPress themes.

Package entry points

Keep the types condition first in each conditional package export, followed by the runtime conditions. Preserve the existing root and @forgewp/react/config targets when updating metadata. Run the React package export regression checks in the compiler tests to verify TypeScript consumer resolution and warning-free browser bundling.