DEV Community: Akshat Saxena

Scaffold a WordPress plugin with linting, tests and CI already wired

Akshat Saxena — Wed, 02 Sep 2026 10:59:16 +0000

Every WordPress plugin I start begins with the same unglamorous hour: PSR-4
autoloading, a PHPCS ruleset, PHPUnit with mocked WordPress functions, a build
step for the admin JS, the GitHub Actions file. Only then do I get to the feature
I actually opened the editor for.

I packaged that hour into a generator. You answer a few prompts, tick the pieces
you need, and get a plugin that already lints, tests and ships.

One command

npx create-wp-plugin-cli
# or: npm create wp-plugin-cli

No install. Node 20+. Generated plugins target PHP 8.2 (fixed) — constructor
promotion, readonly, first-class callables throughout.

The interactive run

Twelve questions. Most have a pre-filled answer you accept with Enter; the two
that matter are the lint target and the modules multiselect.

$ npx create-wp-plugin-cli

🚀 Welcome to create-wp-plugin-cli scaffold generator!

√ 1. Plugin name: … Loyalty Points
√ 2. Plugin slug: … loyalty-points
√ 3. PHP namespace: … LoyaltyPoints
√ 4. Function/constant prefix (>= 4 chars, lowercase): … loyp
√ 5-7. Author name / email / URI …
√ 8. Description (one line): … Award and redeem loyalty points at checkout.
√ 9. Coding standard target for composer lint: › WordPress.org (standard hosting)
√ 10. Include React admin app build pipeline? … no
√ 11. Modules to include (space to toggle):
      › REST API, cron, WP-CLI commands, WooCommerce integration
√ 11a. WooCommerce components: › Payment Gateway, Custom Order Status
√ 12. Output directory: … ./loyalty-points
√ Proceed with these values? … yes

[ok] Successfully scaffolded plugin "Loyalty Points" in ./loyalty-points!

--lint-target picks the PHPCS ruleset composer lint enforces: wp-org
(WordPress-Extra + Docs), vip (WordPress-VIP-Go), or both.

What you always get

Regardless of module choices:

