IsuDev Library self-updates

Reusable, server-rendered Gutenberg blocks and tools. One place instead of copying blocks from project to project.

• Self-contained. No runtime dependency on a theme, on t2, or on any other plugin. build/ ships with the repo, so no build step is needed to install it.
• Always server-rendered. Every block renders in PHP.
• Toggleable. Enable or disable blocks from the admin panel, or pin them in code via isudev.json.

Requirements

WordPress 6.7+, PHP 7.4+. Node 22.22.2 for development only.

Blocks

Each block ships a README.md in its own directory: every setting, where to find it, what a theme can lock, and what to check when the block does not render. Deeper theme-side documentation lives in guides/.

Extensions

Quality-of-life features that are not blocks — an admin column, a post type rename, a plugin integration. Each is toggled from IsuDev Library → Extensions, and every one is off until someone turns it on: a block only appears when an editor inserts it, but an extension changes the admin or the front end the moment it loads.

An extension whose required plugin is inactive cannot be enabled at all; the panel shows it as unavailable rather than letting it be switched on to do nothing.

Each ships a README.md in its own directory: what it changes, every filter it offers, and what to check when it appears to do nothing. extensions/README.md is the guide to writing a new one.

Configuration

Everything works on sensible defaults with no configuration. To override per-project, add an optional isudev.json to your theme (child overrides parent). See isudev.json.example.

This plugin reads only the library key and never writes to the file, so the same isudev.json is safe to share with other isudev-* plugins.

{
  "library": {
    "isudev/site-header": { "enabled": true }
  }
}

Extensions are pinned the same way, under their own extensions key — they are keyed by slug rather than by block name, because an extension has no block name:

{
  "library": {
    "extensions": {
      "skip-links": { "enabled": true },
      "disable-posts": { "enabled": false }
    }
  }
}

enabled set in isudev.json wins over the admin panel and locks the toggle, for blocks and extensions alike.

In v1 a block entry accepts enabled and variations. Per-block default attributes are read by Config\get_block_config(), but no block consumes them yet — see the CHANGELOG's "Not in v1" list.

Variations

Register extra variations of a block from isudev.json. Each gets a _namespace attribute, so render.php can vary markup and classes per variation. See isudev.json.example.

Filters

Each extension adds its own filters under isudev_library/extensions/<slug>/…, documented with examples in that extension's README — see the Extensions table above.

Code-only mode — no panel, configuration lives entirely in isudev.json:

add_filter( 'isudev_library/settings/show_admin', '__return_false' );

Development

nvm use
npm install && composer install
npm run build
npm run test:php
npm run lint:js && npm run lint:css && composer run lint:php
WP_ADMIN_USER=... WP_ADMIN_PASS=... npm run test:e2e

Never run npm start in automated work — use the one-shot npm run build.

Releasing

Releases are cut from a tag and published as a GitHub release. The plugin updates itself from that release's zip, so the artifact is the product:

# Bump the version in isudev-library.php, package.json and package-lock.json,
# add the CHANGELOG.md section, npm run build, commit and push main. Then:
git tag v1.12.0 && git push origin v1.12.0

The workflow refuses to publish a release whose tag disagrees with the plugin header, that has no CHANGELOG.md section, or whose zip is missing runtime code or carrying development files.

Self-updates are active only for installs that carry a bundled vendor/ — that is how the plugin tells a release-zip install from a Composer-managed one, where Composer owns the version instead.

Adding a block

1. Create src/blocks/<slug>/ with block.json (apiVersion: 3, "render": "file:./render.php"), index.js, render.php.
2. Add block.php returning a descriptor — see src/blocks/site-header/block.php.
3. npm run build. The loader picks it up; the panel lists it automatically.

Block directory names must be globally unique: the generated build/blocks-manifest.php is keyed by directory basename.

Adding an extension

1. Create extensions/<slug>/ with extension.php (a descriptor that registers nothing), hooks.php (every hook inside a boot() function) and a README.md.
2. No build step — extensions ship no JavaScript. The panel lists it automatically.

Read extensions/README.md first: it documents every descriptor key, why hooks may never be registered at the top level of a file, and the conventions tools/check.php enforces.

License

GPL-2.0-or-later.