refactor: migrate MDX components to dynamic imports

Convert MDX component loading from synchronous require() calls to
async dynamic imports for improved code splitting and performance.

Changes:
- Update generate-metadata.mjs to generate dynamic import syntax
- Convert getArticleComponents/getDocComponents to getArticleComponent/getDocComponent
- Change component retrieval functions to async
- Update all page components to await component loading
- Remove @typescript-eslint/no-require-imports rule from ESLint config

This migration enables better chunk optimization and reduces initial
bundle size by loading MDX content on demand.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: ericyangpan

eslint.config.mjs

@@ -11,12 +11,6 @@ const compat = new FlatCompat({
 
 const eslintConfig = [
   ...compat.extends("next/core-web-vitals", "next/typescript"),
-  {
-    rules: {
-      // Allow require() for MDX component imports (webpack handles these at build time)
-      "@typescript-eslint/no-require-imports": "off",
-    },
-  },
 ];
 
 export default eslintConfig;

scripts/generate-metadata.mjs

@@ -246,15 +246,15 @@ function generateArticleComponentsCode(articles) {
   for (const locale of locales) {
     const localeArticles = articles[locale];
     const componentEntries = localeArticles.map(article =>
-      `    '${article.slug}': require('@content/articles/${locale}/${article.slug}.mdx').default,`
+      `    '${article.slug}': () => import('@content/articles/${locale}/${article.slug}.mdx'),`
     ).join('\n');
 
     if (componentEntries) {
       componentLines.push(`  '${locale}': {\n${componentEntries}\n  },`);
     }
   }
 
-  return `const articleComponents: Record<string, Record<string, React.ComponentType>> = {\n${componentLines.join('\n')}\n};`;
+  return `const articleComponents: Record<string, Record<string, () => Promise<{ default: React.ComponentType }>>> = {\n${componentLines.join('\n')}\n};`;
 }
 
 // Generate component imports for docs
@@ -265,15 +265,15 @@ function generateDocComponentsCode(docs) {
   for (const locale of locales) {
     const localeDocs = docs[locale];
     const componentEntries = localeDocs.map(doc =>
-      `    '${doc.slug}': require('@content/docs/${locale}/${doc.slug}.mdx').default,`
+      `    '${doc.slug}': () => import('@content/docs/${locale}/${doc.slug}.mdx'),`
     ).join('\n');
 
     if (componentEntries) {
       componentLines.push(`  '${locale}': {\n${componentEntries}\n  },`);
     }
   }
 
-  return `const docComponents: Record<string, Record<string, React.ComponentType>> = {\n${componentLines.join('\n')}\n};`;
+  return `const docComponents: Record<string, Record<string, () => Promise<{ default: React.ComponentType }>>> = {\n${componentLines.join('\n')}\n};`;
 }
 
 // Generate component import for manifesto (single index.mdx per locale)
@@ -283,11 +283,11 @@ function generateManifestoComponentsCode() {
   for (const locale of SUPPORTED_LOCALES) {
     const manifestoIndex = path.join(rootDir, `content/manifesto/${locale}/index.mdx`);
     if (fs.existsSync(manifestoIndex)) {
-      componentLines.push(`    '${locale}': require('@content/manifesto/${locale}/index.mdx').default,`);
+      componentLines.push(`    '${locale}': () => import('@content/manifesto/${locale}/index.mdx'),`);
     }
   }
 
-  return `  const components: Record<string, React.ComponentType> = {\n${componentLines.join('\n')}\n  };`;
+  return `  const components: Record<string, () => Promise<{ default: React.ComponentType }>> = {\n${componentLines.join('\n')}\n  };`;
 }
 
 // Main execution
@@ -359,12 +359,16 @@ export function getArticleBySlug(slug: string, locale: string = 'en'): ArticleMe
   return localeArticles.find((article) => article.slug === slug);
 }
 
-// MDX components mapping for all locales (webpack will handle this at build time)
+// MDX components mapping for all locales (dynamic imports)
 ${articlesComponentsCode}
 
-// Get components for a specific locale with fallback to English
-export function getArticleComponents(locale: string = 'en'): Record<string, React.ComponentType> {
-  return articleComponents[locale] || articleComponents['en'] || {};
+// Get a specific article component for a given locale and slug
+export async function getArticleComponent(locale: string = 'en', slug: string): Promise<React.ComponentType | null> {
+  const loaders = articleComponents[locale] || articleComponents['en'];
+  const loader = loaders?.[slug];
+  if (!loader) return null;
+  const mdxModule = await loader();
+  return mdxModule.default;
 }
 `;
 
@@ -397,12 +401,16 @@ export function getDocBySlug(slug: string, locale: string = 'en'): DocSection |
   return sections.find((doc) => doc.slug === slug);
 }
 
-// MDX components mapping for all locales (webpack will handle this at build time)
+// MDX components mapping for all locales (dynamic imports)
 ${docsComponentsCode}
 
-// Get components for a specific locale with fallback to English
-export function getDocComponents(locale: string = 'en'): Record<string, React.ComponentType> {
-  return docComponents[locale] || docComponents['en'] || {};
+// Get a specific doc component for a given locale and slug
+export async function getDocComponent(locale: string = 'en', slug: string): Promise<React.ComponentType | null> {
+  const loaders = docComponents[locale] || docComponents['en'];
+  const loader = loaders?.[slug];
+  if (!loader) return null;
+  const mdxModule = await loader();
+  return mdxModule.default;
 }
 `;
 
@@ -417,10 +425,12 @@ export function getDocComponents(locale: string = 'en'): Record<string, React.Co
  * Return the Manifesto MDX React component for a given locale.
  * Falls back to the default locale ('en') when the requested locale is missing.
  */
-export function getManifestoComponent(locale: string = 'en'): React.ComponentType {
+export async function getManifestoComponent(locale: string = 'en'): Promise<React.ComponentType> {
 ${manifestoComponentsCode}
 
-  return components[locale] || components['en'];
+  const loader = components[locale] || components['en'];
+  const mdxModule = await loader();
+  return mdxModule.default;
 }
 `;
 

src/app/[locale]/ai-coding-stack/page.tsx

@@ -46,7 +46,7 @@ type Props = {
 export default async function AICodingStackPage({ params }: Props) {
   const { locale } = await params;
   const t = await getTranslations({ locale, namespace: 'stacksPages.overview' });
-  const ManifestoContent = getManifestoComponent(locale);
+  const ManifestoContent = await getManifestoComponent(locale);
 
   return (
     <>

src/app/[locale]/articles/[slug]/page.tsx

@@ -2,7 +2,7 @@ import { Link } from '@/i18n/navigation';
 import { notFound } from 'next/navigation';
 import Header from '@/components/Header';
 import Footer from '@/components/Footer';
-import { getArticles, getArticleBySlug, getArticleComponents } from '@/lib/generated/articles';
+import { getArticles, getArticleBySlug, getArticleComponent } from '@/lib/generated/articles';
 import { generateArticleMetadata } from '@/lib/metadata';
 
 type Props = {
@@ -53,8 +53,7 @@ export default async function ArticlePage({ params }: Props) {
     notFound();
   }
 
-  const articleComponents = getArticleComponents(locale);
-  const ArticleContent = articleComponents[slug];
+  const ArticleContent = await getArticleComponent(locale, slug);
 
   if (!ArticleContent) {
     return (

src/app/[locale]/docs/[slug]/page.tsx

@@ -3,7 +3,7 @@ import { notFound } from 'next/navigation';
 import Header from '@/components/Header';
 import Footer from '@/components/Footer';
 import DocsSidebar from '@/components/sidebar/DocsSidebar';
-import { getDocSections, getDocBySlug, getDocComponents } from '@/lib/generated/docs';
+import { getDocSections, getDocBySlug, getDocComponent } from '@/lib/generated/docs';
 import { generateDocsMetadata } from '@/lib/metadata';
 
 type Props = {
@@ -53,8 +53,7 @@ export default async function DocPage({ params }: Props) {
   }
 
   const docSections = getDocSections(locale);
-  const docComponents = getDocComponents(locale);
-  const DocContent = docComponents[slug];
+  const DocContent = await getDocComponent(locale, slug);
 
   if (!DocContent) {
     return (

src/app/[locale]/docs/page.tsx

@@ -1,7 +1,7 @@
 import Header from '@/components/Header';
 import Footer from '@/components/Footer';
 import DocsSidebar from '@/components/sidebar/DocsSidebar';
-import { getDocSections, getDocComponents } from '@/lib/generated/docs';
+import { getDocSections, getDocComponent } from '@/lib/generated/docs';
 import { getTranslations } from 'next-intl/server';
 import { buildCanonicalUrl, buildOpenGraph, buildTwitterCard, buildTitle } from '@/lib/metadata';
 
@@ -45,8 +45,7 @@ export async function generateMetadata({ params }: { params: Promise<{ locale: s
 export default async function DocsPage({ params }: Props) {
   const { locale } = await params;
   const docSections = getDocSections(locale);
-  const docComponents = getDocComponents(locale);
-  const WelcomeDoc = docComponents['welcome'];
+  const WelcomeDoc = await getDocComponent(locale, 'welcome');
   return (
     <>
       <Header />

src/lib/generated/articles.ts

@@ -24,23 +24,27 @@ export function getArticleBySlug(slug: string, locale: string = 'en'): ArticleMe
   return localeArticles.find((article) => article.slug === slug);
 }
 
-// MDX components mapping for all locales (webpack will handle this at build time)
-const articleComponents: Record<string, Record<string, React.ComponentType>> = {
+// MDX components mapping for all locales (dynamic imports)
+const articleComponents: Record<string, Record<string, () => Promise<{ default: React.ComponentType }>>> = {
   'en': {
-    'getting-started-with-ai-coding': require('@content/articles/en/getting-started-with-ai-coding.mdx').default,
-    'mcp-servers-explained': require('@content/articles/en/mcp-servers-explained.mdx').default,
+    'getting-started-with-ai-coding': () => import('@content/articles/en/getting-started-with-ai-coding.mdx'),
+    'mcp-servers-explained': () => import('@content/articles/en/mcp-servers-explained.mdx'),
   },
   'zh-Hans': {
-    'getting-started-with-ai-coding': require('@content/articles/zh-Hans/getting-started-with-ai-coding.mdx').default,
-    'mcp-servers-explained': require('@content/articles/zh-Hans/mcp-servers-explained.mdx').default,
+    'getting-started-with-ai-coding': () => import('@content/articles/zh-Hans/getting-started-with-ai-coding.mdx'),
+    'mcp-servers-explained': () => import('@content/articles/zh-Hans/mcp-servers-explained.mdx'),
   },
   'de': {
-    'getting-started-with-ai-coding': require('@content/articles/de/getting-started-with-ai-coding.mdx').default,
-    'mcp-servers-explained': require('@content/articles/de/mcp-servers-explained.mdx').default,
+    'getting-started-with-ai-coding': () => import('@content/articles/de/getting-started-with-ai-coding.mdx'),
+    'mcp-servers-explained': () => import('@content/articles/de/mcp-servers-explained.mdx'),
   },
 };
 
-// Get components for a specific locale with fallback to English
-export function getArticleComponents(locale: string = 'en'): Record<string, React.ComponentType> {
-  return articleComponents[locale] || articleComponents['en'] || {};
+// Get a specific article component for a given locale and slug
+export async function getArticleComponent(locale: string = 'en', slug: string): Promise<React.ComponentType | null> {
+  const loaders = articleComponents[locale] || articleComponents['en'];
+  const loader = loaders?.[slug];
+  if (!loader) return null;
+  const mdxModule = await loader();
+  return mdxModule.default;
 }

src/lib/generated/docs.ts

@@ -23,23 +23,27 @@ export function getDocBySlug(slug: string, locale: string = 'en'): DocSection |
   return sections.find((doc) => doc.slug === slug);
 }
 
-// MDX components mapping for all locales (webpack will handle this at build time)
-const docComponents: Record<string, Record<string, React.ComponentType>> = {
+// MDX components mapping for all locales (dynamic imports)
+const docComponents: Record<string, Record<string, () => Promise<{ default: React.ComponentType }>>> = {
   'en': {
-    'getting-started': require('@content/docs/en/getting-started.mdx').default,
-    'welcome': require('@content/docs/en/welcome.mdx').default,
+    'getting-started': () => import('@content/docs/en/getting-started.mdx'),
+    'welcome': () => import('@content/docs/en/welcome.mdx'),
   },
   'zh-Hans': {
-    'getting-started': require('@content/docs/zh-Hans/getting-started.mdx').default,
-    'welcome': require('@content/docs/zh-Hans/welcome.mdx').default,
+    'getting-started': () => import('@content/docs/zh-Hans/getting-started.mdx'),
+    'welcome': () => import('@content/docs/zh-Hans/welcome.mdx'),
   },
   'de': {
-    'getting-started': require('@content/docs/de/getting-started.mdx').default,
-    'welcome': require('@content/docs/de/welcome.mdx').default,
+    'getting-started': () => import('@content/docs/de/getting-started.mdx'),
+    'welcome': () => import('@content/docs/de/welcome.mdx'),
   },
 };
 
-// Get components for a specific locale with fallback to English
-export function getDocComponents(locale: string = 'en'): Record<string, React.ComponentType> {
-  return docComponents[locale] || docComponents['en'] || {};
+// Get a specific doc component for a given locale and slug
+export async function getDocComponent(locale: string = 'en', slug: string): Promise<React.ComponentType | null> {
+  const loaders = docComponents[locale] || docComponents['en'];
+  const loader = loaders?.[slug];
+  if (!loader) return null;
+  const mdxModule = await loader();
+  return mdxModule.default;
 }

src/lib/generated/manifesto.ts

@@ -5,12 +5,14 @@
  * Return the Manifesto MDX React component for a given locale.
  * Falls back to the default locale ('en') when the requested locale is missing.
  */
-export function getManifestoComponent(locale: string = 'en'): React.ComponentType {
-  const components: Record<string, React.ComponentType> = {
-    'en': require('@content/manifesto/en/index.mdx').default,
-    'zh-Hans': require('@content/manifesto/zh-Hans/index.mdx').default,
-    'de': require('@content/manifesto/de/index.mdx').default,
+export async function getManifestoComponent(locale: string = 'en'): Promise<React.ComponentType> {
+  const components: Record<string, () => Promise<{ default: React.ComponentType }>> = {
+    'en': () => import('@content/manifesto/en/index.mdx'),
+    'zh-Hans': () => import('@content/manifesto/zh-Hans/index.mdx'),
+    'de': () => import('@content/manifesto/de/index.mdx'),
   };
 
-  return components[locale] || components['en'];
+  const loader = components[locale] || components['en'];
+  const mdxModule = await loader();
+  return mdxModule.default;
 }