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

WordPress	EmDash	Notes
register_post_type()	SchemaRegistry.createCollection()	Via Admin API or seed file
register_taxonomy()	_emdash_taxonomy_defs table	Hierarchical or flat, attached to collections
register_meta() / ACF	Collection fields via SchemaRegistry	All become typed schema fields
get_post_meta()	entry.data.fieldName	Direct typed access
get_option()	getSiteSetting() / ctx.kv	Site settings or plugin-namespaced KV
WP_Query	getEmDashCollection()	Runtime queries with filters
get_post($id)	getEmDashEntry(collection, slug)	Returns entry or null
wp_insert_post()	POST /_emdash/api/content/{type}	REST API
wp_update_post()	PUT /_emdash/api/content/{type}/{id}	REST API
wp_delete_post()	DELETE /_emdash/api/content/{type}/{id}	Soft delete
Custom tables	Plugin storage collections	ctx.storage.collectionName.put/get/query

Site Configuration

WordPress	EmDash	Notes
get_bloginfo('name')	getSiteSetting('title')	From options table with site: prefix
get_option('blogdesc')	getSiteSetting('tagline')	Site settings API
Theme Customizer	Site Settings admin page	/_emdash/admin/settings
site_icon	getSiteSetting('favicon')	Media reference
custom_logo	getSiteSetting('logo')	Media reference

Navigation Menus

WordPress	EmDash	Notes
register_nav_menu()	Create menu via admin or seed	_emdash_menus table
wp_nav_menu()	getMenu(name)	Returns { items: MenuItem[] }
wp_nav_menu_item	_emdash_menu_items table	Type: custom, page, post, taxonomy
_menu_item_object_id	reference_id + reference_collection	Links to content entries
Menu locations	Query by name in templates	No locations concept — direct query

Taxonomies

WordPress	EmDash	Notes
register_taxonomy()	_emdash_taxonomy_defs table	Define via admin, seed, or API
get_terms()	getTaxonomyTerms(name)	Returns tree for hierarchical
get_the_terms()	getEntryTerms(collection, id, name)	Terms for specific entry
wp_set_post_terms()	TaxonomyRepository.setTermsForEntry()	Replace terms for entry
Hierarchical taxonomy	hierarchical: true in definition	Categories-style
Flat taxonomy	hierarchical: false	Tags-style

Widgets & Sidebars

WordPress	EmDash	Notes
register_sidebar()	_emdash_widget_areas table	Create via admin or seed
dynamic_sidebar()	getWidgetArea(name)	Returns { widgets: Widget[] }
WP_Widget class	Widget types: content, menu, component	Simplified — 3 types only
Text widget	type: 'content' + Portable Text	Rich text widget
Nav Menu widget	type: 'menu' + menuName	References a menu
Custom widgets	type: 'component' + componentId	Plugin-registered components

Admin UI

WordPress	EmDash	Notes
add_menu_page()	admin.pages in definePlugin()	Plugin config
add_submenu_page()	Nested admin pages	Parent determines hierarchy
add_settings_section()	admin.settingsSchema	Auto-generated settings page
add_meta_box()	Field groups in collection schema	UI config in schema
wp_enqueue_script()	ESM imports in admin components	React (trusted) or Block Kit (sandboxed)
Admin notices	Toast notifications	Via admin UI framework

Hooks

WordPress	EmDash	Notes
add_action('init')	plugin:install hook	Runs once on first install
add_action('save_post')	content:afterSave hook	Filter by event.collection
add_action('before_delete_post')	content:beforeDelete hook	Return false to prevent
add_action('wp_head')	page:metadata / page:fragments hook	Metadata is sandbox-safe; scripts need trusted plugin
add_action('rest_api_init')	definePlugin({ routes })	Trusted only
add_filter('the_content')	Portable Text components	Custom block renderers
add_filter('the_title')	Template logic	Handle in Astro component

Frontend Output

WordPress	EmDash	Notes
add_shortcode()	Portable Text custom block	Content → block. Template → component. Trusted only.
register_block_type()	PT block + componentsEntry	Block data → Astro component props. Trusted only.
Template tags	Astro expressions	get_the_title() → {post.data.title}
Widgets	Widget area + components	Query with getWidgetArea()

Plugin Storage

WordPress	EmDash	Notes
get_option('plugin_*')	ctx.kv.get(key)	Namespaced to plugin automatically
update_option()	ctx.kv.set(key, value)	Scoped KV storage
delete_option()	ctx.kv.delete(key)	Delete single key
Custom tables	ctx.storage.collection	Document collections with indexes
Transients	Plugin KV	No TTL yet

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