Skip to content

Commit 1e5fdae

Browse files
rsbhclaude
rsbh
and
claude
committed
revert: remove mdx-loader.ts, restore inline import.meta.glob
Extracting import.meta.glob to a shared module caused hydration mismatch — SSR and client Vite environments compiled MDX differently. Restore inline globs in entry-client.tsx (client-only) and source.ts (SSR-only) to keep each environment's compilation isolated. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 67113f8 commit 1e5fdae

5 files changed

Lines changed: 585 additions & 23 deletions

File tree

‎ADR/001-vite-migration.md‎

Lines changed: 218 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,218 @@
1+
# ADR-001: Migrate from Next.js to Vite
2+
3+
**Status:** Discussion
4+
**Date:** 2026-03-20
5+
6+
## Context
7+
8+
Chronicle is a config-driven documentation framework. The CLI (`chronicle dev/build/start`) currently scaffolds a Next.js project at runtime and spawns the Next.js binary as a child process.
9+
10+
## Why Next.js is problematic
11+
12+
### 1. Binary resolution
13+
- CLI must locate and spawn `next/dist/bin/next` via `createRequire`
14+
- Breaks in pnpm (strict node_modules), monorepos (hoisting), global installs (`npx chronicle dev`)
15+
16+
### 2. Scaffold hack
17+
- Copies `src/`, `source.config.ts`, `tsconfig.json` into `.chronicle/` at runtime
18+
- Generates `next.config.mjs` on the fly
19+
- Symlinks content dir into scaffold
20+
- Runs `npm install` in user's project
21+
- Fragile — a fake Next.js project scaffolded every time
22+
23+
### 3. Turbopack filesystem root boundary
24+
- Symlinks pointing outside monorepo root rejected by Turbopack
25+
- Docker mounts at `/content` break — Turbopack won't follow them
26+
27+
### 4. Heavy dependency
28+
- `next@16` pulls in Turbopack, SWC, webpack — all for a docs site
29+
- Slow install, heavy CI
30+
31+
### 5. No programmatic API
32+
- Next.js must be spawned as child process (`spawn(nextCli, ['dev'])`)
33+
- Signal handling (`Ctrl+C`) needs workarounds
34+
- Cannot embed cleanly into CLI
35+
36+
## What we gain with Vite
37+
38+
| Benefit | Impact |
39+
|---|---|
40+
| Programmatic API | `createServer()` / `build()` — no binary spawning, no scaffold hack |
41+
| No symlink issues | `resolve.alias` handles content dir cleanly |
42+
| Lighter dependency | ~10x smaller than Next.js |
43+
| Faster dev startup | On-demand compilation |
44+
| Simpler architecture | CLI directly creates Vite server, no `.chronicle/` scaffolding |
45+
46+
## What we lose leaving Next.js
47+
48+
| Feature | Next.js provides | Replacement needed | Priority |
49+
|---|---|---|---|
50+
| SSR/SSG | Built-in `generateStaticParams` | Vite SSR + custom build | TODO |
51+
| API routes | `app/api/` | Custom server or `vite.ssrLoadModule` | TODO |
52+
| Image optimization | `next/image` | None or external | TODO |
53+
| ISR | Incremental static regen | Likely not needed for docs | TODO |
54+
| Middleware | Edge middleware | Likely not needed for docs | TODO |
55+
| Ecosystem | Large plugin ecosystem | Smaller but growing | TODO |
56+
57+
## Prior art: How Mintlify uses Next.js
58+
59+
Mintlify (`@mintlify/cli`) has a similar CLI and faces the same problems. They solve it with a fundamentally different architecture: **pre-built app + runtime content injection**.
60+
61+
### Overview
62+
63+
The docs site (Next.js app with components, layouts, themes) is developed in a **private repo** (`mintlify/mint`). Users never see this source code. Mintlify's CI builds it into a Next.js standalone output and uploads it as a tarball to `releases.mintlify.com`.
64+
65+
The open-source CLI (`@mintlify/cli`) is just a **thin wrapper** that:
66+
1. Downloads the pre-built app
67+
2. Injects user's content into it
68+
3. Starts a local server
69+
70+
### Directory structure
71+
72+
```
73+
~/.mintlify/mint/ ← global, shared across all projects
74+
├── apps/client/
75+
│ ├── .next/ ← pre-built Next.js standalone output
76+
│ ├── src/_props/ ← user's compiled content injected here
77+
│ ├── public/ ← user's static assets copied here
78+
│ └── node_modules/ ← bundled Next.js + all deps
79+
└── mint-version.txt ← tracks downloaded version
80+
```
81+
82+
```
83+
your-project/ ← user's docs project
84+
├── docs/
85+
│ ├── getting-started.mdx
86+
│ └── api-reference.mdx
87+
├── mint.json ← config (nav, theme, etc.)
88+
└── images/
89+
```
90+
91+
### How `mintlify dev` works (step by step)
92+
93+
**Step 1: Download (one-time)**
94+
- On first run, CLI downloads tarball from `releases.mintlify.com/mint-{version}.tar.gz`
95+
- Extracts to `~/.mintlify/mint/`
96+
- Version tracked in `mint-version.txt`, checked on subsequent runs
97+
98+
**Step 2: Prebuild (every run + every file change)**
99+
- CLI reads MDX from user's cwd
100+
- Compiles MDX → serialized JSON/JS (not raw MDX — already compiled to renderable data)
101+
- Writes output to `~/.mintlify/mint/apps/client/src/_props/`
102+
- Copies images/static assets to `~/.mintlify/mint/apps/client/public/`
103+
- Content **leaves the user's project directory** and is injected into the global app
104+
105+
**Step 3: Start server (in-process, not spawned)**
106+
```js
107+
// Mintlify's setupNext.js (simplified)
108+
// 1. Read Next.js config from pre-built output
109+
const config = JSON.parse(readFile('.next/required-server-files.json'))
110+
process.env.__NEXT_PRIVATE_STANDALONE_CONFIG = JSON.stringify(config)
111+
112+
// 2. Import Next.js internals directly (not spawn)
113+
await import('next/dist/server/next.js') // side-effect initialization
114+
const { initialize } = await import('next/dist/server/lib/router-server.js')
115+
const requestHandler = await initialize(...)
116+
117+
// 3. Wrap in Express + Socket.io
118+
const app = express()
119+
app.use('/', express.static(NEXT_PUBLIC_PATH))
120+
app.all('*', (req, res) => requestHandler(req, res))
121+
```
122+
123+
The Next.js request handler runs **in the same Node.js process** as the CLI. No child process.
124+
125+
**Step 4: File watching (fake HMR)**
126+
- `chokidar` watches user's cwd for file changes
127+
- On change → `prebuild()` re-compiles changed MDX → overwrites `_props/` files
128+
- Server emits Socket.io `reload` event
129+
- Client-side JS does `window.location.reload()` — **full page reload, not real HMR**
130+
131+
### Content as runtime dependency
132+
133+
This is the key architectural difference from Chronicle:
134+
135+
- The pre-built Next.js app has **no content baked in**
136+
- Pages are designed to read from `_props/` at **request time** (SSR)
137+
- On each request: Next.js page component reads `_props/{slug}.json` → renders to HTML → returns
138+
139+
```
140+
// Simplified page component inside the pre-built app
141+
async function DocsPage({ params }) {
142+
const content = await readFile(`_props/${params.slug}.json`) // runtime read
143+
return <Layout>{render(content)}</Layout>
144+
}
145+
```
146+
147+
Content is a **runtime dependency**, not a build-time dependency. The app never needs to be rebuilt — only `_props/` data files change.
148+
149+
### SSR behavior
150+
151+
The pre-built app runs in **production mode** (equivalent to `next start`):
152+
1. Browser requests `/docs/getting-started`
153+
2. Next.js server receives request
154+
3. Page reads pre-compiled content from `_props/getting-started.json`
155+
4. React renders to HTML **server-side**
156+
5. Returns full HTML → client hydrates
157+
158+
MDX is already compiled by the CLI's `prebuild()`. Server just deserializes and renders. No MDX compilation at request time.
159+
160+
There is **no SSG** — everything is SSR per request, both locally and on their hosted product.
161+
162+
### Problems with this approach
163+
164+
| Problem | Detail |
165+
|---|---|
166+
| No real HMR | Full page reload on every content change — no React fast refresh, no state preservation |
167+
| Content in two places | Lives in your project AND `~/.mintlify/mint/_props/` — source of truth confusion |
168+
| No concurrent projects | Multiple projects share `~/.mintlify/mint/` — can't run two `mintlify dev` simultaneously |
169+
| Stale content | If prebuild crashes, old content remains in `_props/` |
170+
| No SSG | Everything is SSR — no static HTML generation, no build-time optimization |
171+
| Sealed black box | Users can't customize components/layouts — the app is pre-built |
172+
| Internal APIs | Uses `next/dist/server/lib/router-server.js` — undocumented, can break across Next.js versions |
173+
| Distribution overhead | Hosting tarballs, version management between CLI and app, ~100MB+ download |
174+
175+
### How they sidestep the problems Chronicle has
176+
177+
| Problem | Chronicle (current) | Mintlify's solution |
178+
|---|---|---|
179+
| Binary resolution | `createRequire` to find `next` binary — breaks across pkg managers | Avoided — Next.js bundled in tarball at fixed path |
180+
| Scaffold hack | Copies src + config into `.chronicle/` every time | Pre-built standalone downloaded once, reused |
181+
| Content dir | Symlinks into scaffold — Turbopack rejects cross-root symlinks | `prebuild()` copies content — no symlinks |
182+
| Package manager compat | Fragile across pnpm/yarn/npm | N/A — no dependency on user's `node_modules` |
183+
| Dev server | Child process `spawn(nextCli, ['dev'])` | In-process import of Next.js request handler |
184+
185+
### Comparison: Content handling
186+
187+
| | Chronicle (current) | Mintlify | Vite (proposed) |
188+
|---|---|---|---|
189+
| Content is | Build-time dependency | Runtime dependency | Build-time dependency |
190+
| MDX compiled by | Next.js + fumadocs-mdx | CLI `prebuild()` | Vite + @mdx-js/rollup |
191+
| Next.js/Vite role | Full compiler + server | Just a server/renderer | Full compiler + server |
192+
| HMR | Real (React fast refresh) | Fake (full page reload) | Real (Vite native HMR) |
193+
| SSG support | Yes (`generateStaticParams`) | No (SSR only) | Possible (custom build) |
194+
195+
### Takeaway
196+
197+
This gives us a **third option**: keep Next.js but adopt a pre-built tarball approach instead of runtime scaffolding. It solves the binary/scaffold/symlink problems but introduces new ones: no real HMR, no SSG, sealed app, distribution complexity, and reliance on Next.js internal APIs.
198+
199+
## Proposed stack
200+
201+
- **Vite** — dev server + build (programmatic API)
202+
- **React Router** — client/server routing
203+
- **`fumadocs-core`** — page tree, sidebar, breadcrumbs, TOC, search, mdx-plugins, React Router adapter
204+
- **`@mdx-js/rollup`** — MDX compilation (not fumadocs-mdx)
205+
- **`gray-matter`** — frontmatter parsing for content discovery
206+
- **No `fumadocs-mdx`** — see [ADR-002](./002-fumadocs-usage.md) for details
207+
208+
## Open questions
209+
210+
- [ ] Is Vite SSR + React Router sufficient for static site generation?
211+
- [ ] HMR story for content changes?
212+
- [ ] Docker support with Vite?
213+
214+
## Decision
215+
216+
**Migrate to Vite with fumadocs-core (without fumadocs-mdx).**
217+
218+
See [ADR-002](./002-fumadocs-usage.md) for the fumadocs decision.

0 commit comments

Comments
 (0)