chore(devx): reduce docs dev cold-load latency

[dcrawbuck]

Summary

This PR reduces the cold bun run dev -> first /docs/ load path for the docs site.

The main root cause was not Vite startup itself. It was eager whole-corpus work happening during the initial app graph load:

• src/routes/api/search.ts was calling createFromSource(source) at module import time.
• fumadocs-core starts building the local Orama search index immediately when that API is created.
• Because TanStack Start pulls route modules into the graph, the first docs request was paying for a full docs index build before the page was ready.

This PR moves that search-index work behind a lazy getter so it only runs when /api/search is actually hit.

It also keeps a few dev-only MDX reductions that improve the first docs load without changing production builds:

• Fumadocs async mode in development
• disable processed markdown generation in development
• disable Shiki code highlighting in development

Changes

• Lazy-init the local search API in src/routes/api/search.ts
• Enable async docs loading in dev in source.config.ts
• Skip processed markdown generation in dev in source.config.ts
• Fall back to raw markdown for dev-only LLM text endpoints in:
  • src/lib/source.ts
  • src/routes/llms[.]mdx.docs.$.ts
• Disable Shiki highlighting in dev in source.config.ts
• Add a one-off benchmark script at scripts/dev-benchmark.ts

Benchmark

Command:

bun run scripts/dev-benchmark.ts

Current run on this branch:

Step                   Duration  Status
---------------------  --------  ------
Dev ready              3.23s     -
First /docs/ request   2.45s     200
Start -> first /docs/  5.68s     200
Second docs page       0.18s     200
Full benchmark         5.86s     -

Before this work, the user was seeing roughly 28s for the equivalent cold path.

In repeated local runs after the fix, Start -> first /docs/ was generally in the ~5-6s range.

Approximate contribution breakdown

These changes interact, so the safest numbers are ablations: remove one change from the faster version and see how much the benchmark regresses.

• Remove lazy search init:
  • ~5.7s -> ~11.4s
• Remove Fumadocs async dev loading:
  • ~5.7s -> ~17.6s
• Re-enable processed markdown generation in dev:
  • ~5.7s -> ~5.7-5.9s
• Re-enable Shiki highlighting in dev:
  • ~5.7s -> ~5.1-5.9s depending on run variance

Roughly speaking, the biggest wins are:

1. lazy search init
2. async docs loading in dev
3. smaller dev-only MDX reductions

Tradeoffs

• First local /api/search request is slower, because it now pays the index build on first use instead of during startup.
• Dev-only LLM markdown endpoints return raw markdown instead of processed markdown.
• Code blocks in dev lose syntax highlighting.
• Production build behavior is unchanged.

Validation

• bun test ✅
• bun run build ⚠️ still fails on the existing prerender 404 for /docs/web-checkout/web-checkout-overview (pre-existing, unrelated to this perf work)

---

Note

Medium Risk
Moderate risk because it changes initialization timing for the /api/search server (now lazy), which can shift work to first request and affect concurrency/edge-case behavior; other changes are dev-only MDX output differences.

Overview
Speeds up local docs cold loads by deferring expensive work off the initial dev startup path: /api/search now lazily creates the Orama-backed search server on first request instead of at module import.

Adjusts docs/MDX processing in development to reduce first-request cost: disables processed markdown generation and Shiki highlighting in dev, and updates LLM markdown endpoints (getLLMText and /llms.mdx/docs/$) to serve raw text in dev while keeping processed for non-dev.

Adds scripts/dev-benchmark.ts to automate measuring bun run dev readiness and a couple of /docs request latencies.

^{Written by Cursor Bugbot for commit 86716eb. This will update automatically on new commits. Configure here.}

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

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

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	superwall-docs-staging	86716eb	Commit Preview URL Branch Preview URL	Mar 16 2026, 10:58 PM

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}