WPKernel config reference
Every WPKernel project begins with this file. You describe what your product should do. The CLI reads that intent and emits production artefacts in PHP, TypeScript, and UI.
This page has two parts:
- Guide: short, linear sections that show how each field affects builders and artefacts.
- Appendix: the complete schema reference with exact field semantics.
A machine-readable schema lives alongside this guide as wpk-config.schema.json. Use it with Ajv, VS Code, or other tooling to lint your config before running wpk generate.
Guide: The anatomy of wpk.config.ts
1. Here's a minimal but valid config
import type { WPKernelConfigV1 } from '@wpkernel/cli/config';
export const wpkConfig: WPKernelConfigV1 = {
version: 1,
namespace: 'acme-demo',
schemas: {},
resources: {},
adapters: {},
};What this does The version property locks behaviour to a known schema, namespace sets PHP class roots, REST base, and client store prefixes. This is how parity between PHP & JS is ensured. Empty registries are perfectly valid but builders only generate assets when these are filled out. Add an optional meta block to override the generated plugin.php header (plugin name, description, text domain, etc.).
Tip
- In WPKernel, a builder generates files for use in the project.
- You can rename namespace later and generated paths and symbol names will move with it.
2. A resource with real routes and WP Capability checks
resources: {
job: {
name: 'job',
routes: {
list: { path: '/acme/v1/jobs', method: 'GET', capability: 'job.list' },
get: { path: '/acme/v1/jobs/:id', method: 'GET', capability: 'job.get' },
create: { path: '/acme/v1/jobs', method: 'POST', capability: 'job.create'},
},
capabilities: {
'job.list': 'read',
'job.get': 'read',
'job.create': { capability: 'edit_posts', appliesTo: 'resource' },
},
},
},What builders do The route planner records list, get and create. PHP builders then generate RESTful controllers with permission callbacks and JS builder emits a typed API client with fetchList, fetch and create. This is a brief overview. For a deep dive into these concepts, see the canonical guides: - Resources Guide - Capabilities Guide
What you get
.generated/php/Rest/JobController.php.generated/js/resources/job.ts.generated/js/capabilities.ts
Tip
- If a
capabilityis missing, the CLI warns but still appliesmanage_optionsfor that route, so that built assets remain valid with some sane defaults while you finish the map.
This only scratches the surface of what WPKernel infers from the config today. In the appendix below, we list the full range of options driven entirely by the config file.
Top-level decision matrix
| Path | Accepted values & defaults | CLI & pipeline consumers | Generated files | WordPress artifacts | Runtime usage |
|---|---|---|---|---|---|
$schema | Optional URI string. | Ignored by builders; for editor/tooling hints only. | - | - | - |
version | Literal 1. Required. Only 1 is supported today. | Validated when loading configs; selects the config schema and IR version. | - | - | Guards against mismatched CLI/config schema versions; future versions will use a different literal. |
namespace | Required slug string (lowercase, 3-50 chars). Invalid chars are sanitised rather than inferred. | Normalised during validation and reused by all builders. | Namespacing is applied to every emitted file path. | Prepended to PHP class namespaces and REST route namespaces. | Prefix for store keys, capability registries, and reporter labels. |
schemas | Required record of schema descriptors keyed by identifier. May be empty ({}), but the property itself must exist. | Loaded into the IR and reused by PHP + UI builders. | Schema JSON is re-serialised into REST argument metadata or stored for future emitters. | Informs REST controller validation and future storage/type builders. | Schema provenance exposed on ResourceObject so clients can introspect which schema a resource uses. |
resources | Required record of resource descriptors keyed by identifier. | Feeds every builder (PHP, TS, JS) via the IR. | Routes, capability helpers, UI fixtures, storage registries, etc. | Registers REST routes, persistence helpers, and admin menus when configured. | Creates strongly typed resource clients, stores, and capability unions. |
resources.<key>.blocks | Optional per-resource block config. Defaults to JS-only derivation (mode: 'js'). | Consumed by JS + PHP block builders via the IR. | .generated/blocks/** (canonical) mirrored to src/blocks/**, plus build/blocks-manifest.php, Blocks/Register.php, render.php for SSR mode. | Registers Gutenberg blocks (JS or SSR) and enqueue helpers. | Controls whether the derived block renders client-only ('js') or with SSR ('ssr') for SEO/editor fidelity. |
adapters | Optional object. | Adapter factories hook into the generation pipeline. | Adapter-specific artefacts. | Custom PHP writers or extensions may register WordPress code. | Extensions can mutate IR before runtime surfaces are built. |
adapters.php | Factory returning namespace/autoload overrides and optional customise callback. | Consumed by the PHP builder before writing files. | Overrides .generated/php defaults and can inject extra PHP files. | Controls PHP namespace roots and AST customisation. | - |
adapters.extensions | Array of factories returning pipeline extensions. | Resolved before generation starts and executed during the run. | Whatever the extension queues. | Can register additional WordPress code (blocks, controllers, etc.). | Extensions can augment runtime metadata or emit extra JS files. |
directories | Optional map of applied layout IDs → paths. Keys include blocks, blocks.applied, controllers, controllers.applied, plugin, plugin.loader. | Used by apply to route generated artefacts into custom directories. | Applied artefacts land where configured (e.g. into src/); .wpk/** remains the canonical generation root. | N/A (affects apply destinations only; does not change what WordPress registers by default). | N/A |
meta | Optional plugin metadata: name, description, version, requiresAtLeast, requiresPhp, textDomain, author, authorUri?, pluginUri?, license, licenseUri?. Defaults derive from the namespace. | Normalised into IR meta and forwarded to PHP plugin loader builders. | plugin.php header (AST) and related metadata. | WordPress plugin header fields used by the generated loader. | Controls what site admins see in the Plugins list and future packaging metadata. |
readiness | Optional object configuring DX readiness helpers. | Factories under readiness.helpers are resolved when the CLI builds the readiness registry. | Custom helpers join the readiness plan alongside core checks. | wpk doctor and command readiness automatically pick up helper labels and scopes without editing CLI sources. | Metadata drives readiness status summaries and scope filtering during command execution. |
Plugin metadata (meta)
| Path | Accepted values & defaults | WordPress/CLI impact |
|---|---|---|
meta.name | Optional string; defaults to the namespace in title case. | Shown as “Plugin Name” in the generated loader header. |
meta.description | Optional string; defaults to “Bootstrap loader for the <name> WPKernel integration.” | Fills the plugin description block in plugin.php. |
meta.version | Optional string; defaults to 0.1.0. | Version printed in the plugin header. |
meta.requiresAtLeast | Optional string; defaults to 6.7. | Populates “Requires at least” in the plugin header. |
meta.requiresPhp | Optional string; defaults to 8.1. | Populates “Requires PHP” in the plugin header. |
meta.textDomain | Optional string; defaults to the sanitized namespace. | Used as the translation domain in the plugin header. |
meta.author | Optional string; defaults to “WPKernel Contributors”. | Writes the Author line in the plugin header. |
meta.authorUri | Optional string. | Prints the Author URI when provided. |
meta.pluginUri | Optional string. | Prints the Plugin URI when provided. |
meta.license | Optional string; defaults to GPL-2.0-or-later. | Writes the License line in the plugin header. |
meta.licenseUri | Optional string. | Prints the License URI when provided. |
Readiness orchestration (readiness)
| Path | Accepted values & defaults | CLI & pipeline consumers | Generated files | WordPress artifacts | Runtime usage |
|---|---|---|---|---|---|
readiness | Optional object configuring project-specific DX checks. | Parsed when the CLI assembles the readiness plan. | - | - | Enables projects to plug custom checks into wpk doctor and command readiness gates. |
readiness.helpers | Optional array of factory functions. If omitted/empty, only built-in helpers are executed. | Each factory is resolved once when building the readiness registry. | - | - | Contributes helper entries (id, labels, tags, scopes) to the readiness plan. |
readiness.helpers[] | (ctx) => ReadinessHelper functions exported from wpk.config.ts or imported modules. | Called with the adapter context to produce a helper; errors are reported via logs. | - | Helpers may perform WordPress-specific checks (REST calls, DB checks) without extra wiring. | Active helpers participate in wpk doctor, timing budgets, and command pre-flight checks. |
Schema registry (schemas)
Status: Partially active (storage metadata only) schemas entries are read and stored in the IR today. Their path and description fields are active for metadata and validation. generated.types is reserved for future code emission.
These schemas are not tied to REST controllers or database generation yet. They will power upcoming storage builders and type emitters.
Each schema entry describes how an external JSON Schema file participates in the IR. Schemas can power REST argument validation, UI scaffolding, and future type generation.
| Path | Accepted values & defaults | CLI & pipeline consumers | Generated files | WordPress artifacts | Runtime usage |
|---|---|---|---|---|---|
schemas.<key>.path | Required string path to a JSON Schema file. Resolved relative to the config file or workspace root. | Loaded and hashed when building the IR. | Schema JSON copied into the IR for downstream builders. | REST controllers reuse property metadata for validation. | Schema metadata is attached to resources so clients can introspect. |
schemas.<key>.generated.types | Required string. Future default location for emitted .d.ts. | Stored in the IR for downstream consumers. | (Reserved) No files today; planned for schema-to-TypeScript emission. | - | - |
schemas.<key>.description | Optional human-readable string. | Kept in the IR as documentation. | - | - | - |
Resources can reference a schema by key or ask the CLI to synthesise one when storage metadata is present.
Resource registry (resources)
A resource entry mirrors defineResource() in @wpkernel/core with additional metadata for generators. Every field below maps directly to runtime APIs or emitted artifacts.
Resource summary matrix
Status: Active.
Resource descriptors drive generation today. Where a resource references a schema, that schema influences request validation and typing for that resource only. It never creates database fields and it does not call$wpdb.
| Path | Accepted values & defaults | CLI & pipeline consumers | Generated files | WordPress artifacts | Runtime usage |
|---|---|---|---|---|---|
resources.<key>.name | Optional string; defaults to the map key when omitted. | Normalised into IR resource objects. | Appears in generated filenames and symbol names. | Used for REST route namespaces and PHP class names. | Forms store keys, capability unions, reporter labels. |
resources.<key>.namespace | Optional string override. Defaults to the root namespace. | Applied when assembling IR metadata. | Updates generated paths and module specifiers. | Changes PHP namespace roots for controllers. | Sets the store namespace (namespace/resource). |
resources.<key>.schema | 'auto', a schema key (string), an inline JSON Schema object, or undefined. | Resolved via the schema accumulator when building the IR. | Schema JSON embedded into controller metadata or stored in IR. | REST argument validation derived from schema properties where wired. | Schema key exposed on ResourceObject.schemaKey. |
'auto' asks WPKernel to synthesise/derive a schema from storage metadata where possible. undefined means “no schema”. | Inline objects are hashed and deduplicated automatically. | ||||
resources.<key>.storage | One of the storage shapes below (wp-post, wp-option, wp-taxonomy, transient) or omitted. | Storage helpers influence PHP builders and schema synthesis. | Autoload helpers, persistence registries, capability hints. | Registers CRUD helpers for posts/options/taxonomies/transients. | Storage metadata exposed via ResourceObject.storage. |
resources.<key>.identity | Optional identity descriptor. By default, type is 'number' and param is 'id' for numeric IDs or 'slug' for string IDs. | Normalised into resolved identity info. | Identity guards and cache metadata in PHP controllers. | Enforces ID validation and casting in REST handlers. | Used by runtime helpers when creating cache keys. |
Explicit forms include { type: 'number', param?: 'id' } or { type: 'string', param?: 'id' | 'slug' | 'uuid' }. | |||||
resources.<key>.routes | Partial CRUD route map (list, get, create, update, remove). Required when the resource is exposed over REST. | Drives IR route definitions and capability unions. | REST controller methods, TS clients, capability shims. | Registers REST endpoints with permission callbacks. | Provides typed client methods (fetchList, update, ...). |
resources.<key>.capabilities | Map keyed by routes.*.capability hints. Values may be strings or descriptor objects. | Normalised into the capability map fragment. | .generated/js/capabilities.ts + .d.ts, PHP capability helper. | REST controllers enforce WordPress capabilities before handlers run. | Runtime defineCapability() helpers become strongly typed. |
resources.<key>.queryParams | Optional map of parameter descriptors. | Converted into REST argument metadata. | REST controller arg definitions. | Adds WordPress args validation to route registrations. | Documented on ResourceObject.queryParams. |
resources.<key>.ui | Optional UI metadata (admin/DataViews configuration, etc.). | Enables TypeScript UI builders and PHP menu wiring. | .generated/ui/** fixtures, registry modules, bundler deps. | Registers admin menus + loader glue when menu metadata exists. | Provides UI descriptors on resource.ui?.admin. |
Route definitions (resources.<key>.routes)
| Path | Accepted values & defaults | CLI & pipeline consumers | Generated files | WordPress artifacts | Runtime usage | | ------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------ | ------------------------------------------------------ | ----------------------------------------------------------- | ---------------------------------------------------- | ----------------------------------------------------- | ----------------------------------------------------- | | resources.<key>.routes.list | Optional { path, method: 'GET', capability? }. | Validated and added to IR routes. | REST controller GET collection handler. | Registers GET list route with capability callback. | Enables resource.fetchList() and cache key wiring. | | resources.<key>.routes.get | Optional { path, method: 'GET', capability? }. | Same as above. | REST controller single-item handler. | Registers item GET route. | Enables resource.fetch() + prefetchGet. | | resources.<key>.routes.create | Optional { path, method: 'POST' | 'PUT' | 'PATCH', capability? }. | Warns if capability missing, adds to IR. | REST controller mutation handler. | Registers mutation route and enforces capability map. | Enables resource.create() and invalidation helpers. | | resources.<key>.routes.update | Optional { path, method: 'PUT' | 'PATCH', capability? }. | Same pipeline. | REST controller update handler. | Registers update route with capability enforcement. | Enables resource.update(). | | resources.<key>.routes.remove | Optional { path, method: 'DELETE', capability? }. | Same pipeline. | REST controller delete handler. | Registers delete route with capability enforcement. | Enables resource.remove(). | | resources.<key>.routes.*.path | Required string when the route is present. May include :id, :slug, etc. | Validated, normalised into REST args. | Stored in IR and PHP AST. | Passed to register_rest_route. | Used by runtime client to build request URLs. | | resources.<key>.routes.*.method | Must be one of GET, POST, PUT, PATCH, DELETE. | Validated before IR assembly. | Controls generated controller method scaffolding. | Determines REST callback registration + HTTP verb. | Informs transport calls for runtime client. | | resources.<key>.routes.*.capability | Optional string key. | Added to IR for capability map extraction. | Drives capability helper TypeScript + PHP enforcement. | Binds REST route permission callbacks to capability checks. | Exposed via resource.routes metadata for clients. |
Capability map (resources.<key>.capabilities)
This section details the configuration options for defining capabilities within a resource. For a comprehensive explanation of WPKernel's capability system, including how these definitions generate both server-side enforcement and client-side checks, please refer to the canonical Capabilities Guide.
| Path | Accepted values & defaults | CLI & pipeline consumers | Generated files | WordPress artifacts | Runtime usage |
|---|---|---|---|---|---|
resources.<key>.capabilities | Partial record keyed by routes.*.capability literals. Values may be strings or descriptors. | Normalised into the IR capability map with warnings for missing/extra keys. | .generated/js/capabilities.ts, .generated/js/index.ts, and ambient .d.ts files. | PHP capability helper enforces current_user_can() and object bindings. | Typed helpers from defineCapability() mirror the resolved keys. |
resources.<key>.capabilities.<cap>.capability | WordPress capability string. | Serialised verbatim. | Included in TypeScript + PHP helpers. | Determines capability passed to current_user_can(). | Returned via capability runtime metadata. |
resources.<key>.capabilities.<cap>.appliesTo | 'resource' or 'object'. Defaults to 'resource'. | Controls PHP helper metadata. | Included in PHP capability map. | Decides whether WordPress check receives an object ID. | Informs runtime helpers for UI gating. |
resources.<key>.capabilities.<cap>.binding | Optional string naming the identity param when appliesTo: 'object'. | Used to bind request params in PHP controllers. | Appears in PHP helper metadata. | Extracts object IDs before current_user_can(). | Surfaces binding metadata for UI affordances. |
Identity hints (resources.<key>.identity)
| Path | Accepted values & defaults | CLI & pipeline consumers | Generated files | WordPress artifacts | Runtime usage |
|---|---|---|---|---|---|
resources.<key>.identity.type | 'number' or 'string'. Defaults to 'number'. | Resolved into identity metadata. | Identity guards + helper methods in PHP controllers. | Casts IDs to integers or sanitises strings before handlers run. | Used by cache helpers and DataView row identifiers. |
resources.<key>.identity.param | Optional override ('id', 'slug', 'uuid' for string identities). Defaults to id/slug. | Passed to identity resolution helpers. | Embedded in PHP guard code and REST args. | Adds required parameter validation to REST routes. | Exposed via resource.identity. |
Storage configuration (resources.<key>.storage)
| Path | Accepted values & defaults | CLI & pipeline consumers | Generated files | WordPress artifacts | Runtime usage |
|---|---|---|---|---|---|
resources.<key>.storage.mode | 'wp-post', 'wp-option', 'wp-taxonomy', 'transient'. Optional. | Switches storage helpers and schema synthesis. | Storage-specific controllers, helpers, and registries. | Generates CRUD logic for posts/options/taxonomies/transients. | Storage metadata surfaced via resource.storage. |
resources.<key>.storage.postType | Only for mode: 'wp-post'. Optional slug. | Passed to WP_Post builders. | Embedded in PHP controllers. | Determines post type managed by generated CRUD handlers. | Reflected in runtime metadata. |
resources.<key>.storage.statuses | string[] for wp-post. Optional. | Used by WP_Post list helpers. | Stored in PHP metadata arrays. | Filters REST queries to allowed statuses. | Exposed to runtime. |
resources.<key>.storage.supports | Array of WordPress post feature strings. Optional. | Forwarded to mutation helpers. | Included in PHP helper metadata. | Controls which core post features are synced. | - |
resources.<key>.storage.meta | Record of post meta descriptors { type, single? }. Optional. | Drives schema synthesis + meta sync helpers. | PHP helper methods for updating post meta. | Calls update_post_meta() with type-safe casting. Used to define one-to-one or one-to-many relationships with simple values. Generates sync<ResourceName>Meta and prepare<ResourceName>Response methods. | Metadata recorded on the resource. |
resources.<key>.storage.taxonomies | Record of { taxonomy, hierarchical?, register? }. Optional. | Feeds taxonomy sync helpers. | PHP helper methods for syncing term assignments. | Registers taxonomies (when register: true) and syncs term IDs. Used to define many-to-many relationships. Generates sync<ResourceName>Taxonomies and prepare<ResourceName>Response methods. | Metadata recorded on the resource. |
resources.<key>.storage.taxonomies.*.taxonomy | WordPress taxonomy slug. | Same as above. | Same as above. | Used when calling wp_set_object_terms(). | - |
resources.<key>.storage.taxonomies.*.hierarchical | Optional boolean. | Used when generating taxonomy registration metadata. | Included in PHP helper metadata. | Controls registration arguments for new taxonomies. | - |
resources.<key>.storage.taxonomies.*.register | Optional boolean (default false). | Determines whether registration code is emitted. | PHP persistence registry entry when true. | Registers taxonomy on plugin bootstrap. | - |
resources.<key>.storage.taxonomy | Required for mode: 'wp-taxonomy'. | Used when building taxonomy controllers. | PHP controller metadata. | Drives CRUD helpers for taxonomy terms. | Runtime metadata records taxonomy slug. |
resources.<key>.storage.hierarchical | Optional for wp-taxonomy. | Same as above. | Same as above. | Configures taxonomy registration (hierarchical vs. flat). | - |
resources.<key>.storage.option | Required for mode: 'wp-option'. | Consumed by option storage helpers. | PHP controllers calling get_option/update_option. | Registers REST handlers that manage the option name. | Metadata stored on the resource. |
resources.<key>.storage (mode: 'transient') | No additional fields. | Enables transient storage helper. | PHP controller using get_transient/set_transient. | Registers REST routes that operate on the transient key. | Metadata stored on the resource. |
Schema + query parameter metadata
resources.<key>.schemadescribes the API surface of the resource. It powers request validation and response shaping where implemented. It does not create storage, it does not emit DDL, and it ignores extra fields at the storage layer unless a storage driver explicitly maps them.
| Path | Accepted values & defaults | CLI & pipeline consumers | Generated files | WordPress artifacts | Runtime usage |
|---|---|---|---|---|---|
resources.<key>.schema | Schema key (string), inline schema object, or undefined. | Resolved via schema accumulator. | Schema JSON stored in IR (inline objects are hashed and deduplicated automatically). | REST argument validation derived from schema properties. | Schema key exposed on resource.schemaKey. |
resources.<key>.queryParams.<param>.type | 'string' or 'enum'. Required per entry. | Converted into REST arg schema types. | REST arg metadata for query params. | Adds args definitions on register_rest_route. | Documented on resource.queryParams. |
resources.<key>.queryParams.<param>.enum | Optional list of allowed values when type: 'enum'. | Added to REST arg schema. | Same as above. | Adds enum validation to REST args. | - |
resources.<key>.queryParams.<param>.optional | Optional boolean (default true). | Controls REST arg required flag. | Same as above. | Marks query param as required when false. | - |
resources.<key>.queryParams.<param>.description | Optional string. | Copied into REST arg docs. | Same as above. | Populates description in REST arg registration. | Exposed via runtime metadata. |
UI configuration (resources.<key>.ui)
| Path | Accepted values & defaults | CLI & pipeline consumers | Generated files | WordPress artifacts | Runtime usage |
|---|---|---|---|---|---|
resources.<key>.ui.admin.view | Optional; set to 'dataviews' to generate an admin surface. | Enables UI builders, bundler wiring, and PHP loader hooks. | .generated/ui/** DataViews fixtures, admin entrypoints, and supporting TS/JS inferred from schemas/storage/layout. | Loader registration + menu shims emitted when a UI surface exists. | Recorded on resource.ui.admin.view; detailed UI shape is inferred. |
All former ui.admin.dataviews.* knobs have been retired. The CLI derives columns, actions, layouts, and interactivity from your existing schema, storage, and identity hints (plus the layout manifest). For bespoke tweaks, edit the emitted files after generation instead of expanding the config surface.
Menu registration remains explicit: set resources.<key>.ui.admin.menu with slug/title (and optional capability/parent/position) when you want a WordPress admin menu entry for the generated screen. This is not inferred.
| Path | Accepted values & defaults | CLI & pipeline consumers | Generated files | WordPress artifacts | Runtime usage |
|---|---|---|---|---|---|
resources.<key>.ui.admin.menu | Optional object. Provide to register an admin menu page. | Passed to UI/loader builders. | Influences .generated/ui loader. | Registers WP admin menu when menu is present. | Used to build menu metadata for runtime surfaces. |
resources.<key>.ui.admin.menu.slug | Required when menu is present. | Same as above. | Same. | Menu slug for add_menu_page/add_submenu. | Exposed via UI metadata. |
resources.<key>.ui.admin.menu.title | Required when menu is present. | Same as above. | Same. | Menu page title. | Same. |
resources.<key>.ui.admin.menu.capability | Optional; defaults to 'manage_options' when omitted. | Same as above. | Same. | Capability guard for menu access. | Same. |
resources.<key>.ui.admin.menu.parent | Optional parent slug (e.g. options-general.php). | Same as above. | Same. | Registers submenu under the parent when set. | Same. |
resources.<key>.ui.admin.menu.position | Optional menu position number. | Same as above. | Same. | Controls menu ordering. | Same. |
Keeping documentation in sync
The Jest suite contains a guard that verifies every property described above remains documented. Adding a new config field requires updating both the TypeScript types and this reference so the test continues to pass.