StreamMDX
HomeDocsGuidesDeployment And Security
Browse docs

Deployment and Security

This guide covers a production deployment pattern for StreamMDX with strict CSP, hosted worker assets, and controlled HTML rendering.

  1. Build your app and StreamMDX worker bundle in CI.
  2. Copy markdown-worker.js into static assets.
  3. Serve docs/app pages and worker from the same origin.
  4. Keep CSP strict (worker-src 'self') and avoid blob:.
bash
mkdir -p public/workers
cp node_modules/@stream-mdx/worker/dist/hosted/markdown-worker.js public/workers/markdown-worker.js

Then reference it explicitly:

tsx
<StreamingMarkdown worker="/workers/markdown-worker.js" />

CSP baseline

A conservative baseline for most deployments:

plain text
default-src 'self';
script-src 'self';
style-src 'self' 'unsafe-inline';
img-src 'self' data: https:;
worker-src 'self';
connect-src 'self' https:;

Notes:

  • style-src 'unsafe-inline' is often needed for runtime style injection in UI stacks.
  • If your stack supports nonce-based styles, prefer nonce over unrestricted inline styles.

HTML rendering policy

StreamMDX applies sanitization for untrusted HTML by default. Keep that enabled unless your input source is fully trusted and audited.

Operational policy:

  • Enable features.html only when required.
  • Prefer render-layer overrides (htmlElements) over sanitizer allowlist expansion.
  • Review any allowlist changes as security-sensitive changes.

MDX policy

MDX is code execution by design. Treat MDX input as trusted content unless you have a hardened compilation boundary.

  • For user-generated content, keep features.mdx disabled.
  • For trusted editorial content, enforce review + snapshot tests before publish.

Release hardening checklist

  • [ ] Hosted worker copied to static path and versioned with app deploy.
  • [ ] CSP validated in production response headers.
  • [ ] features.html and features.mdx configured intentionally (not accidental defaults).
  • [ ] Regression snapshots updated and reviewed.
  • [ ] Perf harness run attached to release notes.

Incident response quick path

If a production issue appears in rendered output:

  1. Disable risky feature flag (html or mdx) first.
  2. Roll back to previous worker bundle + app release.
  3. Compare regression snapshots to isolate the rendering delta.
  4. Patch and redeploy with a new snapshot/perf report.

Vercel notes

For this monorepo docs app on Vercel:

  • Root Directory: apps/docs
  • Build Command: cd ../.. && npm run docs:build
  • Install Command: cd ../.. && npm ci
  • Output Directory: apps/docs/out
  • Include files outside root directory: Enabled

This is required so Vercel can access workspace packages and build the hosted worker.

PreviousArchitecture and InternalsNextMermaid Diagrams