File	Role
`src/Plugin.php`	Bootloader with a re-entry guard; `boot()` is the composition root
`src/Core/Activator.php` / `Deactivator.php`	Implement `Contracts\Activatable` / `Deactivatable`, run from the (de)activation hooks
`src/Services.php`	Static locator of memoised singletons — only emitted if a module needs a shared collaborator
`tests/Unit/Plugin_TestCase.php`, `tests/bootstrap.php`	Brain Monkey base — unit tests run with no WordPress install
`composer.json`, `phpcs.xml`, `phpunit.xml.dist`	PHPCS/WPCS(+VIP), PHPUnit, PHPCompatibility against `8.2-`
`.github/workflows/ci.yml`	PHPCS + a PHPUnit 8.2/8.3/8.4 matrix (+ more when there's JS)

The modules

All opt-in, all freely combinable — nothing here depends on anything else.

Admin, content & data

Module	What you get
`admin_settings`	A Settings API page split into `Admin\Settings_Registrar` / `Settings_Repository` / a view
`cpt_taxonomy`	`PostTypes\Post_Types` — a CPT + taxonomy, wired into activation
`custom_table`	`dbDelta()` schema + `Database\Schema` + an `Item_Repository`, with version-checked migrations
`caching`	`Cache_Service` — a persistent object cache or a transient fallback, chosen per call, never both

Front-end

Module	What you get
`shortcode`	A `Frontend\Shortcode` class registering one shortcode
`block`	Native Gutenberg block(s): `block:dynamic` (`render.php`) and/or `block:static` (`save()`). `Blocks\Block_Registrar` globs `assets/build/blocks/*`, so more blocks need no PHP
`interactivity`	A WordPress Interactivity API store — `view.js` + a Script Module (WP 6.5+)

Integration points

Module	What you get
`rest_api`	A `WP_REST_Controller` subclass with a real permission callback
`ajax_handler`	A nonce- and capability-guarded `admin-ajax` handler + the `assets/js/main.js` it enqueues
`cron`	`Cron\Scheduler` — a scheduled event with a worked example body
`cli`	`wp <prefix> status` and `wp <prefix> cache clear`, behind a `defined( 'WP_CLI' )` guard
`elementor_widget`	`Widget_Registrar` auto-discovers `src/Widgets/*`; convention-based CSS/JS enqueue

Tooling

Module	What you get
`editor_config`	`.vscode/` snippets, settings, recommended extensions
`integration_tests`	A real `wp-phpunit` suite (`composer test:integration`), `phpunit-integration.xml.dist`, a boot test, `.wp-env.json`, and a CI integration job

WooCommerce

Pass woocommerce for all nine, or pick components. Each is a Woo\Providers\*
class wired inside a single class_exists( 'WooCommerce' ) guard, so the plugin
is inert on a site without WooCommerce.

Component	What you get
`woo:gateway`	A `WC_Payment_Gateway` subclass + a Blocks (block checkout) payment method type
`woo:shipping`	A `WC_Shipping_Method` subclass
`woo:email`	A `WC_Email` subclass + HTML and plain-text templates
`woo:order-status`	A custom, HPOS-compliant order status
`woo:product-type`	A custom product type with data tabs/panels
`woo:blocks`	Cart & Checkout block extensions (front-end script + integration class)
`woo:action-scheduler`	An Action Scheduler-backed background task runner
`woo:store-api`	A Store API extension via `ExtendSchema`
`woo:my-account`	A custom My Account endpoint (route + template)

A JS pipeline (wp-scripts build + Playwright) is added automatically for
--react, interactivity, block, woo:gateway, or woo:blocks. Jest comes
in with --react. uninstall.php is derived — it ships only when a selected
module actually persists something (an option, a table, a scheduled event).

The architecture, in 60 seconds

Plugin is a bootloader with a re-entry guard. Its boot() is a flat list —
here's the real thing the run above produced:

public function boot(): void {
    if ( $this->booted ) {
        return;
    }
    $this->booted = true;

    if ( defined( 'WP_CLI' ) && WP_CLI ) {
        ( new CLI\Commands() )->init_hooks();
    }

    ( new Rest\Rest_Controller() )->init_hooks();
    ( new Cron\Scheduler() )->init_hooks();

    if ( class_exists( 'WooCommerce' ) ) {
        ( new Woo\Providers\Gateway_Provider() )->init_hooks();
        ( new Woo\Providers\Order_Status_Provider( Services::order_status_service() ) )->init_hooks();
    }
}

A "module" is a plain class with an init_hooks() method. No base class, no
interface, no auto-discovery — a class runs only because boot() names it. CLI
commands sit behind a WP_CLI check; WooCommerce providers behind the
class_exists guard.

Services is emitted only when something needs it — here, because
Order_Status_Provider takes a Services::order_status_service() injection.
Gateway_Provider needs nothing, so it's constructed bare. Services::set() /
reset() are the test seams.

Tests, per module

cd loyalty-points
composer install
composer test

Green on the first run. Every selected module gets its own unit test — the run
above generated Rest_Controller_Test, Commands_Test, Gateway_Test,
Order_Status_Service_Test, plus Services_Test and a Module_Hooks_Test that
asserts each module's init_hooks() registers exactly the hooks it claims. All
Brain Monkey, no WordPress install.

Gateway_Test, for instance, checks the gateway instantiates with id
loyp_gateway and that the unimplemented process_payment() stub fails
closed — returns ['result' => 'failure'], never marks an order paid.

For anything browser-facing:

npm install && npm run build
npm run test:e2e        # Playwright — `npx @wordpress/env start` for a target site

The CI file it wrote

.github/workflows/ci.yml, unprompted:

phpcs — composer validate --strict + composer lint
phpunit — a PHP 8.2 / 8.3 / 8.4 matrix running composer test
node-build — npm run build, JS/CSS lint, then Playwright E2E against a wp-env site (only when the selection has a JS side)
integration — the wp-phpunit suite, when you picked integration_tests

Using it in scripts

Every answer is a flag:

npx create-wp-plugin-cli --yes \
  --name "Loyalty Points" --prefix loyp --namespace LoyaltyPoints \
  --modules "rest_api,cron,cli,woo:gateway,woo:order-status" \
  --lint-target both \
  --out ./loyalty-points

Piping in without --yes and no TTY exits with an error instead of hanging. A
failure partway through generation rolls back the directory it created.

When not to use it

A one-file plugin. If it's 40 lines in a single file, this is overkill.
You want a DI container. It deliberately doesn't ship one — modules are plain classes and boot() is the composition root.
Block-only projects are usually better served by @wordpress/create-block directly; this wraps it when you also need PHP, tests and CI around the block.

A Gutenberg block that uses the Interactivity API — with no render callback and no framework on the front end

Akshat Saxena — Fri, 28 Aug 2026 04:55:16 +0000

A YouTube embed looks innocent enough.

You drop an iframe into a page, give it a src, and you're done, right?

Except you're not.

Google's Lighthouse documentation puts a full embedded YouTube player at around 540 KB. On a live page, it's closer to 1.3 MB. And the cost doesn't get amortized when you add another embed — two players can mean roughly twice the payload because the resources aren't shared.

HTTP Archive data referenced by web.dev puts another horrifying metric on it: the median YouTube embed occupies the browser's main thread for more than 1.7 seconds.

And here's the part that bothered me most: All of that happens even if nobody presses Play. 🤯

The Solution: The Facade Pattern

The fix isn't new. It's the facade pattern:

Show a poster.
Show a play button.
Don't load the actual player.
Only load it when the visitor clicks.

Tools like lite-youtube-embed have been doing this for years.

I wanted to bring this exact same concept into a WordPress Gutenberg block—but not just for YouTube, and definitely not by shipping an entire JavaScript framework to the browser just to replace a JPEG with an iframe.

That experiment became the Story Video Block (now live on the WP repo, source on GitHub).

Here are the most interesting architectural decisions and technical gotchas I ran into while building it. 👇

The Interactivity Dilemma

The actual interaction needed for a facade is tiny. Click. Swap in the embed. Play the video. That's basically it.

But traditional block solutions can be surprisingly expensive for such a small interaction:

You could enqueue a classic view.js and manually handle event delegation and DOM manipulation.
You could ship React to the front end (some block plugins actually do this). You're essentially sending a UI framework to someone's phone so a poster image can turn into an iframe.
You could use jQuery (please don't).

Enter WordPress's Interactivity API ⚡

Since WordPress 6.5, we have the Interactivity API. It gives blocks a declarative way to add client-side behavior. More importantly, the runtime is shared by all blocks on the page.

The opt-in is incredibly simple in your block.json:

"editorScript": "file:./index.js",
"style": "file:./style-index.css",
"viewScriptModule": "file:./view.js"

Notice one detail: viewScriptModule, not viewScript.
That registers the file through the Script Modules API and allows you to natively import the shared WP runtime:

import { store } from '@wordpress/interactivity';

Revelation: You Don't Need a Dynamic Block

This was my biggest misconception. Because almost every Interactivity API tutorial uses a dynamic block (render.php), I assumed they were mandatory. They aren't.

The directives are just HTML attributes. A static block's save() function can output them, and the frontend runtime will hydrate whatever it finds.

Here's how my static save() looks:

const blockProps = useBlockProps.save( {
    className: clsx( {
        [ `has-media-${ videoPosition }` ]: videoPosition,
        [ `card-style-${ cardStyle }` ]: cardStyle,
    } ),
    style: {
        '--story-video-block-bg': backgroundColor || undefined,
    },
    ...( ! isFile
        ? {
                'data-wp-interactive': 'create-block/story-video-block',
                'data-wp-context': JSON.stringify( {
                    isPlaying: false,
                    embedUrl,
                    videoSrc: '',
                } ),
          }
        : {} ),
} );

That JSON.stringify() is the whole server-state story for this block! The markup lives in post_content. There's no PHP render callback running on every request, yet each block instance gets its own scoped, reactive state.

The Performance Trick: The `iframe` with no `src`

You cannot render an iframe and just CSS hide it. If it has a src, the browser will load the player. Hidden doesn't mean unloaded.

So, the iframe is deliberately rendered without a src.

<div
    className="story-video-block__video"
    hidden
    data-wp-bind--hidden="state.isNotPlaying"
>
    <iframe
        title={ heading || __( 'Video', 'story-video-block' ) }
        data-wp-bind--src="context.videoSrc"
        allow="autoplay; fullscreen; picture-in-picture"
        allowFullScreen
    />
</div>

Initially, context.videoSrc === ''. Because WP's data-wp-bind--* removes an attribute when its value is falsy, there is no src attribute at all. No request, no player.

Bonus UX win: Because the source is assigned inside the click handler, the browser treats playback as user-initiated. That means autoplay=1 actually works. One click, video starts. No double-clicking required.

Progressive Enhancement: The facade is a link 🔗

I didn't make the facade a <div>. JavaScript shouldn't be the only way to reach the video.

The facade is a real <a> tag pointing to the original video:

<a
    href={ videoUrl }
    target="_blank"
    rel="noopener noreferrer"
    className="story-video-block__facade"
    data-wp-on--click="actions.play"
    data-wp-bind--hidden="state.isPlaying"
>

Our Interactivity store then enhances it:

import { store, getContext } from '@wordpress/interactivity';

store( 'create-block/story-video-block', {
    state: {
        get isPlaying() { return getContext().isPlaying; },
        get isNotPlaying() { return ! getContext().isPlaying; },
    },
    actions: {
        play( event ) {
            const context = getContext();
            if ( context.isPlaying ) return;

            // If no direct-embed URL (like TikTok), let the original <a> link work!
            if ( ! context.embedUrl ) return;

            event.preventDefault();
            context.videoSrc = context.embedUrl;
            context.isPlaying = true;
        },
    },
} );

This gives us graceful degradation:

JS + Supported provider (YouTube/Vimeo): Plays inline seamlessly.
JS + No direct embed (TikTok): Acts as a normal link.
No JS enabled: Acts as a normal link.

🐛 A CSS Gotcha That Cost Me an Evening

The Interactivity API was working. The hidden attribute was toggling perfectly in the DOM. But the elements were still visible on the screen. Why?

Browsers have a default user-agent style:

[hidden] { display: none; }

But if your block's custom CSS applies an explicit display (like display: flex;), it overrides the low-specificity [hidden] rule.

The fix:

[hidden] {
    display: none !important;
}

Pro-tip: If you're using data-wp-bind--hidden and nothing is happening visually, check your CSS specificity before ripping apart your JavaScript!

Why skip WordPress oEmbed on the frontend?

WordPress has robust oEmbed support. Why did I write manual regex provider detection for the frontend?

Because the /oembed/1.0/proxy endpoint requires edit_posts permissions. An anonymous site visitor gets a 401 Unauthorized.

Instead, the block parses the URL itself (supporting YouTube, Vimeo, Dailymotion, Twitch, mp4s, etc.) and constructs the embed URL string locally. Zero network requests just to figure out a URL we already know how to build.

Final Thoughts

Building this reminded me of a golden rule in web development: Don't make every visitor pay for a feature that only some visitors will use.

A video doesn't need to be a 1MB+ third-party application just because someone might press Play. A static Gutenberg block doesn't need to become dynamic just to hold state. And a tiny bit of interactivity doesn't require shipping a massive JS runtime.

If you're building blocks for WordPress, give the Interactivity API a shot for your next frontend component!

The Story Video Block is currently v0.1.0, requires WP 6.8+, and is GPL. If you want to check out the full code or contribute, PRs are welcome on GitHub!