StreamMDX
HomeDocsRelease Checklist
Browse docs

StreamMDX — Release Checklist

_Last updated: 2025-12-17_

Use this checklist when cutting releases from the stream-mdx/ repo. It assumes the current workspace scripts in package.json.

1. Preflight (local)

  1. Install deps (clean) ```bash npm ci ```
  2. Build packages
  3. npm run build runs all workspace builds (npm --workspaces --if-present run build). ```bash npm run build ```
  4. Sourcemap policy sanity check
  5. Default: no sourcemaps are emitted by package builds.
  6. Optional: enable sourcemaps for local debugging by setting SOURCEMAP=1. ```bash SOURCEMAP=1 npm run build ```
  7. Build the hosted worker + copy to examples ```bash npm run worker:build ```
  8. Run tests ```bash npm test ```
  9. Local regression baselines (local-only, recommended) ```bash npm run test:regression:html npm run test:regression:styles ```
  10. HTML snapshots capture streaming checkpoints (5/10/25/50/75/90/100%) and run both typical + extreme scenarios for stress fixtures.
  11. Format anticipation is enabled by default in the regression harness.
  12. To update baselines, re-run with UPDATE_SNAPSHOTS=1.
  13. CSS parity checks to confirm after styles update:
  14. Table row borders (dark mode)
  15. Blockquote + footnote color alignment
  16. Preview + code adjacency (no top gap/radius)
  17. Perf baseline capture (optional, local) ```bash NEXT_PUBLIC_STREAMING_DEMO_API=true npm run docs:dev npm run perf:demo -- --rate 12000 --tick 5 --runs 1 ```
  18. Output includes a longTasks summary (count, total duration, max, p95).
  19. Baseline runs are tracked in docs/perf/LOCAL_BENCHMARKS.md.
  20. Perf compare + changelog update (recommended) ```bash npm run perf:compare -- --base tmp/perf-baselines/<baseline> --candidate tmp/perf-baselines/<candidate> ```
  21. Record the deltas in docs/PERF_QUALITY_CHANGELOG.md.
  22. Update docs/perf/LOCAL_BENCHMARKS.md when new baselines are captured.
  23. Sanity-check hosted worker outputs
  24. Built worker artifact:
  25. packages/markdown-v2-worker/dist/hosted/markdown-worker.js
  26. Copied artifact (for the example app):
  27. examples/streaming-markdown-starter/public/workers/markdown-worker.js

2. Pack + external install gate (high signal)

This is the most reliable “will npm users succeed?” gate.

Runs a fully automated pack+install+next build using the included starter (no workspace links):

bash
npm run ci:pack-smoke

2.2 Manual pack (optional)

  1. Pack tarballs locally ```bash mkdir -p tmp/release-packs (cd packages/markdown-v2-core && npm pack --pack-destination ../../tmp/release-packs) (cd packages/markdown-v2-plugins && npm pack --pack-destination ../../tmp/release-packs) (cd packages/markdown-v2-protocol && npm pack --pack-destination ../../tmp/release-packs) (cd packages/markdown-v2-worker && npm pack --pack-destination ../../tmp/release-packs) (cd packages/markdown-v2-react && npm pack --pack-destination ../../tmp/release-packs) (cd packages/markdown-v2-mermaid && npm pack --pack-destination ../../tmp/release-packs) (cd packages/markdown-v2-tui && npm pack --pack-destination ../../tmp/release-packs) (cd packages/theme-tailwind && npm pack --pack-destination ../../tmp/release-packs) (cd packages/stream-mdx && npm pack --pack-destination ../../tmp/release-packs) ```
  2. In a clean scratch dir, install from tarballs and build
  3. Minimum expectation:
  4. npm install ./tmp/release-packs/*.tgz (or explicit paths)
  5. next build succeeds for a simple Next app using stream-mdx (or @stream-mdx/react)
  6. If you use the included starter:
  7. point the starter deps at the tarballs (no workspace/file links)
  8. ensure it can npm install, npm run worker:build, and npm run build

3. Versioning & tagging (Changesets)

This repo is set up for Changesets.

  1. Add changesets for the release ```bash npm run changeset ```
  2. Version packages ```bash npm run changeset:version ```
  3. Commit
  4. Example:
  5. chore(release): version packages
  6. Tag (optional but recommended)
  7. Prefer a single repo tag per release:
  8. v0.0.1 / v0.1.0 / v1.0.0

4. Publish

  1. Ensure you are logged into npm ```bash npm whoami ```
  2. Trusted Publishing (recommended)
  3. Configure npm “Trusted Publisher” for:
  4. @stream-mdx/core
  5. @stream-mdx/plugins
  6. @stream-mdx/protocol
  7. @stream-mdx/worker
  8. @stream-mdx/react
  9. @stream-mdx/mermaid
  10. @stream-mdx/tui
  11. @stream-mdx/theme-tailwind
  12. stream-mdx
  13. Required workflow permissions:
  14. id-token: write
  15. Workflows:
  16. .github/workflows/release.yml (auto release PRs / publish)
  17. .github/workflows/publish.yml (manual workflow_dispatch)
  18. Publish via Changesets ```bash npm run changeset:publish ```
  19. Optional: local interactive publish helper ```bash scripts/publish-v0.4.0.sh ```
  20. Requires npm login --auth-type=web.
  21. Publishes in dependency order, verifies all local versions match, and skips packages already published at that version.
  22. Confirm all packages are published
  23. @stream-mdx/core
  24. @stream-mdx/plugins
  25. @stream-mdx/protocol
  26. @stream-mdx/worker
  27. @stream-mdx/react
  28. @stream-mdx/mermaid
  29. @stream-mdx/tui
  30. @stream-mdx/theme-tailwind
  31. stream-mdx

5. CI gates (current repo)

This repo’s CI (.github/workflows/ci.yml) enforces:

  • npm ci
  • npm run build
  • npm test
  • npm -ws --if-present pack --dry-run
  • npm run ci:pack-smoke (pack+install+next build)

Before publishing, run the same commands locally (plus the external install gate in §2).

6. Post-publish checks

  1. Verify npm README renders
  2. stream-mdx should display packages/stream-mdx/README.md on npmjs.com.
  3. Verify docs + demo links
  4. Docs: https://kmccleary3301.github.io/stream-mdx/
  5. Demo: https://kmccleary3301.github.io/stream-mdx/demo
  6. Showcase: https://kmccleary3301.github.io/stream-mdx/showcase
  7. Verify hosted worker guidance
  8. The worker is expected at /workers/markdown-worker.js in most examples.
  9. Confirm Trusted Publishing works
  10. Once configured on npm, use .github/workflows/publish.yml (manual) or .github/workflows/release.yml (auto).

7. Docs & release notes

  • Update docs/STREAMING_MARKDOWN_V2_STATUS.md as implementation details change.
  • Publish release notes via GitHub Releases (recommended), or add a CHANGELOG.md if you want a file-based changelog.
  • When publishing packages, ensure badges and docs links remain correct.

8. Rollback plan

  • Tag every release; rollback is typically “revert and republish as -patch” or “yank with npm deprecate + publish fix”.
  • Keep the hosted worker build deterministic so it can be regenerated from tags.
PreviousPlugins cookbookNextPerf harness