Air WordPress Plugin

WordPress Playground (browser-only QA)

Designers / PM can boot a disposable WordPress in the browser with the plugin preinstalled — no Docker, no local install. Each link below pulls the matching zip from the latest GitHub Release.

Env	Open in Playground
dev	https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/AirLabsTeam/air-wordpress-plugin/main/blueprints/dev.json
qa	https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/AirLabsTeam/air-wordpress-plugin/main/blueprints/qa.json
prod	https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/AirLabsTeam/air-wordpress-plugin/main/blueprints/prod.json

Login: admin / password. Lands on a new post; insert the Air Asset Picker block to test. State is ephemeral — refresh wipes the site.

The blueprints bake a default air_workspace_id via setSiteOptions. Default workspace targets:

Env	Workspace
dev / qa	QA Air Workspace (254754d4-15f8-4547-89f8-f27e64d40ffd) on api-qa.air.inc
prod	Air Workspace (77b00fde-3652-4bc3-8b7b-32a4f14617eb) on api.air.inc

To target a different workspace, edit the air_workspace_id value in the matching blueprints/{dev,qa,prod}.json file.

Cutting a release

Tag a commit v* (e.g. git tag v0.1.1 && git push --tags). The Release Plugin Builds workflow builds three zips (air-picker-development.zip, air-picker-qa.zip, air-picker-production.zip) and attaches them to a GitHub Release. The Playground links above always resolve to the latest release.

Picker iframe / CORS notes

• Each Air picker origin (localhost:3007, qa.wordpress-plugin.air.inc, wordpress-plugin.air.inc) must allow being framed by https://playground.wordpress.net (CSP frame-ancestors, no X-Frame-Options: DENY).
• API calls from the picker need CORS allow for the Playground origin.
• localhost:3007 will not work in Playground (browser cannot reach the designer's localhost). Use the qa or prod link for Playground QA.

Local development

Prerequisites

• Docker Desktop
• Node.js 22+ (via nvm)

Setup

1. Create a standalone yarn lockfile (required since this plugin is excluded from the monorepo workspaces):

touch yarn.lock

2. Install dependencies:

yarn install

Environments

The Air picker iframe URL is selected at build time. Three committed env files drive the defaults:

File	Picker target	Use for
.env.development	http://localhost:3007	local Next picker (next dev)
.env.qa	https://qa.wordpress-plugin.air.inc	qa Vercel deployment
.env.production	https://wordpress-plugin.air.inc	prod Vercel deployment

Personal overrides (gitignored, optional):

• .env.local — applies to every environment
• .env.<APP_ENV>.local — applies to one environment
• .env — lowest-priority fallback

Resolution order (first wins, matches Next.js):

process.env CLI > .env.<APP_ENV>.local > .env.local > .env.<APP_ENV> > .env

The webpack config logs the resolved value at every build:

[webpack] APP_ENV=qa AIR_PICKER_ORIGIN=https://qa.wordpress-plugin.air.inc

Build scripts

npm run build:dev     # bundle against http://localhost:3007
npm run build:qa      # bundle against qa.wordpress-plugin.air.inc
npm run build:prod    # bundle against wordpress-plugin.air.inc

Watch scripts (rebuild on file change)

npm run start:dev
npm run start:qa
npm run start:prod

One-shot full-stack scripts (build + wp-env)

npm run wp:dev        # build dev bundle, then `wp-env start`
npm run wp:qa
npm run wp:prod

npm run build / npm run start (no suffix) honour whatever APP_ENV is in the shell, defaulting to development if unset.

Running WordPress locally

Option A — wp-env (recommended)

yarn dlx @wordpress/env start

WordPress at http://localhost:8888 — username: admin, password: v1I&ir9jRTvechcJ&9jxOZin.

Option B — docker-compose

export NEXT_WP_PLUGIN_DIR=~/path/to/next/plugins/wordpress
docker-compose up

WordPress at http://localhost:4080.

⚠️ Local dev only: docker-compose.yml uses hardcoded credentials: MARIADB_ROOT_PASSWORD=root and MARIADB_PASSWORD=wordpress. Never use these in a shared or staging environment.

Settings → Air Media

After the plugin is active, configure the Air workspace ID under Settings → Air Media in wp-admin. The block reads the workspace ID from window.airAssetPickerData.workspaceId, which is localised by PHP from the saved option.

Running the Air picker locally (legacy)

The air-picker/ folder contains a static dev stand-in for the Air gallery picker. It is no longer the default — the build now points at the deployed Next picker app. Keep it around if you want to test the iframe handshake without depending on the Next dev server:

python3 -m http.server 8000 --directory air-picker

Then create a .env.local with AIR_PICKER_ORIGIN=http://localhost:8000 and run npm run build:dev.