wordpress-plugin-to-emdash

---
name: wordpress-plugin-to-emdash
description: Port a WordPress plugin to EmDash CMS. Use this skill when asked to migrate, convert, or port a WordPress plugin, theme functionality, or custom post type to EmDash. Provides concept mapping and implementation patterns.
---

# 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.

```typescript
// 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.

```typescript
// 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.

```typescript
// 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:

```json
{
	"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)

```typescript
// 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)

```typescript
// 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)

```typescript
// 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