feat: expand /docs with recipes, migration guides, and more FAQ

Co-Authored-By: Glinr <bot@glincker.com>

Author: thegdsks

src/app/docs/page.tsx

@@ -5,17 +5,21 @@ import { getCategoryCounts, getFormattedIconCount } from "@/lib/icons";
 import { SidebarShell } from "@/components/layout/sidebar-shell";
 import { JsonLd } from "@/components/json-ld";
 import { FRAMEWORK_GUIDES, BEST_PRACTICES, TRICKS, FAQ_ITEMS } from "@/lib/docs-content";
+import { RECIPES } from "@/lib/docs-recipes";
+import { MIGRATION_GUIDES } from "@/lib/docs-migration";
 import { FrameworkGuideSection } from "@/components/docs/framework-guide-section";
 import { BestPracticesSection } from "@/components/docs/best-practices-section";
 import { TricksSection } from "@/components/docs/tricks-section";
+import { RecipesSection } from "@/components/docs/recipes-section";
+import { MigrationSection } from "@/components/docs/migration-section";
 import { FaqSection } from "@/components/docs/faq-section";
 import { DocsNav, type DocsNavItem } from "@/components/docs/docs-nav";
 
 const count = getFormattedIconCount();
 
 export const metadata: Metadata = {
-  title: "Docs & Guides - theSVG",
-  description: `How to use ${count}+ brand SVG icons in React, Vue, Svelte, React Native, plain HTML, the CLI, the REST API, and AI assistants via MCP. Best practices, tricks, and FAQ.`,
+  title: "Docs & Guides",
+  description: `How to use ${count}+ brand SVG icons in React, Vue, Svelte, React Native, plain HTML, the CLI, the REST API, and AI assistants via MCP. Recipes, best practices, tricks, migration guides, and FAQ.`,
   keywords: [
     "theSVG docs",
     "SVG icon library usage guide",
@@ -27,10 +31,15 @@ export const metadata: Metadata = {
     "brand icon CLI",
     "MCP server icons",
     "SVG icon FAQ",
+    "tech stack badge icons",
+    "brand icon picker React",
+    "migrate from Simple Icons",
+    "Next.js Image SVG icons",
+    "accessible icon button",
   ],
   openGraph: {
-    title: "Docs & Guides - theSVG",
-    description: `How to use ${count}+ brand SVG icons across every major framework, the CDN, the CLI, the REST API, and AI assistants.`,
+    title: "Docs & Guides",
+    description: `How to use ${count}+ brand SVG icons across every major framework, the CDN, the CLI, the REST API, and AI assistants. Recipes, best practices, and migration guides included.`,
     siteName: "theSVG",
   },
   alternates: {
@@ -41,8 +50,10 @@ export const metadata: Metadata = {
 const NAV_ITEMS: DocsNavItem[] = [
   { id: "getting-started", label: "Getting started" },
   ...FRAMEWORK_GUIDES.map((g) => ({ id: g.id, label: g.label })),
+  { id: "recipes", label: "Recipes" },
   { id: "best-practices", label: "Best practices" },
   { id: "tricks", label: "Tricks" },
+  { id: "migration", label: "Migrating" },
   { id: "faq", label: "FAQ" },
 ];
 
@@ -81,19 +92,21 @@ export default function DocsPage() {
             </div>
             <h1 className="mb-2 text-2xl font-bold sm:text-3xl">Docs &amp; Guides</h1>
             <p className="max-w-3xl text-muted-foreground">
-              Everything for using {count}+ brand icons: framework guides, best practices,
-              tricks, and FAQ, all on one page.
+              Everything for using {count}+ brand icons: framework guides, real-world recipes,
+              best practices, tricks, migration guides, and FAQ, all on one page.
             </p>
           </div>
 
-          {/* Sticky in-page nav */}
-          <div className="sticky top-0 z-10 -mx-4 mb-8 border-b border-border/40 bg-background/90 px-4 py-2 backdrop-blur-sm sm:-mx-6 sm:px-6 dark:border-white/[0.06]">
+          {/* Sticky in-page nav. Offset below the mobile floating top bar
+              and the desktop header (both fixed/sticky with a higher
+              z-index) so it doesn't scroll underneath them. */}
+          <div className="sticky top-16 z-20 -mx-4 mb-8 border-b border-border/40 bg-background/90 px-4 py-2 backdrop-blur-sm sm:-mx-6 sm:px-6 lg:top-[calc(4.25rem+var(--banner-h,0px))] dark:border-white/[0.06]">
             <DocsNav items={NAV_ITEMS} />
           </div>
 
           <div className="space-y-14">
             {/* Getting started */}
-            <section id="getting-started" className="scroll-mt-24">
+            <section id="getting-started" className="scroll-mt-32">
               <h2 className="mb-3 text-lg font-semibold">Getting started</h2>
               <p className="max-w-2xl text-sm text-muted-foreground">
                 Pick the guide that matches how you&apos;re building. A handful of known icons in
@@ -108,8 +121,10 @@ export default function DocsPage() {
               <FrameworkGuideSection key={guide.id} guide={guide} />
             ))}
 
+            <RecipesSection items={RECIPES} />
             <BestPracticesSection items={BEST_PRACTICES} />
             <TricksSection items={TRICKS} />
+            <MigrationSection items={MIGRATION_GUIDES} />
             <FaqSection items={FAQ_ITEMS} />
           </div>
         </div>

src/components/docs/best-practices-section.tsx

@@ -3,7 +3,7 @@ import type { BestPractice } from "@/lib/docs-content";
 
 export function BestPracticesSection({ items }: { items: BestPractice[] }) {
   return (
-    <section id="best-practices" className="scroll-mt-24">
+    <section id="best-practices" className="scroll-mt-32">
       <h2 className="mb-4 flex items-center gap-2 text-lg font-semibold">
         <Lightbulb className="h-4 w-4 text-orange-500" />
         Best practices

src/components/docs/framework-guide-section.tsx

@@ -5,7 +5,7 @@ import { DocsCodeBlock } from "@/components/docs/docs-code-block";
 
 export function FrameworkGuideSection({ guide }: { guide: FrameworkGuide }) {
   return (
-    <section id={guide.id} className="scroll-mt-24">
+    <section id={guide.id} className="scroll-mt-32">
       <div className="mb-3 flex flex-wrap items-center gap-2">
         <h3 className="text-base font-semibold">{guide.label}</h3>
         {guide.packageName && (

src/components/docs/migration-section.tsx

@@ -0,0 +1,38 @@
+import Link from "next/link";
+import { ArrowLeftRight } from "lucide-react";
+import type { MigrationGuide } from "@/lib/docs-migration";
+import { DocsCodeBlock } from "@/components/docs/docs-code-block";
+
+export function MigrationSection({ items }: { items: MigrationGuide[] }) {
+  return (
+    <section id="migration" className="scroll-mt-32">
+      <h2 className="mb-1.5 flex items-center gap-2 text-lg font-semibold">
+        <ArrowLeftRight className="h-4 w-4 text-orange-500" />
+        Migrating from other libraries
+      </h2>
+      <p className="mb-4 max-w-2xl text-sm text-muted-foreground">
+        Full feature-by-feature comparison lives on{" "}
+        <Link href="/compare" className="text-orange-600 underline underline-offset-2 dark:text-orange-400">
+          /compare
+        </Link>
+        . These are the short, practical version.
+      </p>
+      <div className="space-y-8">
+        {items.map((guide) => (
+          <div key={guide.id} id={guide.id} className="scroll-mt-32">
+            <h3 className="mb-1.5 text-sm font-semibold">{guide.title}</h3>
+            <p className="mb-3 max-w-2xl text-xs leading-relaxed text-muted-foreground">
+              {guide.summary}
+            </p>
+            <ul className="mb-3 list-disc space-y-1 pl-4 text-xs leading-relaxed text-muted-foreground">
+              {guide.points.map((point) => (
+                <li key={point}>{point}</li>
+              ))}
+            </ul>
+            {guide.snippet && <DocsCodeBlock snippet={guide.snippet} />}
+          </div>
+        ))}
+      </div>
+    </section>
+  );
+}

src/components/docs/recipes-section.tsx

@@ -0,0 +1,29 @@
+import { Wrench } from "lucide-react";
+import type { Recipe } from "@/lib/docs-recipes";
+import { DocsCodeBlock } from "@/components/docs/docs-code-block";
+
+export function RecipesSection({ items }: { items: Recipe[] }) {
+  return (
+    <section id="recipes" className="scroll-mt-32">
+      <h2 className="mb-4 flex items-center gap-2 text-lg font-semibold">
+        <Wrench className="h-4 w-4 text-orange-500" />
+        Recipes
+      </h2>
+      <div className="space-y-8">
+        {items.map((recipe) => (
+          <div key={recipe.id} id={recipe.id} className="scroll-mt-32">
+            <h3 className="mb-1.5 text-sm font-semibold">{recipe.title}</h3>
+            <p className="mb-3 max-w-2xl text-xs leading-relaxed text-muted-foreground">
+              {recipe.description}
+            </p>
+            <div className="space-y-3">
+              {recipe.snippets.map((snippet) => (
+                <DocsCodeBlock key={snippet.label} snippet={snippet} />
+              ))}
+            </div>
+          </div>
+        ))}
+      </div>
+    </section>
+  );
+}

src/components/docs/tricks-section.tsx

@@ -4,7 +4,7 @@ import { DocsCodeBlock } from "@/components/docs/docs-code-block";
 
 export function TricksSection({ items }: { items: Trick[] }) {
   return (
-    <section id="tricks" className="scroll-mt-24">
+    <section id="tricks" className="scroll-mt-32">
       <h2 className="mb-4 flex items-center gap-2 text-lg font-semibold">
         <Sparkles className="h-4 w-4 text-orange-500" />
         Tricks

src/lib/docs-content.ts

@@ -9,8 +9,22 @@
  * packages/cli) — verify against those before changing an API shape.
  */
 
+import { readFileSync } from "fs";
+import { join } from "path";
 import type { SnippetFormat } from "@/lib/code-snippets";
 
+/**
+ * The release workflow (.github/workflows/release.yml) tags releases as
+ * `thesvg@<version>`, taken from packages/thesvg/package.json's own
+ * version field at publish time. Reading that same field here means the
+ * jsDelivr pin example below tracks whatever was actually last released,
+ * instead of a hardcoded tag that goes stale the next time a version bumps.
+ */
+const THESVG_PKG_VERSION: string = JSON.parse(
+  readFileSync(join(process.cwd(), "packages/thesvg/package.json"), "utf-8"),
+).version;
+const JSDELIVR_PINNED_REF = `thesvg@${THESVG_PKG_VERSION}`;
+
 export interface DocsSnippet {
   label: string;
   code: string;
@@ -42,7 +56,7 @@ export const FRAMEWORK_GUIDES: FrameworkGuide[] = [
       {
         label: "Automatic dark mode (no JS)",
         format: "html",
-        code: `<picture>\n  <source media="(prefers-color-scheme: dark)" srcset="https://thesvg.org/icons/github/light.svg" />\n  <img src="https://thesvg.org/icons/github/dark.svg" width="24" alt="GitHub" />\n</picture>`,
+        code: `<picture>\n  <source media="(prefers-color-scheme: dark)" srcset="https://thesvg.org/icons/github/light.svg" />\n  <img src="https://thesvg.org/icons/github/dark.svg" width="24" height="24" alt="GitHub" />\n</picture>`,
       },
     ],
   },
@@ -85,14 +99,20 @@ export const FRAMEWORK_GUIDES: FrameworkGuide[] = [
         format: "vue",
         code: `<script setup>\nimport { Github, Figma } from "@thesvg/vue";\n</script>\n\n<template>\n  <Github width="24" height="24" />\n  <Figma width="32" height="32" aria-label="Figma" />\n</template>`,
       },
+      {
+        label: "Nuxt 3 (explicit import, no auto-import config needed)",
+        format: "vue",
+        code: `<script setup>\n// @thesvg/vue is a plain npm package, not a Nuxt module -\n// import it like any other component, no nuxt.config changes required.\nimport { Github } from "@thesvg/vue";\n</script>\n\n<template>\n  <Github width="24" height="24" />\n</template>`,
+      },
     ],
   },
   {
     id: "svelte",
     label: "Svelte",
     packageName: "@thesvg/svelte",
     npmUrl: "https://www.npmjs.com/package/@thesvg/svelte",
-    summary: "Typed components for Svelte 4 and 5.",
+    summary:
+      "Typed components for Svelte 4 and 5. Plain markup with no browser-only APIs, so it renders identically during SvelteKit SSR and in the client - no onMount guard or client-only wrapper needed.",
     snippets: [
       { label: "Install", format: "cli", code: `npm install @thesvg/svelte` },
       {
@@ -119,6 +139,11 @@ export const FRAMEWORK_GUIDES: FrameworkGuide[] = [
         format: "react",
         code: `import { Github, Figma } from '@thesvg/react-native';\n\nexport function MyComponent() {\n  return (\n    <>\n      <Github size={24} />\n      <Figma size={32} color="#3b82f6" />\n    </>\n  );\n}`,
       },
+      {
+        label: "Expo Router screen",
+        format: "react",
+        code: `import { View } from 'react-native';\nimport { Github, Figma } from '@thesvg/react-native';\n\nexport default function Screen() {\n  return (\n    <View style={{ flexDirection: 'row', gap: 16 }}>\n      <Github size={28} />\n      <Figma size={28} />\n    </View>\n  );\n}`,
+      },
     ],
   },
   {
@@ -136,6 +161,11 @@ export const FRAMEWORK_GUIDES: FrameworkGuide[] = [
         code: `npx @thesvg/cli add github vercel nextjs --format jsx --dir ./components/icons`,
       },
       { label: "Search the catalog", format: "cli", code: `npx @thesvg/cli search "version control"` },
+      {
+        label: "In a Dockerfile / CI build step",
+        format: "cli",
+        code: `# Vendor icons at image build time instead of fetching them at runtime\nRUN npx --yes @thesvg/cli add github vercel nextjs --dir /app/public/icons`,
+      },
     ],
   },
   {
@@ -150,7 +180,7 @@ export const FRAMEWORK_GUIDES: FrameworkGuide[] = [
       {
         label: "jsDelivr mirror (recommended for high traffic)",
         format: "cli",
-        code: `curl "https://cdn.jsdelivr.net/gh/glincker/thesvg@main/src/data/icons.json"`,
+        code: `curl "https://cdn.jsdelivr.net/gh/glincker/thesvg@${JSDELIVR_PINNED_REF}/src/data/icons.json"`,
       },
     ],
   },
@@ -160,12 +190,12 @@ export const FRAMEWORK_GUIDES: FrameworkGuide[] = [
     packageName: "@thesvg/mcp-server",
     npmUrl: "https://www.npmjs.com/package/@thesvg/mcp-server",
     summary:
-      "A local MCP server (stdio) that gives Claude Desktop, Claude Code, and Cursor tools to search and fetch icons directly.",
+      "A local MCP server (stdio) that gives AI assistants tools to search and fetch icons directly. The same mcpServers JSON block works in any MCP-compatible client's config file (Claude Desktop, Claude Code, Cursor, Windsurf) - check your client's docs for where that config file lives.",
     snippets: [
       {
         label: "MCP config (Claude Desktop, Cursor, etc.)",
         format: "mcp",
-        code: `{\n  "mcpServers": {\n    "thesvg": {\n      "command": "npx",\n      "args": ["@thesvg/mcp-server"]\n    }\n  }\n}`,
+        code: `{\n  "mcpServers": {\n    "thesvg": {\n      "command": "npx",\n      "args": ["-y", "@thesvg/mcp-server"]\n    }\n  }\n}`,
       },
     ],
   },
@@ -191,7 +221,7 @@ export const BEST_PRACTICES: BestPractice[] = [
   },
   {
     title: "Pin the jsDelivr mirror to a release, not @main",
-    body: "cdn.jsdelivr.net/gh/glincker/thesvg@main/... tracks the moving main branch. Pin to a released version (e.g. @3.3.8) in production so an upstream rename or removal can't silently change what your app renders.",
+    body: `cdn.jsdelivr.net/gh/glincker/thesvg@main/... tracks the moving main branch. Pin to a released git tag (e.g. @${JSDELIVR_PINNED_REF}, the current release) in production so an upstream rename or removal can't silently change what your app renders.`,
   },
   {
     title: "Use <picture> for dark mode, not JS",
@@ -225,7 +255,7 @@ export const TRICKS: Trick[] = [
     code: {
       label: "onError fallback",
       format: "react",
-      code: `<img\n  src={\`https://thesvg.org/icons/\${slug}/default.svg\`}\n  onError={(e) => { e.currentTarget.src = "/fallback-icon.svg"; }}\n  alt={slug}\n/>`,
+      code: `// "/fallback-icon.svg" is a placeholder you provide - swap in a real\n// asset from your own public/ folder.\n<img\n  src={\`https://thesvg.org/icons/\${slug}/default.svg\`}\n  onError={(e) => {\n    e.currentTarget.onerror = null; // stop if the fallback itself 404s\n    e.currentTarget.src = "/fallback-icon.svg";\n  }}\n  alt={slug}\n/>`,
     },
   },
   {
@@ -246,6 +276,24 @@ export const TRICKS: Trick[] = [
       code: `npx @thesvg/cli add github vercel nextjs tailwindcss vscode --format jsx --dir ./src/icons`,
     },
   },
+  {
+    title: "Preload a hero logo to avoid a flash",
+    body: "A brand icon that's visible immediately on page load (a hero logo, an above-the-fold integration badge) benefits from a preload hint so the browser fetches it before it's needed, instead of waiting for the <img> tag to be discovered during layout.",
+    code: {
+      label: "Preload hint",
+      format: "html",
+      code: `<link rel="preload" as="image" href="https://thesvg.org/icons/github/default.svg" />`,
+    },
+  },
+  {
+    title: "Search the catalog client-side without a package",
+    body: "Building a custom icon picker? Fetch the manifest once, then filter it in memory - no search package, no per-keystroke network request.",
+    code: {
+      label: "Client-side filter",
+      format: "react",
+      code: `const res = await fetch('https://thesvg.org/api/registry.json');\nconst { icons } = await res.json();\n\nconst matches = icons.filter((icon) =>\n  icon.title.toLowerCase().includes(query.toLowerCase()) ||\n  icon.aliases.some((a) => a.toLowerCase().includes(query.toLowerCase()))\n);`,
+    },
+  },
 ];
 
 export interface FaqItem {
@@ -289,4 +337,39 @@ export const FAQ_ITEMS: FaqItem[] = [
     answer:
       "A handful of known icons in a React, Vue, or Svelte app: use the matching framework package — it's tree-shaken and typed. An open-ended or large set (a picker, a directory): use the CDN <img> pattern instead, no bundle cost regardless of count. Want icons checked into your own repo: use the CLI.",
   },
+  {
+    question: "My icon is showing a broken image / 404. What's wrong?",
+    answer:
+      "Almost always a slug mismatch — the URL path uses the exact slug from /api/registry.json, which isn't always the brand's display name (spaces, dots, and casing are normalized). Search the site or check the registry for the exact slug rather than guessing one from the brand name.",
+  },
+  {
+    question: "Does theSVG work with Next.js's <Image> component?",
+    answer:
+      "Not out of the box. Next's built-in image optimizer doesn't rasterize SVGs by default, so <Image> either needs the unoptimized prop for that image, or dangerouslyAllowSVG set on the domain in next.config. For most icon use cases a plain <img> tag (or a framework package component) is simpler and avoids the optimizer entirely.",
+  },
+  {
+    question: "Is there a TypeScript type listing every icon slug?",
+    answer:
+      "No exported union type of all slugs — each icon is its own named export (Github, Figma, ...), so importing an icon that doesn't exist is a module-not-found error at build time, not a string-literal type error. If you need slugs as data (e.g. from an API response), registry.json's slug field is a plain string.",
+  },
+  {
+    question: "How is theSVG different from Simple Icons, svgl, or Iconify?",
+    answer:
+      "Short version: theSVG has more brand icons with more variants per icon (color, mono, light, dark, wordmark) and a wider toolchain (framework packages, CLI, REST API, MCP server). Simple Icons is mono-only but has years of community trust; svgl is Svelte-focused with no npm package; Iconify aggregates 150+ icon sets but isn't brand-focused. Full side-by-side comparison at /compare.",
+  },
+  {
+    question: "Do the framework packages support server-side rendering (SSR)?",
+    answer:
+      "Yes. Every framework package (@thesvg/react, @thesvg/vue, @thesvg/svelte) renders plain markup with no browser-only APIs, so they're SSR-safe by default - no client-only wrapper or hydration guard needed. @thesvg/react components specifically work as React Server Components with no \"use client\" directive.",
+  },
+  {
+    question: "Can I self-host the icons without crediting theSVG?",
+    answer:
+      "The codebase and tooling are MIT-licensed, so no attribution is legally required to self-host. The brand marks themselves stay the property of their trademark holders regardless of where you host the files — see /legal. A link back is appreciated but not required.",
+  },
+  {
+    question: "Why does the same icon look different in dark mode?",
+    answer:
+      "If you're rendering the default variant everywhere, that's expected - it's a fixed brand color, not theme-aware. For a variant that adapts to the page theme, use light/dark with a <picture> element (see Best practices above), or the mono variant with an inline component so it inherits currentColor.",
+  },
 ];