Porting WordPress Plugins to EmDash

This skill maps WordPress concepts to their EmDash equivalents for plugin porting. For general plugin authoring details (plugin structure, definePlugin(), hooks, storage, admin UI, etc.), use the creating-plugins skill.

Migration Approach

1. Understand the plugin — What does it do, not how
2. Identify concepts — Content types, admin pages, hooks, shortcodes
3. Map to EmDash — Use the tables below
4. Implement in TypeScript — Clean room, not line-by-line port. Use the creating-plugins skill for implementation details.
5. Test behaviour — Same result, different implementation

Concept Mapping

Content & Data

Site Configuration

Navigation Menus

Taxonomies

Widgets & Sidebars

Admin UI

Hooks

Frontend Output

Plugin Storage

Porting-Specific Patterns

These patterns cover WordPress-specific concepts that don't have a direct 1:1 mapping. For general plugin patterns (defining hooks, storage, routes, admin UI), see the creating-plugins skill.

Shortcodes → Portable Text Blocks

WordPress shortcodes ([youtube id="xxx"]) become Portable Text custom block types. The block data replaces shortcode attributes, and an Astro component replaces the shortcode render function. This is a trusted-only feature.

// WordPress
add_shortcode('youtube', function($atts) {
    return '<iframe src="https://youtube.com/embed/' . $atts['id'] . '"></iframe>';
});

// EmDash — block type declaration in definePlugin()
admin: {
	portableTextBlocks: [{
		type: "youtube",
		label: "YouTube Video",
		icon: "video",
		fields: [
			{ type: "text_input", action_id: "id", label: "YouTube URL" },
			{ type: "text_input", action_id: "title", label: "Title" },
		],
	}],
}

// EmDash — Astro component for rendering
// src/astro/YouTube.astro
const { id, title } = Astro.props.node;
const videoId = id?.match(/(?:v=|youtu\.be\/)([^&]+)/)?.[1] ?? id;
// <iframe src={`https://youtube-nocookie.com/embed/${videoId}`} ... />

Options API → Plugin KV

WordPress's get_option/update_option maps to the plugin KV store. The key difference: WordPress options are global, EmDash KV is automatically scoped to the plugin.

// WordPress
$count = get_option("myplugin_post_count", 0);
update_option("myplugin_post_count", $count + 1);
delete_option("myplugin_temp_data");

// EmDash — no prefix needed, automatically scoped
const count = (await ctx.kv.get<number>("post-count")) ?? 0;
await ctx.kv.set("post-count", count + 1);
await ctx.kv.delete("temp-data");

Custom Database Tables → Storage Collections

WordPress plugins that create custom tables with $wpdb->query("CREATE TABLE ...") should use EmDash's storage collections instead. No migrations needed — declare the schema in definePlugin() and it's automatically provisioned.

// WordPress
$wpdb->insert($table, ['form_id' => $id, 'data' => json_encode($data), 'created_at' => current_time('mysql')]);
$results = $wpdb->get_results("SELECT * FROM $table WHERE form_id = '$id' ORDER BY created_at DESC LIMIT 50");

// EmDash — declared in definePlugin()
storage: {
	submissions: {
		indexes: ["formId", "createdAt", ["formId", "createdAt"]],
	},
},

// In a hook or route handler
await ctx.storage.submissions!.put(entryId, { formId, data, createdAt: new Date().toISOString() });
const result = await ctx.storage.submissions!.query({
	where: { formId },
	orderBy: { createdAt: "desc" },
	limit: 50,
});

Seeding Data (replaces starter content, theme setup)

WordPress plugins that call wp_insert_term(), register_nav_menu(), or insert default content on activation should use a seed file:

{
	"version": "1",
	"settings": { "title": "My Site", "tagline": "Welcome" },
	"taxonomies": [
		{
			"name": "category",
			"label": "Categories",
			"hierarchical": true,
			"collections": ["posts"],
			"terms": [
				{ "slug": "news", "label": "News" },
				{ "slug": "tutorials", "label": "Tutorials" }
			]
		}
	],
	"menus": [
		{
			"name": "primary",
			"label": "Primary Navigation",
			"items": [
				{ "type": "custom", "label": "Home", "url": "/" },
				{ "type": "page", "ref": "about", "collection": "pages" }
			]
		}
	],
	"redirects": [
		{ "source": "/?p=123", "destination": "/about" },
		{ "source": "/old-contact", "destination": "/contact", "type": 301 }
	]
}

Save to .emdash/seed.json (or wire up via package.json#emdash.seed); the runtime applies it on the next first-boot when the database is empty.

Use redirects for legacy WordPress URLs that still receive traffic after migration.

Querying Content (replaces WP_Query)

// WordPress
$query = new WP_Query(['post_type' => 'post', 'category_name' => 'tech', 'posts_per_page' => 10]);

// EmDash — in Astro component frontmatter
import { getEmDashCollection, getEntryTerms } from "emdash";
const { entries } = await getEmDashCollection("posts", {
	where: { category: "technology" },
	limit: 10,
});

Menus (replaces wp_nav_menu)

// WordPress
wp_nav_menu(['theme_location' => 'primary']);

// EmDash — in Astro component
import { getMenu } from "emdash";
const nav = await getMenu("primary");
// nav.items[].label, nav.items[].url, nav.items[].children

Widget Areas (replaces dynamic_sidebar)

// WordPress
dynamic_sidebar("sidebar-1");

// EmDash — in Astro component
import { getWidgetArea } from "emdash";
const sidebar = await getWidgetArea("sidebar");
// sidebar.widgets[].type: "content" | "menu" | "component"

Red Flags (Need Human Decision)

Flag these for review — they may need architectural decisions:

1. Deep WP integration — Hooks into WP core features not in EmDash
2. Theme dependencies — Assumes specific theme structure
3. Multisite features — Not supported
4. Complex WP_Query — Meta queries may need custom implementation
5. Direct SQL — Schema differs, use Kysely or plugin storage
6. Session/transient abuse — Needs proper caching layer
7. User capability checks — Review role mapping (future)
8. ob_start() buffering — PHP pattern, rethink for streaming
9. Cron jobs — wp_schedule_event() has no direct equivalent; needs platform cron

Output Format

When porting a plugin, provide:

1. Analysis — What the WP plugin does (concepts, not code)
2. Concept mapping — Which WP concepts map to which EmDash features
3. Plugin code — src/descriptor.ts and src/index.ts (use creating-plugins skill for structure)
4. Seed data — If plugin needs default taxonomies/menus/widgets
5. Astro components — For frontend output
6. Flags — Anything needing human decision