feat(web): improve docs and refactor cli (#476)

Author: AmanVarshney01

README.md

@@ -25,33 +25,36 @@ pnpm create better-t-stack@latest
 
 ## Features
 
-- **Zero-config setup** with interactive CLI wizard
-- **End-to-end type safety** from database to frontend via tRPC
-- **Modern stack** with React, Hono/Elysia, and TanStack libraries
-- **Multi-platform** supporting web, mobile (Expo), and desktop applications
-- **Database flexibility** with SQLite (Turso) or PostgreSQL options
-- **ORM choice** between Drizzle or Prisma
-- **Built-in authentication** with Better-Auth
-- **Optional PWA support** for installable web applications
-- **Desktop app capabilities** with Tauri integration
-- **Monorepo architecture** powered by Turborepo
+- Frontend: React (TanStack Router, React Router, TanStack Start), Next.js, Nuxt, Svelte, Solid, React Native (NativeWind/Unistyles), or none
+- Backend: Hono, Express, Fastify, Elysia, Next API Routes, Convex, or none
+- API: tRPC or oRPC (or none)
+- Runtime: Bun, Node.js, or Cloudflare Workers
+- Databases: SQLite, PostgreSQL, MySQL, MongoDB (or none)
+- ORMs: Drizzle, Prisma, Mongoose (or none)
+- Auth: Better-Auth (optional)
+- Addons: Turborepo, PWA, Tauri, Biome, Husky, Starlight, Fumadocs, Ultracite, Oxlint
+- Examples: Todo, AI
+- DB Setup: Turso, Neon, Supabase, Prisma PostgreSQL, MongoDB Atlas, Cloudflare D1, Docker
+- Web Deploy: Cloudflare Workers
+
+Type safety end-to-end, clean monorepo layout, and zero‑lock‑in: you choose only what you need.
 
 ## Repository Structure
 
 This repository is organized as a monorepo containing:
 
-- **CLI**: [`create-better-t-stack`](apps/cli) - The scaffolding CLI tool
-- **Documentation**: [`web`](apps/web) - Official website and documentation
+- **CLI**: [`apps/cli`](apps/cli) - The scaffolding CLI tool
+- **Documentation**: [`apps/web`](apps/web) - Official website and documentation
 
 ## Documentation
 
-Visit [better-t-stack.dev](https://better-t-stack.dev) for full documentation, guides, and examples.
+Visit [better-t-stack.dev](https://better-t-stack.dev) for full documentation, guides, and examples. You can also use the visual Stack Builder at `https://better-t-stack.dev/new` to generate a command for your stack.
 
 ## Development
 
 ```bash
 # Clone the repository
-git clone https://github.com/better-t-stack/create-better-t-stack.git
+git clone https://github.com/AmanVarshney01/create-better-t-stack.git
 
 # Install dependencies
 bun install
@@ -65,7 +68,10 @@ bun dev:web
 
 ## Want to contribute?
 
-Just fork the repository and submit a pull request!
+Please read the Contribution Guide first and open an issue before starting new features to ensure alignment with project goals.
+
+- Docs: [`Contributing`](/apps/web/content/docs/contributing.mdx)
+- Repo guide: [`.github/CONTRIBUTING.md`](.github/CONTRIBUTING.md)
 
 ## Star History
 

apps/cli/src/constants.ts

@@ -139,14 +139,3 @@ export const ADDON_COMPATIBILITY: Record<Addons, readonly Frontend[]> = {
 	fumadocs: [],
 	none: [],
 } as const;
-
-// TODO: need to refactor this
-export const WEB_FRAMEWORKS: readonly Frontend[] = [
-	"tanstack-router",
-	"react-router",
-	"tanstack-start",
-	"next",
-	"nuxt",
-	"svelte",
-	"solid",
-];

apps/cli/src/prompts/api.ts

@@ -1,6 +1,7 @@
 import { cancel, isCancel, select } from "@clack/prompts";
 import pc from "picocolors";
 import type { API, Backend, Frontend } from "../types";
+import { allowedApisForFrontends } from "../utils/compatibility-rules";
 
 export async function getApiChoice(
 	Api?: API | undefined,
@@ -11,46 +12,30 @@ export async function getApiChoice(
 		return "none";
 	}
 
-	if (Api) return Api;
+	const allowed = allowedApisForFrontends(frontend ?? []);
 
-	const includesNuxt = frontend?.includes("nuxt");
-	const includesSvelte = frontend?.includes("svelte");
-	const includesSolid = frontend?.includes("solid");
-
-	let apiOptions = [
-		{
-			value: "trpc" as const,
-			label: "tRPC",
-			hint: "End-to-end typesafe APIs made easy",
-		},
-		{
-			value: "orpc" as const,
-			label: "oRPC",
-			hint: "End-to-end type-safe APIs that adhere to OpenAPI standards",
-		},
-		{
-			value: "none" as const,
-			label: "None",
-			hint: "No API layer (e.g. for full-stack frameworks like Next.js with Route Handlers)",
-		},
-	];
-
-	if (includesNuxt || includesSvelte || includesSolid) {
-		apiOptions = [
-			{
-				value: "orpc" as const,
-				label: "oRPC",
-				hint: `End-to-end type-safe APIs (Recommended for ${
-					includesNuxt ? "Nuxt" : includesSvelte ? "Svelte" : "Solid"
-				} frontend)`,
-			},
-			{
-				value: "none" as const,
-				label: "None",
-				hint: "No API layer",
-			},
-		];
+	if (Api) {
+		return allowed.includes(Api) ? Api : allowed[0];
 	}
+	const apiOptions = allowed.map((a) =>
+		a === "trpc"
+			? {
+					value: "trpc" as const,
+					label: "tRPC",
+					hint: "End-to-end typesafe APIs made easy",
+				}
+			: a === "orpc"
+				? {
+						value: "orpc" as const,
+						label: "oRPC",
+						hint: "End-to-end type-safe APIs that adhere to OpenAPI standards",
+					}
+				: {
+						value: "none" as const,
+						label: "None",
+						hint: "No API layer (e.g. for full-stack frameworks like Next.js with Route Handlers)",
+					},
+	);
 
 	const apiType = await select<API>({
 		message: "Select API type",

apps/cli/src/prompts/examples.ts

@@ -2,6 +2,10 @@ import { cancel, isCancel, multiselect } from "@clack/prompts";
 import pc from "picocolors";
 import { DEFAULT_CONFIG } from "../constants";
 import type { API, Backend, Database, Examples, Frontend } from "../types";
+import {
+	isExampleAIAllowed,
+	isExampleTodoAllowed,
+} from "../utils/compatibility-rules";
 
 export async function getExamplesChoice(
 	examples?: Examples[],
@@ -30,27 +34,33 @@ export async function getExamplesChoice(
 	if (noFrontendSelected) return [];
 
 	let response: Examples[] | symbol = [];
-	const options: { value: Examples; label: string; hint: string }[] = [
-		{
+	const options: { value: Examples; label: string; hint: string }[] = [];
+
+	if (isExampleTodoAllowed(backend, database)) {
+		options.push({
 			value: "todo" as const,
 			label: "Todo App",
 			hint: "A simple CRUD example app",
-		},
-	];
+		});
+	}
 
-	if (backend !== "elysia" && !frontends?.includes("solid")) {
+	if (isExampleAIAllowed(backend, frontends ?? [])) {
 		options.push({
 			value: "ai" as const,
 			label: "AI Chat",
 			hint: "A simple AI chat interface using AI SDK",
 		});
 	}
 
+	if (options.length === 0) return [];
+
 	response = await multiselect<Examples>({
 		message: "Include examples",
 		options: options,
 		required: false,
-		initialValues: DEFAULT_CONFIG.examples,
+		initialValues: DEFAULT_CONFIG.examples?.filter((ex) =>
+			options.some((o) => o.value === ex),
+		),
 	});
 
 	if (isCancel(response)) {

apps/cli/src/prompts/frontend.ts

@@ -2,6 +2,7 @@ import { cancel, isCancel, multiselect, select } from "@clack/prompts";
 import pc from "picocolors";
 import { DEFAULT_CONFIG } from "../constants";
 import type { Backend, Frontend } from "../types";
+import { isFrontendAllowedWithBackend } from "../utils/compatibility-rules";
 
 export async function getFrontendChoice(
 	frontendOptions?: Frontend[],
@@ -73,12 +74,9 @@ export async function getFrontendChoice(
 			},
 		];
 
-		const webOptions = allWebOptions.filter((option) => {
-			if (backend === "convex") {
-				return option.value !== "solid";
-			}
-			return true;
-		});
+		const webOptions = allWebOptions.filter((option) =>
+			isFrontendAllowedWithBackend(option.value, backend),
+		);
 
 		const webFramework = await select<Frontend>({
 			message: "Choose web",

apps/cli/src/prompts/project-name.ts

@@ -1,10 +1,17 @@
 import path from "node:path";
 import { cancel, isCancel, text } from "@clack/prompts";
+import consola from "consola";
 import fs from "fs-extra";
 import pc from "picocolors";
 import { DEFAULT_CONFIG } from "../constants";
 import { ProjectNameSchema } from "../types";
 
+function isPathWithinCwd(targetPath: string): boolean {
+	const resolved = path.resolve(targetPath);
+	const rel = path.relative(process.cwd(), resolved);
+	return !rel.startsWith("..") && !path.isAbsolute(rel);
+}
+
 function validateDirectoryName(name: string): string | undefined {
 	if (name === ".") return undefined;
 
@@ -23,7 +30,11 @@ export async function getProjectName(initialName?: string): Promise<string> {
 		const finalDirName = path.basename(initialName);
 		const validationError = validateDirectoryName(finalDirName);
 		if (!validationError) {
-			return initialName;
+			const projectDir = path.resolve(process.cwd(), initialName);
+			if (isPathWithinCwd(projectDir)) {
+				return initialName;
+			}
+			consola.error(pc.red("Project path must be within current directory"));
 		}
 	}
 
@@ -56,7 +67,7 @@ export async function getProjectName(initialName?: string): Promise<string> {
 
 				if (nameToUse !== ".") {
 					const projectDir = path.resolve(process.cwd(), nameToUse);
-					if (!projectDir.startsWith(process.cwd())) {
+					if (!isPathWithinCwd(projectDir)) {
 						return "Project path must be within current directory";
 					}
 				}

apps/cli/src/prompts/web-deploy.ts

@@ -1,7 +1,8 @@
 import { cancel, isCancel, select } from "@clack/prompts";
 import pc from "picocolors";
-import { DEFAULT_CONFIG, WEB_FRAMEWORKS } from "../constants";
+import { DEFAULT_CONFIG } from "../constants";
 import type { Backend, Frontend, Runtime, WebDeploy } from "../types";
+import { WEB_FRAMEWORKS } from "../utils/compatibility";
 
 function hasWebFrontend(frontends: Frontend[]): boolean {
 	return frontends.some((f) => WEB_FRAMEWORKS.includes(f));

apps/cli/src/types.ts

@@ -17,9 +17,7 @@ export type Backend = z.infer<typeof BackendSchema>;
 
 export const RuntimeSchema = z
 	.enum(["bun", "node", "workers", "none"])
-	.describe(
-		"Runtime environment (workers only available with hono backend and drizzle orm)",
-	);
+	.describe("Runtime environment");
 export type Runtime = z.infer<typeof RuntimeSchema>;
 
 export const FrontendSchema = z
@@ -176,5 +174,3 @@ export interface BetterTStackConfig {
 	api: API;
 	webDeploy: WebDeploy;
 }
-
-export type AvailablePackageManagers = "npm" | "pnpm" | "bun";