Documentation site for Mix — an expressive way to build design systems in Flutter.
This repository hosts the source for the Mix documentation website. It pairs a Next.js + Nextra docs frontend with a Flutter preview bundle so every widget example in the docs is a live, interactive Flutter app compiled to WebAssembly.
| Layer | Stack |
|---|---|
| Docs site | Next.js 15, Nextra 4, React 19, Tailwind CSS 4, TypeScript |
| Previews | Flutter 3.41+, Dart 3.11+, Mix 2+ |
| Search | Pagefind |
| Deployment | Vercel + GitHub Actions |
Install dependencies for both the website and the Flutter preview package:
pnpm install
(cd packages/mix_docs_preview && flutter pub get)Build the Flutter preview bundle and copy it into public/previews/:
bash packages/mix_docs_preview/scripts/build_web_previews.shStart the Next.js dev server:
pnpm devOpen http://localhost:3000 to view the docs.
Note
The Flutter bundle only needs to be rebuilt when you change preview code in packages/mix_docs_preview/. Regular MDX and component edits are hot-reloaded by Next.js.
.
├── src/
│ ├── app/ # Next.js app router
│ └── content/ # MDX documentation pages
├── components/ # React components (FlutterPreview, etc.)
├── packages/
│ └── mix_docs_preview/ # Flutter app that renders the previews
│ ├── lib/ # Preview widgets, mirrors the docs layout
│ ├── scripts/ # build_web_previews.sh
│ └── tool/ # Manifest generator
├── public/previews/ # Built Flutter web bundle (generated)
├── scripts/
│ ├── vercel-build.sh # Vercel build entrypoint
│ └── check-previews-manifest.mjs
└── .github/workflows/ # CI for validating previews
- Each preview is a Dart widget under
packages/mix_docs_preview/lib/organized to mirror the docs (overview/,guides/,widgets/,tutorials/,ecosystem/). - Widgets are registered in
lib/preview_registry.dartwith a doc-scopedpreviewId(e.g.widgets/box.0). build_web_previews.shcompiles the Flutter app to WebAssembly, extracts source files, and generatespreviews-manifest.json.- In MDX,
<FlutterPreview previewId="widgets/box.0" />loads the bundle and displays the widget alongside its source.
See packages/mix_docs_preview/README.md for details on adding a new preview.
| Command | What it does |
|---|---|
pnpm dev |
Run the Next.js dev server with Turbopack |
pnpm build |
Build the docs site for production |
pnpm start |
Serve the production build |
pnpm check:previews |
Validate previews-manifest.json integrity |
The site is deployed to Vercel. scripts/vercel-build.sh orchestrates the full build: it installs Flutter at the version pinned in .fvmrc, compiles the preview bundle to WASM, copies it into public/previews/, validates the manifest, and finally builds the Next.js app.
A matching GitHub Actions workflow (.github/workflows/preview-docs.yml) runs on pull requests to catch preview or manifest regressions before merge.
Important
Flutter web builds are CPU and memory intensive. Expect the preview build step to dominate CI time.