Skip to content

initialization.md

Latest commit

 

History

History
125 lines (91 loc) · 7.77 KB

initialization.md

File metadata and controls

125 lines (91 loc) · 7.77 KB
Raw

Initialize and manage the plugin

npm run init turns the skeleton into a named plugin and records your choices; later runs manage identity and optional features. It is a thin wrapper (bin/init.js) around the shared init engine in @rtcamp/wp-tooling, configured by bin/scaffold.config.js.

Before init

Install dependencies first (see Getting Started); the engine lives in node_modules/@rtcamp/wp-tooling. Then confirm the working tree is clean:

git status --short

Init rewrites and deletes files in place. A clean checkout is your only undo.

CLI or AI

Entry point Role
npm run init The interactive wizard (or flags for a scripted run).
/init Claude Code skill (Copilot: .github/prompts/init.prompt.md). Installs dependencies with your consent, runs the same wizard, and can hand a feature brief to /scaffold.
/scaffold Adds features after personalization; see Scaffolding.
/setup Generic tooling bootstrap for other projects. It is not a personalization path for this skeleton.

What the wizard asks

  1. Confirm setup and name the plugin. A first run has no .wp-scaffold.json, so init starts in setup mode.

  2. Review identity. Accept the derived values or edit any field before applying. For Acme Content, the review screen shows:

    Field Value
    Plugin Name Acme Content
    Version 1.0.0 by default
    Text Domain acme-content
    Package rtcamp/acme-content-features
    Namespace Acme_Content\Features (tests: Acme_Content\Features\Tests)
    Function Prefix acme_content_
    Constant Prefix ACME_CONTENT

    .wp-scaffold.json stores these values. The generated code adds -features: plugin header Acme Content Features, text domain acme-content-features, prefixes acme_content_features_ and ACME_CONTENT_FEATURES_, and main file acme-content-features.php.

  3. Select capabilities. One grouped prompt lists the twelve example sets, the CI workflow and the three optional features. Space toggles, Enter confirms. Unchecking an example set removes it entirely.

  4. Apply. Init rewrites the tokens, removes deselected sets, writes .wp-scaffold.json, and regenerates the Composer autoloader. The wrapper then runs npm run sync-ai.

  5. Git and hooks. A first run can start a new Git repository. This defaults to No; accepting deletes the existing .git and the skeleton's history, so decline it when keeping that history or working inside another repository. Non-interactive --yes skips optional Git setup.

Defaults: every example set kept, HMR on, Tailwind and Dev Tools off.

For a scripted first run:

npm run init -- --name="Acme Content" --version=1.0.0 --yes \
  --remove-examples=blocks,shortcodes,cli,cron,settings,admin,roles,cache,transients

Capability keys

Category Example-set keys (keep/remove once) Optional feature keys (toggle any time)
Content post-types, taxonomies
Editor & Front-end blocks, shortcodes tailwind
APIs & Automation rest, cli, cron
Admin settings, admin, roles
Utilities cache, transients
Developer Tooling test-measure (the CI caller workflow) hmr

What each set contains is listed in Included features.

What changes

Area Result
Identity Project Name / project-name / Project_Name / PROJECT_NAME tokens are replaced across source, config, tests and docs. The main file is renamed.
Version Written to the main file's header and package.json.
Removed example sets The module file (inc/Modules/<Module>.php), its folder, its test (tests/php/<Module>Test.php), its Main::CLASSES line and any coupled region (for example the static block list in inc/Core/Assets.php for blocks, the unschedule call in inc/Core/PluginSetup.php for cron).
Kept example sets Stay as working references. Their // wp:example:<key> markers are removed.
Optional features hmr edits .env.local; tailwind adds src/css/tailwind.css, postcss.config.js, dependencies and flips the Tailwind constant.
State .wp-scaffold.json records identity and feature choices. Do not edit it by hand.
Cleanup Nothing is removed. Copilot files, workflows and templates under .github/ stay.
AI instructions sync-ai refreshes .github/instructions/framework-php.instructions.md from the installed framework.

Init does not generate a translation template. Run npm run pot when preparing translations.

Review the result

  1. Run npm run init -- --list and confirm the kept sets and feature states match your choices.
  2. Inspect the main plugin file, composer.json, package.json and .wp-scaffold.json for the resolved name, namespace, prefixes and version.
  3. Review git status and the diff: removed sets should be gone from inc/Modules/, tests/php/ and Main::CLASSES.
  4. Start WordPress and confirm the plugin activates and the kept examples load.

Follow any dependency instructions init prints, run composer update --lock (the package was renamed), then make a baseline commit.

Change things later

Identity edits and optional-feature toggles are repeatable. Example removal is a one-time setup decision: its markers are consumed, so a later run can neither restore a removed set nor safely remove another one. To remove a set later, delete its module, classes, test and Main::CLASSES line by hand. To add functionality, use Scaffolding.

Bare npm run init on an initialized project opens manage mode. Useful commands:

npm run init -- --list                   # read-only status
npm run init -- --list --json            # one machine-readable line
npm run init -- --enable=tailwind --yes  # change one feature
npm run init -- --disable=hmr --yes
npm run init -- --features=hmr --yes     # set the exact enabled set
npm run init -- --help                   # options for your installed engine

--features replaces the whole enabled set; --enable and --disable change one feature at a time. Do not combine them. For JSON without npm's banner, run node bin/init.js --list --json. Do not use --reinit to restore examples.

Optional dependencies

  • HMR: toggling only flips ENABLE_HMR in .env.local, a per-developer file. See Live reload.
  • Tailwind: enabling changes declarations and adds files; run npm install afterwards. See Tailwind.

Troubleshooting

Symptom Check and next action
Could not load the init engine Dependencies are not installed. Run npm install from the plugin root and confirm node_modules/@rtcamp/wp-tooling exists.
Option rejected Run npm run init -- --help; flags differ between setup and manage mode.
--name/--version ignored The project is already set up, so init is in manage mode. Edit identity through bare npm run init.
Interrupted or partial setup Inspect the diff and .wp-scaffold.json. Restore the pre-init checkout if needed; do not blindly rerun a destructive setup.
Feature enabled but package missing A declaration is not an installed package. Run the npm install or composer update command init printed.
An example set is missing Run npm run init -- --list. If it was removed, recover it from a clean skeleton checkout; manage mode cannot restore consumed markers.
init succeeded but sync-ai failed Run composer install, then npm run sync-ai.

Generic engine behaviour is documented upstream in wp-tooling; use the local --help output for your installed revision.