Skip to content

perf: lazy-load wagmi providers only on interactive pages#266

Merged
brendanjryan merged 1 commit intomainfrom
perf/lazy-load-providers
Apr 10, 2026
Merged

perf: lazy-load wagmi providers only on interactive pages#266
brendanjryan merged 1 commit intomainfrom
perf/lazy-load-providers

Conversation

@brendanjryan
Copy link
Copy Markdown
Contributor

@brendanjryan brendanjryan commented Apr 10, 2026

Problem

Every MDX page (198 pages) was wrapped in <Providers> which eagerly loaded wagmi + viem + tanstack-query + accounts SDK (121 KB brotli / 590 KB raw). Only 24 pages actually use interactive wallet demos.

Solution

Pages opt in via frontmatter interactive: true. The _mdx-wrapper uses React.lazy to load Providers only when this flag (or mipd) is set. Content pages never download or parse the wagmi bundle.

---
interactive: true
---

Measured impact

Lighthouse network audit (dev server, before → after on /learn/tempo):

Metric Before After
wagmi scripts loaded 4 (239 KB) 0
Total scripts 579 (33.7 MB) 543 (29.9 MB)
TBT (desktop, avg) ~490ms ~370ms (−25%)
Perf score (desktop) 51–53 63–67 (+10–16 pts)

Changes

  • _mdx-wrapper.tsxReact.lazy + frontmatter check, documented
  • 24 MDX pages — added interactive: true frontmatter
  • scripts/bundle-diff.ts — scans dist/, brotli-compresses, groups into framework/heavy-deps/app
  • scripts/lighthouse.ts — runs Lighthouse across worst pages, supports --save/--compare
  • New scripts: bundle:analyze, bundle:diff, bundle:save, lighthouse, lighthouse:mobile

@vercel
Copy link
Copy Markdown

vercel bot commented Apr 10, 2026

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
tempo-docs Ready Ready Preview, Comment Apr 10, 2026 5:09pm

Request Review

Copy link
Copy Markdown

@chatgpt-codex-connector chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: fb29394a20

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

const Providers = React.lazy(() => import('../components/Providers'))

/** Path prefixes that need the Wagmi/QueryClient provider tree for interactive demos. */
const PROVIDER_PATH_PREFIXES = ['/guide/', '/quickstart/', '/accounts/']
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Include /accounts root in provider-gated routes

The new route gate only matches prefixes ending with a slash (/accounts/), so the actual Accounts landing page at /accounts does not get wrapped in Providers. That page renders interactive demo steps (src/pages/accounts/index.mdx) that rely on Wagmi/React Query context (for example useConnection in steps/auth/Connect.tsx), so visiting /accounts can leave the demo non-functional or throw missing-provider errors. Add an exact /accounts match (or normalize path matching) so the root page is covered.

Useful? React with 👍 / 👎.

return (
<Layout>
<Providers mipd={context.frontmatter?.mipd as boolean | undefined}>{children}</Providers>
{needsProviders ? (
<React.Suspense fallback={children}>
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Do not render provider-dependent children as Suspense fallback

Using fallback={children} causes the same MDX tree to render without Providers while the lazy import is loading. On interactive routes, those children include components that call Wagmi hooks, so a cold load/navigation can render hooks outside WagmiProvider/QueryClientProvider before the chunk resolves, leading to runtime errors or hydration instability. The fallback should be a neutral loading UI (or null), not provider-dependent content.

Useful? React with 👍 / 👎.

Previously every MDX page was wrapped in <Providers> which eagerly
loaded wagmi + viem + tanstack-query + accounts SDK (121 KB brotli).
Only ~24 pages actually use interactive wallet demos.

Pages now opt in via frontmatter `interactive: true`. The _mdx-wrapper
uses React.lazy to load Providers only when this flag (or `mipd`) is
set. Content pages no longer fetch the wagmi bundle at all.

Measured: -36 scripts, -3.9 MB JS on content pages, -25% TBT.

Also adds bundle:analyze and lighthouse measurement scripts.
@brendanjryan brendanjryan force-pushed the perf/lazy-load-providers branch from 8446420 to 3580c13 Compare April 10, 2026 17:05
@brendanjryan brendanjryan merged commit fc7ba4a into main Apr 10, 2026
9 checks passed
@brendanjryan brendanjryan deleted the perf/lazy-load-providers branch April 10, 2026 17:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant