docs: rename trusted -> native, improve native vs sandboxed plugin comparison by ascorbic · Pull Request #602 · emdash-cms/emdash

ascorbic · 2026-04-16T14:45:47Z

What does this PR do?

Rewrites plugin documentation to standardize on "native" (not "trusted") terminology and adds clear side-by-side comparisons of what sandboxed vs native plugins support. People were confused about the differences between the two modes.

Key changes:

Rewrites plugins/sandbox.mdx from a security-focused page into a comprehensive comparison page ("Native vs. Sandboxed Plugins") with tabbed code examples showing React admin vs Block Kit, standard vs native format, etc.
Fixes factual error: api-routes.mdx and sandbox.mdx incorrectly stated sandboxed plugins cannot have API routes. They can -- the bridge fully supports them.
Adds sandbox-first messaging: the docs now consistently recommend sandboxed plugins as the default choice, since they can be installed without npm install + rebuild.
Renames "trusted" -> "native" across all 10 affected doc files with zero remaining references to the old terminology.

Type of change

Checklist

I have read CONTRIBUTING.md
pnpm typecheck passes
pnpm lint passes
pnpm test passes (or targeted tests for my change)
pnpm format has been run
I have added/updated tests for my changes (if applicable)
User-visible strings in the admin UI are wrapped for translation and pnpm locale:extract has been run (if applicable)
I have added a changeset (if this PR changes a published package)
New features link to an approved Discussion: https://github.com/emdash-cms/emdash/discussions/...

AI-generated code disclosure

This PR includes AI-generated code

Files changed

File	Change
`plugins/sandbox.mdx`	Full rewrite: comparison page with tabs, tables, decision guide
`plugins/api-routes.mdx`	Fix: sandboxed plugins DO support routes
`plugins/overview.mdx`	Sandbox-first framing, terminology
`plugins/creating-plugins.mdx`	Format guidance tip, fix route comment
`plugins/installing.mdx`	Richer comparison table
`plugins/hooks.mdx`	Terminology (4 instances)
`plugins/block-kit.mdx`	Terminology
`plugins/publishing.mdx`	Terminology
`concepts/architecture.mdx`	Terminology
`reference/hooks.mdx`	Terminology

Rewrites plugin documentation to use 'native' instead of 'trusted' terminology and adds side-by-side comparisons showing what each plugin mode supports. Key changes: - Rewrite sandbox.mdx as comprehensive comparison page with tabbed examples - Fix incorrect claim that sandboxed plugins can't have API routes - Add sandbox-first messaging throughout plugin docs - Update terminology across 10 doc files (zero 'trusted' references remain)

changeset-bot · 2026-04-16T14:45:56Z

⚠️ No Changeset found

Latest commit: 6011227

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

cloudflare-workers-and-pages · 2026-04-16T14:46:21Z

Deploying with Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Updated (UTC)
✅ Deployment successful! View logs	emdash-playground	`6011227`	Apr 16 2026, 02:47 PM

pkg-pr-new · 2026-04-16T14:47:36Z

Open in StackBlitz

@emdash-cms/admin

npm i https://pkg.pr.new/@emdash-cms/admin@602

@emdash-cms/auth

npm i https://pkg.pr.new/@emdash-cms/auth@602

@emdash-cms/blocks

npm i https://pkg.pr.new/@emdash-cms/blocks@602

@emdash-cms/cloudflare

npm i https://pkg.pr.new/@emdash-cms/cloudflare@602

emdash

npm i https://pkg.pr.new/emdash@602

create-emdash

npm i https://pkg.pr.new/create-emdash@602

@emdash-cms/gutenberg-to-portable-text

npm i https://pkg.pr.new/@emdash-cms/gutenberg-to-portable-text@602

@emdash-cms/x402

npm i https://pkg.pr.new/@emdash-cms/x402@602

@emdash-cms/plugin-ai-moderation

npm i https://pkg.pr.new/@emdash-cms/plugin-ai-moderation@602

@emdash-cms/plugin-atproto

npm i https://pkg.pr.new/@emdash-cms/plugin-atproto@602

@emdash-cms/plugin-audit-log

npm i https://pkg.pr.new/@emdash-cms/plugin-audit-log@602

@emdash-cms/plugin-color

npm i https://pkg.pr.new/@emdash-cms/plugin-color@602

@emdash-cms/plugin-embeds

npm i https://pkg.pr.new/@emdash-cms/plugin-embeds@602

@emdash-cms/plugin-forms

npm i https://pkg.pr.new/@emdash-cms/plugin-forms@602

@emdash-cms/plugin-webhook-notifier

npm i https://pkg.pr.new/@emdash-cms/plugin-webhook-notifier@602

commit: 6011227

Copilot

Pull request overview

Updates EmDash plugin documentation to standardize terminology (“native” vs “sandboxed”) and reduce confusion by adding a clearer, side-by-side comparison of execution modes and supported features.

Changes:

Renames “trusted” → “native” across plugin docs and reference pages.
Rewrites the sandbox page into a “Native vs. Sandboxed Plugins” comparison with tables, tabs, and decision guidance.
Corrects docs to state that sandboxed plugins do support API routes, and clarifies route handler signature differences by plugin format.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
docs/src/content/docs/reference/hooks.mdx	Updates page fragment injection wording to “native plugins” terminology.
docs/src/content/docs/plugins/sandbox.mdx	Full rewrite into a native vs sandboxed comparison and sandbox architecture explanation.
docs/src/content/docs/plugins/publishing.mdx	Updates terminology in bundling/publishing guidance.
docs/src/content/docs/plugins/overview.mdx	Shifts overview to sandbox-first framing and updates execution mode terminology.
docs/src/content/docs/plugins/installing.mdx	Updates install paths and marketplace vs config comparison using “native” terminology.
docs/src/content/docs/plugins/hooks.mdx	Updates hook docs and reference table to “native-only” for page fragments.
docs/src/content/docs/plugins/creating-plugins.mdx	Adds guidance on standard vs native formats; removes outdated “routes are trusted-only” note.
docs/src/content/docs/plugins/block-kit.mdx	Updates terminology in Block Kit positioning/description.
docs/src/content/docs/plugins/api-routes.mdx	Corrects claim about sandbox support and clarifies handler signature differences.
docs/src/content/docs/concepts/architecture.mdx	Updates architecture terminology from trusted → native.

Comments suppressed due to low confidence (1)

docs/src/content/docs/plugins/installing.mdx:122

Native plugins run in-process on any platform (including Cloudflare Workers), so saying they “have full access to Node.js APIs” (and the comparison table’s “Node.js APIs: Full access”) isn’t accurate outside Node deployments. Please reword to “full access to the host runtime APIs” and, if you want to call out Node specifically, scope it to Node.js deployments (e.g., filesystem/process.env/Node built-ins).

Native plugins:

- Run in-process (not sandboxed)
- Have full access to Node.js APIs
- Are loaded at build time and on every server start

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-16T14:51:39Z

 ---

-import { Aside, Card, CardGrid, Steps } from "@astrojs/starlight/components";
+import { Aside, Card, CardGrid, Steps, Tabs, TabItem } from "@astrojs/starlight/components";


The import list includes Card and CardGrid, but this page doesn't use either component. Unused imports can fail lint/typecheck in MDX tooling and add noise—please remove them or add the missing Card/CardGrid section if intended.

Suggested change

import { Aside, Card, CardGrid, Steps, Tabs, TabItem } from "@astrojs/starlight/components";

import { Aside, Steps, Tabs, TabItem } from "@astrojs/starlight/components";

Copilot · 2026-04-16T14:51:39Z

+Plugins can add custom block types to the Portable Text editor (YouTube embeds, code snippets, etc.). The editing UI uses Block Kit fields, which works in both modes. But rendering those blocks on the public site requires Astro components loaded at build time from npm -- so only native plugins can provide a `componentsEntry`.

-In trusted mode:
+Sandboxed plugins can still declare PT block types with editing fields. The site author just needs to provide their own rendering components or use a companion native package for rendering.


This section says sandboxed plugins can declare Portable Text block types (with editing fields) and only need help for site rendering. However, the bundler/runtime treats admin.portableTextBlocks as trusted/native-only (the CLI errors or warns that they’re ignored in sandboxed/marketplace plugins). Please update this text to reflect that sandboxed plugins can’t ship portableTextBlocks today (and adjust the guidance accordingly).

Copilot AI review requested due to automatic review settings April 16, 2026 14:45

github-actions bot added area/docs size/L labels Apr 16, 2026

github-actions bot added the cla: signed label Apr 16, 2026

Copilot started reviewing on behalf of ascorbic April 16, 2026 14:46 View session

Copilot AI reviewed Apr 16, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: rename trusted -> native, improve native vs sandboxed plugin comparison#602

docs: rename trusted -> native, improve native vs sandboxed plugin comparison#602
ascorbic wants to merge 1 commit intomainfrom
docs/native-vs-sandboxed-plugins

ascorbic commented Apr 16, 2026

Uh oh!

changeset-bot bot commented Apr 16, 2026

Uh oh!

cloudflare-workers-and-pages bot commented Apr 16, 2026 •

edited

Loading

Uh oh!

pkg-pr-new bot commented Apr 16, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 16, 2026

Uh oh!

Copilot AI Apr 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	import { Aside, Card, CardGrid, Steps, Tabs, TabItem } from "@astrojs/starlight/components";
	import { Aside, Steps, Tabs, TabItem } from "@astrojs/starlight/components";

Conversation

ascorbic commented Apr 16, 2026

What does this PR do?

Type of change

Checklist

AI-generated code disclosure

Files changed

Uh oh!

changeset-bot bot commented Apr 16, 2026

⚠️ No Changeset found

Uh oh!

cloudflare-workers-and-pages bot commented Apr 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying with Cloudflare Workers

Uh oh!

pkg-pr-new bot commented Apr 16, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

cloudflare-workers-and-pages bot commented Apr 16, 2026 •

edited

Loading