@farming-labs/docs 0.0.36 → 0.0.38

package/dist/cli/index.mjs

@@ -15,6 +15,7 @@ function detectFramework(cwd) {
 		...pkg.devDependencies
 	};
 	if (allDeps["next"]) return "nextjs";
+	if (allDeps["@tanstack/react-start"]) return "tanstack-start";
 	if (allDeps["@sveltejs/kit"]) return "sveltekit";
 	if (allDeps["astro"]) return "astro";
 	if (allDeps["nuxt"]) return "nuxt";
@@ -65,6 +66,7 @@ const GLOBAL_CSS_CANDIDATES = [
 	"src/app/globals.css",
 	"src/app/global.css",
 	"src/app.css",
+	"src/styles/app.css",
 	"styles/globals.css",
 	"styles/global.css",
 	"src/styles/globals.css",
@@ -226,6 +228,46 @@ const THEME_INFO = {
 function getThemeInfo(theme) {
 	return THEME_INFO[theme] ?? THEME_INFO.fumadocs;
 }
+function toPosixPath(value) {
+	return value.replace(/\\/g, "/");
+}
+function stripScriptExtension(value) {
+	return value.replace(/\.(?:[cm]?[jt]sx?)$/i, "");
+}
+function relativeImport(fromFile, toFile) {
+	const fromPosix = toPosixPath(fromFile);
+	const toPosix = stripScriptExtension(toPosixPath(toFile));
+	const rel = path.posix.relative(path.posix.dirname(fromPosix), toPosix);
+	return rel.startsWith(".") ? rel : `./${rel}`;
+}
+function relativeAssetPath(fromFile, toFile) {
+	const fromPosix = toPosixPath(fromFile);
+	const toPosix = toPosixPath(toFile);
+	const rel = path.posix.relative(path.posix.dirname(fromPosix), toPosix);
+	return rel.startsWith(".") ? rel : `./${rel}`;
+}
+function extractImportSpecifier(importLine) {
+	const fromMatch = importLine.match(/\bfrom\s+["']([^"']+)["']/);
+	if (fromMatch) return fromMatch[1];
+	const bareImportMatch = importLine.match(/^\s*import\s+["']([^"']+)["']/);
+	if (bareImportMatch) return bareImportMatch[1];
+	return null;
+}
+function addImportLine(content, importLine) {
+	if (content.includes(importLine)) return content;
+	const specifier = extractImportSpecifier(importLine);
+	if (specifier) {
+		if (new RegExp(String.raw`\bimport(?:\s+type)?[\s\S]*?\bfrom\s+["']${specifier.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}["']|^\s*import\s+["']${specifier.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}["']`, "m").test(content)) return content;
+	}
+	const lines = content.split("\n");
+	const lastImportIdx = lines.reduce((acc, line, index) => {
+		const trimmed = line.trimStart();
+		return trimmed.startsWith("import ") || trimmed.startsWith("import type ") ? index : acc;
+	}, -1);
+	if (lastImportIdx >= 0) lines.splice(lastImportIdx + 1, 0, importLine);
+	else lines.unshift(importLine, "");
+	return lines.join("\n");
+}
 function renderI18nConfig(cfg, indent = "  ") {
 	const i18n = cfg.i18n;
 	if (!i18n || i18n.locales.length === 0) return "";
@@ -737,6 +779,414 @@ pnpm build
 Deploy to Vercel, Netlify, or any Node.js hosting platform.
 `;
 }
+function tanstackDocsConfigTemplate(cfg) {
+	if (cfg.theme === "custom" && cfg.customThemeName) {
+		const exportName = getThemeExportName(cfg.customThemeName);
+		return `\
+import { defineDocs } from "@farming-labs/docs";
+import { ${exportName} } from "./themes/${cfg.customThemeName.replace(/\.ts$/i, "")}";
+
+export default defineDocs({
+  entry: "${cfg.entry}",
+  contentDir: "${cfg.entry}",
+  theme: ${exportName}({
+    ui: {
+      colors: { primary: "#6366f1" },
+    },
+  }),
+  nav: {
+    title: "${cfg.projectName} Docs",
+    url: "/${cfg.entry}",
+  },
+  themeToggle: {
+    enabled: true,
+    default: "dark",
+  },
+  metadata: {
+    titleTemplate: "%s – ${cfg.projectName}",
+    description: "Documentation for ${cfg.projectName}",
+  },
+});
+`;
+	}
+	const t = getThemeInfo(cfg.theme);
+	return `\
+import { defineDocs } from "@farming-labs/docs";
+import { ${t.factory} } from "${t.nextImport}";
+
+export default defineDocs({
+  entry: "${cfg.entry}",
+  contentDir: "${cfg.entry}",
+  theme: ${t.factory}({
+    ui: {
+      colors: { primary: "#6366f1" },
+    },
+  }),
+  nav: {
+    title: "${cfg.projectName} Docs",
+    url: "/${cfg.entry}",
+  },
+  themeToggle: {
+    enabled: true,
+    default: "dark",
+  },
+  metadata: {
+    titleTemplate: "%s – ${cfg.projectName}",
+    description: "Documentation for ${cfg.projectName}",
+  },
+});
+`;
+}
+function tanstackDocsServerTemplate() {
+	return `\
+import { createDocsServer } from "@farming-labs/tanstack-start/server";
+import docsConfig from "../../docs.config";
+
+export const docsServer = createDocsServer({
+  ...docsConfig,
+  rootDir: process.cwd(),
+});
+`;
+}
+function tanstackDocsFunctionsTemplate() {
+	return `\
+import { createServerFn } from "@tanstack/react-start";
+import { docsServer } from "./docs.server";
+
+export const loadDocPage = createServerFn({ method: "GET" })
+  .inputValidator((data: { pathname: string; locale?: string }) => data)
+  .handler(async ({ data }) => docsServer.load(data));
+`;
+}
+function tanstackDocsFunctionsImport(opts) {
+	if (opts.useAlias) return "@/lib/docs.functions";
+	return relativeImport(opts.filePath, "src/lib/docs.functions.ts");
+}
+function tanstackDocsConfigImport(filePath) {
+	return relativeImport(filePath, "docs.config.ts");
+}
+function tanstackDocsIndexRouteTemplate(opts) {
+	const entryUrl = `/${opts.entry.replace(/^\/+|\/+$/g, "")}`;
+	return `\
+import { createFileRoute } from "@tanstack/react-router";
+import { TanstackDocsPage } from "@farming-labs/tanstack-start/react";
+import { loadDocPage } from "${tanstackDocsFunctionsImport(opts)}";
+import docsConfig from "${tanstackDocsConfigImport(opts.filePath)}";
+
+export const Route = createFileRoute("${entryUrl}/")({
+  loader: () => loadDocPage({ data: { pathname: "${entryUrl}" } }),
+  head: ({ loaderData }) => ({
+    meta: [
+      { title: loaderData ? \`\${loaderData.title} – ${opts.projectName}\` : "${opts.projectName}" },
+      ...(loaderData?.description
+        ? [{ name: "description", content: loaderData.description }]
+        : []),
+    ],
+  }),
+  component: DocsIndexPage,
+});
+
+function DocsIndexPage() {
+  const data = Route.useLoaderData();
+  return <TanstackDocsPage config={docsConfig} data={data} />;
+}
+`;
+}
+function tanstackDocsCatchAllRouteTemplate(opts) {
+	const entryUrl = `/${opts.entry.replace(/^\/+|\/+$/g, "")}`;
+	return `\
+import { createFileRoute, notFound } from "@tanstack/react-router";
+import { TanstackDocsPage } from "@farming-labs/tanstack-start/react";
+import { loadDocPage } from "${tanstackDocsFunctionsImport(opts)}";
+import docsConfig from "${tanstackDocsConfigImport(opts.filePath)}";
+
+export const Route = createFileRoute("${entryUrl}/$")({
+  loader: async ({ location }) => {
+    try {
+      return await loadDocPage({ data: { pathname: location.pathname } });
+    } catch (error) {
+      if (
+        error &&
+        typeof error === "object" &&
+        "status" in error &&
+        (error as { status?: unknown }).status === 404
+      ) {
+        throw notFound();
+      }
+      throw error;
+    }
+  },
+  head: ({ loaderData }) => ({
+    meta: [
+      { title: loaderData ? \`\${loaderData.title} – ${opts.projectName}\` : "${opts.projectName}" },
+      ...(loaderData?.description
+        ? [{ name: "description", content: loaderData.description }]
+        : []),
+    ],
+  }),
+  component: DocsCatchAllPage,
+});
+
+function DocsCatchAllPage() {
+  const data = Route.useLoaderData();
+  return <TanstackDocsPage config={docsConfig} data={data} />;
+}
+`;
+}
+function tanstackApiDocsRouteTemplate(useAlias, filePath) {
+	return `\
+import { createFileRoute } from "@tanstack/react-router";
+import { docsServer } from "${useAlias ? "@/lib/docs.server" : relativeImport(filePath, "src/lib/docs.server.ts")}";
+
+export const Route = createFileRoute("/api/docs")({
+  server: {
+    handlers: {
+      GET: async ({ request }) => docsServer.GET({ request }),
+      POST: async ({ request }) => docsServer.POST({ request }),
+    },
+  },
+});
+`;
+}
+function tanstackRootRouteTemplate(globalCssRelPath) {
+	return `\
+import appCss from "${relativeAssetPath("src/routes/__root.tsx", globalCssRelPath)}?url";
+import { createRootRoute, HeadContent, Outlet, Scripts } from "@tanstack/react-router";
+import { RootProvider } from "@farming-labs/theme/tanstack";
+
+export const Route = createRootRoute({
+  head: () => ({
+    links: [{ rel: "stylesheet", href: appCss }],
+    meta: [
+      { charSet: "utf-8" },
+      { name: "viewport", content: "width=device-width, initial-scale=1" },
+      { title: "Docs" },
+    ],
+  }),
+  component: RootComponent,
+});
+
+function RootComponent() {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <head>
+        <HeadContent />
+      </head>
+      <body>
+        <RootProvider>
+          <Outlet />
+        </RootProvider>
+        <Scripts />
+      </body>
+    </html>
+  );
+}
+`;
+}
+function injectTanstackRootProviderIntoRoute(content) {
+	if (!content || content.includes("RootProvider")) return null;
+	let out = addImportLine(content, "import { RootProvider } from \"@farming-labs/theme/tanstack\";");
+	if (out.includes("<Outlet />")) out = out.replace("<Outlet />", "<RootProvider><Outlet /></RootProvider>");
+	else if (out.includes("<Outlet></Outlet>")) out = out.replace("<Outlet></Outlet>", "<RootProvider><Outlet /></RootProvider>");
+	else return null;
+	return out === content ? null : out;
+}
+function tanstackViteConfigTemplate(useAlias) {
+	return `\
+import { defineConfig } from "vite";
+import tailwindcss from "@tailwindcss/vite";
+${useAlias ? "import tsconfigPaths from \"vite-tsconfig-paths\";\n" : ""}import { tanstackStart } from "@tanstack/react-start/plugin/vite";
+import { docsMdx } from "@farming-labs/tanstack-start/vite";
+
+export default defineConfig({
+  plugins: [tailwindcss(), docsMdx(), ${useAlias ? "tsconfigPaths({ ignoreConfigErrors: true }), " : ""}tanstackStart()],
+});
+`;
+}
+function injectTanstackVitePlugins(content, useAlias) {
+	if (!content) return null;
+	let out = content;
+	out = addImportLine(out, "import tailwindcss from \"@tailwindcss/vite\";");
+	if (useAlias) out = addImportLine(out, "import tsconfigPaths from \"vite-tsconfig-paths\";");
+	out = addImportLine(out, "import { docsMdx } from \"@farming-labs/tanstack-start/vite\";");
+	const additions = [];
+	if (!out.includes("tailwindcss()")) additions.push("tailwindcss()");
+	if (!out.includes("docsMdx()")) additions.push("docsMdx()");
+	if (useAlias && !out.includes("tsconfigPaths(")) additions.push("tsconfigPaths({ ignoreConfigErrors: true })");
+	if (additions.length === 0) return out === content ? null : out;
+	const pluginsMatch = out.match(/plugins\s*:\s*\[([\s\S]*?)\]/m);
+	if (pluginsMatch) {
+		const current = pluginsMatch[1].trim();
+		const existing = current ? `${current}${current.endsWith(",") ? "" : ","}` : "";
+		const replacement = `plugins: [\n    ${existing}${existing ? "\n    " : ""}${additions.join(",\n    ")}\n  ]`;
+		return out.replace(pluginsMatch[0], replacement);
+	}
+	const configMatch = out.match(/defineConfig\(\s*\{/);
+	if (configMatch) {
+		const insertion = `defineConfig({\n  plugins: [${additions.join(", ")}],`;
+		return out.replace(configMatch[0], insertion);
+	}
+	return out === content ? null : out;
+}
+function tanstackWelcomePageTemplate(cfg) {
+	return `\
+---
+title: "Documentation"
+description: "Welcome to ${cfg.projectName} documentation"
+---
+
+# Welcome to ${cfg.projectName}
+
+This docs site is powered by \`@farming-labs/docs\` and TanStack Start.
+
+## Overview
+
+- Content lives in \`${cfg.entry}/\`
+- Routes live in \`src/routes/${cfg.entry}/\`
+- Search is served from \`/api/docs\`
+
+## Next Steps
+
+Read the [Installation](/${cfg.entry}/installation) guide, then continue to [Quickstart](/${cfg.entry}/quickstart).
+`;
+}
+function tanstackInstallationPageTemplate(cfg) {
+	if (cfg.theme === "custom" && cfg.customThemeName) {
+		const baseName = cfg.customThemeName.replace(/\.(ts|css)$/i, "");
+		const exportName = getThemeExportName(baseName);
+		const cssImportPath = getCustomThemeCssImportPath("src/styles/app.css", baseName);
+		return `\
+---
+title: "Installation"
+description: "How to install and set up ${cfg.projectName}"
+---
+
+# Installation
+
+Add the docs packages to your TanStack Start app:
+
+\`\`\`bash
+pnpm add @farming-labs/docs @farming-labs/theme @farming-labs/tanstack-start
+\`\`\`
+
+The scaffold also configures MDX through \`docsMdx()\` in \`vite.config.ts\`.
+
+## Theme CSS
+
+Keep your config theme and global CSS import aligned:
+
+\`\`\`ts title="docs.config.ts"
+import { defineDocs } from "@farming-labs/docs";
+import { ${exportName} } from "./themes/${baseName}";
+
+export default defineDocs({
+  entry: "${cfg.entry}",
+  contentDir: "${cfg.entry}",
+  theme: ${exportName}(),
+});
+\`\`\`
+
+\`\`\`css title="src/styles/app.css"
+@import "tailwindcss";
+@import "${cssImportPath}";
+\`\`\`
+
+## Generated Files
+
+\`\`\`
+docs.config.ts
+themes/${baseName}.ts
+themes/${baseName}.css
+${cfg.entry}/
+src/lib/docs.server.ts
+src/lib/docs.functions.ts
+src/routes/${cfg.entry}/index.tsx
+src/routes/${cfg.entry}/$.tsx
+src/routes/api/docs.ts
+\`\`\`
+`;
+	}
+	const t = getThemeInfo(cfg.theme);
+	return `\
+---
+title: "Installation"
+description: "How to install and set up ${cfg.projectName}"
+---
+
+# Installation
+
+Add the docs packages to your TanStack Start app:
+
+\`\`\`bash
+pnpm add @farming-labs/docs @farming-labs/theme @farming-labs/tanstack-start
+\`\`\`
+
+The scaffold also configures MDX through \`docsMdx()\` in \`vite.config.ts\`.
+
+## Theme CSS
+
+Keep your config theme and global CSS import aligned:
+
+\`\`\`ts title="docs.config.ts"
+import { defineDocs } from "@farming-labs/docs";
+import { ${t.factory} } from "${t.nextImport}";
+
+export default defineDocs({
+  entry: "${cfg.entry}",
+  contentDir: "${cfg.entry}",
+  theme: ${t.factory}(),
+});
+\`\`\`
+
+\`\`\`css title="src/styles/app.css"
+@import "tailwindcss";
+@import "@farming-labs/theme/${t.nextCssImport}/css";
+\`\`\`
+
+## Generated Files
+
+\`\`\`
+docs.config.ts
+${cfg.entry}/
+src/lib/docs.server.ts
+src/lib/docs.functions.ts
+src/routes/${cfg.entry}/index.tsx
+src/routes/${cfg.entry}/$.tsx
+src/routes/api/docs.ts
+\`\`\`
+`;
+}
+function tanstackQuickstartPageTemplate(cfg) {
+	return `\
+---
+title: "Quickstart"
+description: "Get up and running in minutes"
+---
+
+# Quickstart
+
+Create a new page under \`${cfg.entry}/\`:
+
+\`\`\`bash
+mkdir -p ${cfg.entry}/my-page
+\`\`\`
+
+Then add \`${cfg.entry}/my-page/page.mdx\`:
+
+\`\`\`mdx
+---
+title: "My Page"
+description: "A custom documentation page"
+---
+
+# My Page
+
+Write your content here using **MDX**.
+\`\`\`
+
+Visit [/${cfg.entry}/my-page](/${cfg.entry}/my-page) after starting the dev server.
+`;
+}
 function svelteDocsConfigTemplate(cfg) {
 	if (cfg.theme === "custom" && cfg.customThemeName) {
 		const exportName = getThemeExportName(cfg.customThemeName);
@@ -1763,7 +2213,8 @@ const VALID_TEMPLATES = [
 	"next",
 	"nuxt",
 	"sveltekit",
-	"astro"
+	"astro",
+	"tanstack-start"
 ];
 const COMMON_LOCALE_OPTIONS = [
 	{
@@ -1838,6 +2289,12 @@ function normalizeLocaleCode(value) {
 function parseLocaleInput(input) {
 	return Array.from(new Set(input.split(",").map((value) => normalizeLocaleCode(value)).filter(Boolean)));
 }
+function normalizeEntryPath(entry) {
+	return entry.replace(/^\/+|\/+$/g, "");
+}
+function getTanstackDocsRouteDir(entry) {
+	return path.posix.join("src/routes", normalizeEntryPath(entry));
+}
 async function init(options = {}) {
 	const cwd = process.cwd();
 	p.intro(pc.bgCyan(pc.black(" @farming-labs/docs ")));
@@ -1852,7 +2309,7 @@ async function init(options = {}) {
 			}, {
 				value: "fresh",
 				label: "Fresh project",
-				hint: "Bootstrap a new app from a template (Next, Nuxt, SvelteKit, Astro)"
+				hint: "Bootstrap a new app from a template (Next, Nuxt, SvelteKit, Astro, TanStack Start)"
 			}]
 		});
 		if (p.isCancel(projectTypeAnswer)) {
@@ -1892,6 +2349,11 @@ async function init(options = {}) {
 						value: "astro",
 						label: "Astro",
 						hint: "Content-focused with islands"
+					},
+					{
+						value: "tanstack-start",
+						label: "TanStack Start",
+						hint: "React with TanStack Router and server functions"
 					}
 				]
 			});
@@ -1920,7 +2382,7 @@ async function init(options = {}) {
 			}
 			projectName = nameAnswer.trim() || defaultProjectName;
 		}
-		const templateLabel = template === "next" ? "Next.js" : template === "nuxt" ? "Nuxt" : template === "sveltekit" ? "SvelteKit" : "Astro";
+		const templateLabel = template === "next" ? "Next.js" : template === "nuxt" ? "Nuxt" : template === "sveltekit" ? "SvelteKit" : template === "astro" ? "Astro" : "TanStack Start";
 		const targetDir = path.join(cwd, projectName);
 		const fs = await import("node:fs");
 		if (fs.existsSync(targetDir)) {
@@ -1979,7 +2441,7 @@ async function init(options = {}) {
 	}
 	let framework = detectFramework(cwd);
 	if (framework) {
-		const frameworkName = framework === "nextjs" ? "Next.js" : framework === "sveltekit" ? "SvelteKit" : framework === "astro" ? "Astro" : "Nuxt";
+		const frameworkName = framework === "nextjs" ? "Next.js" : framework === "tanstack-start" ? "TanStack Start" : framework === "sveltekit" ? "SvelteKit" : framework === "astro" ? "Astro" : "Nuxt";
 		p.log.success(`Detected framework: ${pc.cyan(frameworkName)}`);
 	} else {
 		p.log.warn("Could not auto-detect a framework from " + pc.cyan("package.json") + ".");
@@ -1991,6 +2453,11 @@ async function init(options = {}) {
 					label: "Next.js",
 					hint: "React framework with App Router"
 				},
+				{
+					value: "tanstack-start",
+					label: "TanStack Start",
+					hint: "React with TanStack Router and server functions"
+				},
 				{
 					value: "sveltekit",
 					label: "SvelteKit",
@@ -2101,7 +2568,7 @@ async function init(options = {}) {
 		}
 		customThemeName = nameAnswer.trim().replace(/\.(ts|css)$/i, "") || defaultThemeName;
 	}
-	const aliasHint = framework === "nextjs" ? `Uses ${pc.cyan("@/")} prefix (requires tsconfig paths)` : framework === "sveltekit" ? `Uses ${pc.cyan("$lib/")} prefix (SvelteKit built-in)` : framework === "nuxt" ? `Uses ${pc.cyan("~/")} prefix (Nuxt built-in)` : `Uses ${pc.cyan("@/")} prefix (requires tsconfig paths)`;
+	const aliasHint = framework === "nextjs" ? `Uses ${pc.cyan("@/")} prefix (requires tsconfig paths)` : framework === "tanstack-start" ? `Uses ${pc.cyan("@/")} prefix (requires tsconfig paths)` : framework === "sveltekit" ? `Uses ${pc.cyan("$lib/")} prefix (SvelteKit built-in)` : framework === "nuxt" ? `Uses ${pc.cyan("~/")} prefix (Nuxt built-in)` : `Uses ${pc.cyan("@/")} prefix (requires tsconfig paths)`;
 	const useAlias = await p.confirm({
 		message: `Use path aliases for imports? ${pc.dim(aliasHint)}`,
 		initialValue: false
@@ -2157,67 +2624,71 @@ async function init(options = {}) {
 		process.exit(0);
 	}
 	const entryPath = entry.trim() || defaultEntry;
-	const enableI18n = await p.confirm({
-		message: "Do you want to scaffold internationalized docs ?",
-		initialValue: false
-	});
-	if (p.isCancel(enableI18n)) {
-		p.outro(pc.red("Init cancelled."));
-		process.exit(0);
-	}
 	let docsI18n;
-	if (enableI18n) {
-		const selectedLocales = await p.multiselect({
-			message: "Which languages should we scaffold?",
-			options: COMMON_LOCALE_OPTIONS.map((option) => ({
-				value: option.value,
-				label: option.label,
-				hint: option.hint
-			}))
+	if (framework === "tanstack-start") p.log.info("Skipping i18n scaffold for TanStack Start. Configure localized routes manually if needed.");
+	else {
+		const enableI18n = await p.confirm({
+			message: "Do you want to scaffold internationalized docs ?",
+			initialValue: false
 		});
-		if (p.isCancel(selectedLocales)) {
+		if (p.isCancel(enableI18n)) {
 			p.outro(pc.red("Init cancelled."));
 			process.exit(0);
 		}
-		const extraLocalesAnswer = await p.text({
-			message: "Any additional locale codes? (comma-separated, optional)",
-			placeholder: "nl, sv, pt-BR",
-			defaultValue: "",
-			validate: (value) => {
-				return parseLocaleInput(value ?? "").every((locale) => /^[a-z]{2,3}(?:-[A-Z]{2})?$/.test(locale)) ? void 0 : "Use locale codes like en, fr, zh, or pt-BR";
+		if (!enableI18n) docsI18n = void 0;
+		else {
+			const selectedLocales = await p.multiselect({
+				message: "Which languages should we scaffold?",
+				options: COMMON_LOCALE_OPTIONS.map((option) => ({
+					value: option.value,
+					label: option.label,
+					hint: option.hint
+				}))
+			});
+			if (p.isCancel(selectedLocales)) {
+				p.outro(pc.red("Init cancelled."));
+				process.exit(0);
 			}
-		});
-		if (p.isCancel(extraLocalesAnswer)) {
-			p.outro(pc.red("Init cancelled."));
-			process.exit(0);
-		}
-		const locales = Array.from(new Set([...(selectedLocales ?? []).map((locale) => normalizeLocaleCode(locale)), ...parseLocaleInput(extraLocalesAnswer ?? "")])).filter(Boolean);
-		if (locales.length === 0) {
-			p.log.error("Pick at least one locale to scaffold i18n support.");
-			p.outro(pc.red("Init cancelled."));
-			process.exit(1);
-		}
-		const defaultLocaleAnswer = await p.select({
-			message: "Which locale should be the default?",
-			options: locales.map((locale) => ({
-				value: locale,
-				label: locale,
-				hint: locale === "en" ? "Recommended default" : void 0
-			})),
-			initialValue: locales[0]
-		});
-		if (p.isCancel(defaultLocaleAnswer)) {
-			p.outro(pc.red("Init cancelled."));
-			process.exit(0);
+			const extraLocalesAnswer = await p.text({
+				message: "Any additional locale codes? (comma-separated, optional)",
+				placeholder: "nl, sv, pt-BR",
+				defaultValue: "",
+				validate: (value) => {
+					return parseLocaleInput(value ?? "").every((locale) => /^[a-z]{2,3}(?:-[A-Z]{2})?$/.test(locale)) ? void 0 : "Use locale codes like en, fr, zh, or pt-BR";
+				}
+			});
+			if (p.isCancel(extraLocalesAnswer)) {
+				p.outro(pc.red("Init cancelled."));
+				process.exit(0);
+			}
+			const locales = Array.from(new Set([...(selectedLocales ?? []).map((locale) => normalizeLocaleCode(locale)), ...parseLocaleInput(extraLocalesAnswer ?? "")])).filter(Boolean);
+			if (locales.length === 0) {
+				p.log.error("Pick at least one locale to scaffold i18n support.");
+				p.outro(pc.red("Init cancelled."));
+				process.exit(1);
+			}
+			const defaultLocaleAnswer = await p.select({
+				message: "Which locale should be the default?",
+				options: locales.map((locale) => ({
+					value: locale,
+					label: locale,
+					hint: locale === "en" ? "Recommended default" : void 0
+				})),
+				initialValue: locales[0]
+			});
+			if (p.isCancel(defaultLocaleAnswer)) {
+				p.outro(pc.red("Init cancelled."));
+				process.exit(0);
+			}
+			docsI18n = {
+				locales,
+				defaultLocale: defaultLocaleAnswer
+			};
 		}
-		docsI18n = {
-			locales,
-			defaultLocale: defaultLocaleAnswer
-		};
 	}
 	const detectedCssFiles = detectGlobalCssFiles(cwd);
 	let globalCssRelPath;
-	const defaultCssPath = framework === "sveltekit" ? "src/app.css" : framework === "astro" ? "src/styles/global.css" : framework === "nuxt" ? "assets/css/main.css" : framework === "nextjs" ? `${nextAppDir}/globals.css` : "app/globals.css";
+	const defaultCssPath = framework === "tanstack-start" ? "src/styles/app.css" : framework === "sveltekit" ? "src/app.css" : framework === "astro" ? "src/styles/global.css" : framework === "nuxt" ? "assets/css/main.css" : framework === "nextjs" ? `${nextAppDir}/globals.css` : "app/globals.css";
 	if (detectedCssFiles.length === 1) {
 		globalCssRelPath = detectedCssFiles[0];
 		p.log.info(`Found global CSS at ${pc.cyan(globalCssRelPath)}`);
@@ -2272,7 +2743,8 @@ async function init(options = {}) {
 		if (writeFileSafe(path.join(cwd, rel), content, overwrite)) written.push(rel);
 		else skipped.push(rel);
 	}
-	if (framework === "sveltekit") scaffoldSvelteKit(cwd, cfg, globalCssRelPath, write, skipped, written);
+	if (framework === "tanstack-start") scaffoldTanstackStart(cwd, cfg, globalCssRelPath, write, skipped, written);
+	else if (framework === "sveltekit") scaffoldSvelteKit(cwd, cfg, globalCssRelPath, write, skipped, written);
 	else if (framework === "astro") scaffoldAstro(cwd, cfg, globalCssRelPath, write, skipped, written);
 	else if (framework === "nuxt") scaffoldNuxt(cwd, cfg, globalCssRelPath, write, skipped, written);
 	else scaffoldNextJs(cwd, cfg, globalCssRelPath, write, skipped, written);
@@ -2316,7 +2788,17 @@ async function init(options = {}) {
 	const s2 = p.spinner();
 	s2.start("Installing dependencies");
 	try {
-		if (framework === "sveltekit") exec(`${installCommand(pm)} @farming-labs/docs @farming-labs/svelte @farming-labs/svelte-theme`, cwd);
+		if (framework === "tanstack-start") {
+			exec(`${installCommand(pm)} @farming-labs/docs @farming-labs/theme @farming-labs/tanstack-start`, cwd);
+			const devDeps = ["@tailwindcss/vite", "tailwindcss"];
+			if (useAlias) devDeps.push("vite-tsconfig-paths");
+			const allDeps = {
+				...pkgJson.dependencies,
+				...pkgJson.devDependencies
+			};
+			const missingDevDeps = devDeps.filter((d) => !allDeps[d]);
+			if (missingDevDeps.length > 0) exec(`${devInstallCommand(pm)} ${missingDevDeps.join(" ")}`, cwd);
+		} else if (framework === "sveltekit") exec(`${installCommand(pm)} @farming-labs/docs @farming-labs/svelte @farming-labs/svelte-theme`, cwd);
 		else if (framework === "astro") {
 			const adapterPkg = getAstroAdapterPkg(cfg.astroAdapter ?? "vercel");
 			exec(`${installCommand(pm)} @farming-labs/docs @farming-labs/astro @farming-labs/astro-theme ${adapterPkg}`, cwd);
@@ -2356,7 +2838,11 @@ async function init(options = {}) {
 		process.exit(0);
 	}
 	p.log.step("Starting dev server...");
-	const devCommand = framework === "sveltekit" ? {
+	const devCommand = framework === "tanstack-start" ? {
+		cmd: "npx",
+		args: ["vite", "dev"],
+		waitFor: "ready"
+	} : framework === "sveltekit" ? {
 		cmd: "npx",
 		args: ["vite", "dev"],
 		waitFor: "ready"
@@ -2377,7 +2863,7 @@ async function init(options = {}) {
 		],
 		waitFor: "Ready"
 	};
-	const defaultPort = framework === "sveltekit" ? "5173" : framework === "astro" ? "4321" : framework === "nuxt" ? "3000" : "3000";
+	const defaultPort = framework === "tanstack-start" ? "5173" : framework === "sveltekit" ? "5173" : framework === "astro" ? "4321" : framework === "nuxt" ? "3000" : "3000";
 	try {
 		const child = await spawnAndWaitFor(devCommand.cmd, devCommand.args, cwd, devCommand.waitFor, 6e4);
 		const url = `http://localhost:${defaultPort}/${entryPath}`;
@@ -2396,7 +2882,7 @@ async function init(options = {}) {
 			});
 		});
 	} catch (err) {
-		const manualCmd = framework === "sveltekit" ? "npx vite dev" : framework === "astro" ? "npx astro dev" : framework === "nuxt" ? "npx nuxt dev" : "pnpm dev";
+		const manualCmd = framework === "tanstack-start" ? "npx vite dev" : framework === "sveltekit" ? "npx vite dev" : framework === "astro" ? "npx astro dev" : framework === "nuxt" ? "npx nuxt dev" : "pnpm dev";
 		p.log.error(`Could not start dev server. Try running manually:
   ${pc.cyan(manualCmd)}`);
 		p.outro(pc.yellow("Setup complete. Start the server manually."));
@@ -2489,6 +2975,68 @@ function scaffoldNextJs(cwd, cfg, globalCssRelPath, write, skipped, written) {
 	write(`${appDir}/${cfg.entry}/installation/page.mdx`, installationPageTemplate(cfg));
 	write(`${appDir}/${cfg.entry}/quickstart/page.mdx`, quickstartPageTemplate(cfg));
 }
+function scaffoldTanstackStart(cwd, cfg, globalCssRelPath, write, skipped, written) {
+	if (cfg.theme === "custom" && cfg.customThemeName) {
+		const baseName = cfg.customThemeName.replace(/\.(ts|css)$/i, "");
+		write(`themes/${baseName}.ts`, customThemeTsTemplate(baseName));
+		write(`themes/${baseName}.css`, customThemeCssTemplate(baseName));
+	}
+	write("docs.config.ts", tanstackDocsConfigTemplate(cfg));
+	write("src/lib/docs.server.ts", tanstackDocsServerTemplate());
+	write("src/lib/docs.functions.ts", tanstackDocsFunctionsTemplate());
+	const routeDir = getTanstackDocsRouteDir(cfg.entry);
+	const docsIndexRoute = `${routeDir}/index.tsx`;
+	const docsCatchAllRoute = `${routeDir}/$.tsx`;
+	const apiRoute = "src/routes/api/docs.ts";
+	write(docsIndexRoute, tanstackDocsIndexRouteTemplate({
+		entry: cfg.entry,
+		filePath: docsIndexRoute,
+		useAlias: cfg.useAlias,
+		projectName: cfg.projectName
+	}));
+	write(docsCatchAllRoute, tanstackDocsCatchAllRouteTemplate({
+		entry: cfg.entry,
+		filePath: docsCatchAllRoute,
+		useAlias: cfg.useAlias,
+		projectName: cfg.projectName
+	}));
+	write(apiRoute, tanstackApiDocsRouteTemplate(cfg.useAlias, apiRoute));
+	const rootRoutePath = path.join(cwd, "src/routes/__root.tsx");
+	const existingRootRoute = readFileSafe(rootRoutePath);
+	if (!existingRootRoute) write("src/routes/__root.tsx", tanstackRootRouteTemplate(globalCssRelPath), true);
+	else if (!existingRootRoute.includes("RootProvider")) {
+		const injected = injectTanstackRootProviderIntoRoute(existingRootRoute);
+		if (injected) {
+			writeFileSafe(rootRoutePath, injected, true);
+			written.push("src/routes/__root.tsx (injected RootProvider)");
+		} else skipped.push("src/routes/__root.tsx (could not inject RootProvider)");
+	} else skipped.push("src/routes/__root.tsx (already has RootProvider)");
+	const viteConfigRel = fileExists(path.join(cwd, "vite.config.ts")) ? "vite.config.ts" : fileExists(path.join(cwd, "vite.config.mts")) ? "vite.config.mts" : fileExists(path.join(cwd, "vite.config.js")) ? "vite.config.js" : "vite.config.ts";
+	const viteConfigPath = path.join(cwd, viteConfigRel);
+	const existingViteConfig = readFileSafe(viteConfigPath);
+	if (!existingViteConfig) write(viteConfigRel, tanstackViteConfigTemplate(cfg.useAlias), true);
+	else {
+		const injected = injectTanstackVitePlugins(existingViteConfig, cfg.useAlias);
+		if (injected) {
+			writeFileSafe(viteConfigPath, injected, true);
+			written.push(`${viteConfigRel} (updated)`);
+		} else skipped.push(`${viteConfigRel} (already configured)`);
+	}
+	const globalCssAbsPath = path.join(cwd, globalCssRelPath);
+	const existingGlobalCss = readFileSafe(globalCssAbsPath);
+	if (existingGlobalCss) {
+		const injected = injectCssImport(existingGlobalCss, cfg.theme, cfg.customThemeName, globalCssRelPath);
+		if (injected) {
+			writeFileSafe(globalCssAbsPath, injected, true);
+			written.push(globalCssRelPath + " (updated)");
+		} else skipped.push(globalCssRelPath + " (already configured)");
+	} else write(globalCssRelPath, globalCssTemplate(cfg.theme, cfg.customThemeName, globalCssRelPath));
+	for (const base of getScaffoldContentRoots(cfg)) {
+		write(`${base}/page.mdx`, tanstackWelcomePageTemplate(cfg));
+		write(`${base}/installation/page.mdx`, tanstackInstallationPageTemplate(cfg));
+		write(`${base}/quickstart/page.mdx`, tanstackQuickstartPageTemplate(cfg));
+	}
+}
 function scaffoldSvelteKit(cwd, cfg, globalCssRelPath, write, skipped, written) {
 	if (cfg.theme === "custom" && cfg.customThemeName) {
 		const baseName = cfg.customThemeName.replace(/\.(ts|css)$/i, "");
@@ -2673,11 +3221,16 @@ async function upgrade(options = {}) {
 		preset = normalized;
 		framework = frameworkFromPreset(preset);
 	} else {
-		framework = detectFramework(cwd);
-		if (!framework) {
+		const detected = detectFramework(cwd);
+		if (!detected) {
 			p.log.error("Could not detect a supported framework (Next.js, Nuxt, SvelteKit, Astro). Use " + pc.cyan("--framework <next|nuxt|sveltekit|astro>") + " to specify.");
 			process.exit(1);
 		}
+		if (detected === "tanstack-start") {
+			p.log.error("TanStack Start is supported by " + pc.cyan("init") + " but not by " + pc.cyan("upgrade") + " yet. Upgrade the docs packages manually for now.");
+			process.exit(1);
+		}
+		framework = detected;
 		preset = presetFromFramework(framework);
 	}
 	let pm = detectPackageManagerFromLockfile(cwd);
@@ -2785,7 +3338,7 @@ ${pc.dim("Supported frameworks:")}
   Next.js, SvelteKit, Astro, Nuxt
 
 ${pc.dim("Options for init:")}
-  ${pc.cyan("--template <name>")}  Bootstrap a project (${pc.dim("next")}, ${pc.dim("nuxt")}, ${pc.dim("sveltekit")}, ${pc.dim("astro")}); use with ${pc.cyan("--name")}
+  ${pc.cyan("--template <name>")}  Bootstrap a project (${pc.dim("next")}, ${pc.dim("nuxt")}, ${pc.dim("sveltekit")}, ${pc.dim("astro")}, ${pc.dim("tanstack-start")}); use with ${pc.cyan("--name")}
   ${pc.cyan("--name <project>")}  Project folder name when using ${pc.cyan("--template")}; prompt if omitted (e.g. ${pc.dim("my-docs")})
   ${pc.cyan("--theme <name>")}     Skip theme prompt (e.g. ${pc.dim("darksharp")}, ${pc.dim("greentree")})
   ${pc.cyan("--entry <path>")}     Skip entry path prompt (e.g. ${pc.dim("docs")})

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farming-labs/docs",
-  "version": "0.0.36",
+  "version": "0.0.38",
   "description": "Modern, flexible MDX-based docs framework — core types, config, and CLI",
   "keywords": [
     "docs",