Events

WPKernel includes a robust, typed event system that allows different parts of your application to communicate without being tightly coupled. The WPKernelEventBus is the central publisher, and a bridge to wp.hooks ensures compatibility with the broader WordPress ecosystem.

Events are especially powerful when combined with the automatically generated DataView screens.

The Event Flow in a DataView

Understanding the event lifecycle is key to extending WPKernel. Let's trace the flow when a user clicks a button in a generated admin screen:

1. User Interaction: A user clicks the "Publish" button on a row in a DataView.
2. Interactivity API: The data-wp-on-click handler, automatically generated by the WPKernel CLI, triggers the appropriate action from the interactive store.
3. Action Start: The useAction hook that powers the interactive store dispatches the WPKernel Action (e.g., Job.Publish). This immediately emits the wpk.action.start event.
4. Resource Call: The Action's handler calls the resource method (e.g., job.update(...)). This triggers a REST API request, which emits wpk.resource.request.
5. Resource Response: The API responds. The resource client emits wpk.resource.response on success or wpk.resource.error on failure.
6. Cache Invalidation: The Action's handler invalidates the relevant cache keys (e.g., ctx.invalidate(...)), which emits wpk.cache.invalidated.
7. Domain Event: The Action emits a specific domain event, like acme.job.updated. The ctx object, which is an ActionContext, provides an emit method for this purpose.
8. Action Complete: The Action finishes, emitting wpk.action.complete on success or wpk.action.error on failure.

All of these events can be listened to, allowing you to build custom analytics, notifications, or other side effects that react to application state changes.

Listening to Events

You can subscribe to events directly on the event bus for a fully-typed experience, or use the familiar wp.hooks API. The configureWPKernel() function is used to initialize the WPKernel runtime.

import { configureWPKernel } from '@wpkernel/core/data';

const wpk = configureWPKernel({ namespace: 'acme' });

// Option 1: Use the typed event bus
const unsubscribe = wpk.events.on('wpk.action.complete', (event) => {
	console.log(`Action ${event.actionName} completed successfully.`);
});

// Option 2: Use WordPress hooks (the bridge forwards events automatically)
import { addAction } from '@wordpress/hooks';

addAction('wpk.action.complete', 'my-plugin/logging', (event) => {
	console.log(`Action ${event.actionName} completed successfully.`);
});

Key Event Categories

While there are many specific events, they fall into a few main categories.

Action Events

Fired during an Action's lifecycle. Useful for global loading indicators or analytics.

• wpk.action.start
• wpk.action.complete
• wpk.action.error

Resource & Transport Events

Fired by the resource client during REST API calls. Useful for network-level logging or debugging.

• wpk.resource.request
• wpk.resource.response
• wpk.resource.error

Domain Events

These are specific to your application's logic and are emitted by your Actions. By convention, they are namespaced to your plugin (e.g., my-plugin.job.published).

• [namespace].[resource].[verb] (e.g., acme.job.created)

You define and emit these in your actions to signal that a meaningful business event has occurred.

// In an Action handler
// The `ctx` object is an ActionContext, which provides an `emit` method.
ctx.emit('acme.job.created', {
	postId: createdPost.id,
	data: createdPost,
});

What's Next?

• Actions: See how to emit your own custom domain events from within an Action.
• DataViews: Understand the context where these events are most commonly generated.