feat(cli): Add lefthook addon (#711)

* initial lefthook support

* lefthook template

* lefthook addon

* skip lefthook template if no linter selected

* template update

* always add lefthook.yml file

* lint-staged only necessary w/ husky

* file fixing

* lefthook and husky work in parallel

* git hooks group

* spacing fix

* reordered addons section to make more sense

* fixed ultracite compat

* skip lefthook template if ultracite configured

* coderabbit fixes

* newest lefthook version

* 'bun check' fixes

* hasLinting

* logic fixes

* fixed merge conflict

* feat: add lefthook to dependencyVersionMap

* refactor: update lefthook config to use newer jobs syntax

- Changed from 'commands' object syntax to 'jobs' array syntax
- Added --write flag to biome check for file fixing
- Follows latest lefthook documentation recommendations

* fix: remove unnecessary glob from oxfmt job

* fix: update ultracite setup to match latest CLI

- Fixed --integrations flag to pass values correctly
- Added lint-staged to integrations array when husky is selected
- Added claude hook option
- Added new agents: cursor-cli, mistral-vibe, vercel

* fix: init git before install dependencies

Prepare scripts (lefthook install, husky) require a git repo to exist.
Moving git init before install ensures these hooks can be properly set up.

* Revert "fix: init git before install dependencies"

This reverts commit 475d87d.

* fix: make prepare scripts git-aware to avoid install failures

The prepare script now checks if a git repo exists before running.
If no .git directory exists, the script silently succeeds, avoiding
errors during initial install when git init happens after bun install.

* fix: husky uses simple prepare, lefthook uses git check

- Husky v9+ handles missing .git directory gracefully
- Lefthook needs git check as lefthook install fails without git repo

* fix: remove biome.json.hbs from ultracite templates

Ultracite creates its own linter config via CLI init command.
The biome.json template was incorrectly being copied even when
oxlint was selected as the linter.

* fix: remove prepare script for lefthook (auto-installs via postinstall)

* refactor: move lefthook config to template-generator with package manager

- Moved lefthook.yml.hbs to template-generator/templates/addons/lefthook/
- Template uses {{packageManager}} for commands (bun oxlint, bun oxfmt)
- Removed programmatic generation from addons-setup.ts
- Fixes 'command not found' errors for oxlint/oxfmt

* chore: regenerate embedded templates with lefthook

* feat: add lefthook install instructions to post-install output

* fix

---------

Co-authored-by: Aman Varshney <amanvarshney.work@gmail.com>

Author: therealsamyak

README.md

@@ -44,7 +44,7 @@ npx create-better-t-stack@latest
 - 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, Ruler, Ultracite, Oxlint
+- Addons: Turborepo, PWA, Tauri, Biome, Lefthook, Husky, Starlight, Fumadocs, Ruler, Ultracite, Oxlint
 - Examples: Todo, AI
 - DB Setup: Turso, Neon, Supabase, Prisma PostgreSQL, MongoDB Atlas, Cloudflare D1, Docker
 - Web Deploy: Cloudflare Workers

apps/cli/README.md

@@ -41,7 +41,7 @@ Follow the prompts to configure your project or use the `--yes` flag for default
 | **Database Setup**       | • Turso (SQLite)<br>• Cloudflare D1 (SQLite)<br>• Neon (PostgreSQL)<br>• Supabase (PostgreSQL)<br>• Prisma Postgres<br>• MongoDB Atlas<br>• None (manual setup)                                                                                            |
 | **Authentication**       | Better-Auth (email/password, with more options coming soon)                                                                                                                                                                                                |
 | **Styling**              | Tailwind CSS with shadcn/ui components                                                                                                                                                                                                                     |
-| **Addons**               | • PWA support<br>• Tauri (desktop applications)<br>• Starlight (documentation site)<br>• Biome (linting and formatting)<br>• Husky (Git hooks)<br>• Turborepo (optimized builds)                                                                           |
+| **Addons**               | • PWA support<br>• Tauri (desktop applications)<br>• Starlight (documentation site)<br>• Biome (linting and formatting)<br>• Lefthook, Husky (Git hooks)<br>• Turborepo (optimized builds)                                                                 |
 | **Examples**             | • Todo app<br>• AI Chat interface (using Vercel AI SDK)                                                                                                                                                                                                    |
 | **Developer Experience** | • Automatic Git initialization<br>• Package manager choice (npm, pnpm, bun)<br>• Automatic dependency installation                                                                                                                                         |
 
@@ -58,7 +58,7 @@ Options:
   --auth                          Include authentication
   --no-auth                       Exclude authentication
   --frontend <types...>           Frontend types (tanstack-router, react-router, tanstack-start, next, nuxt, svelte, solid, native-bare, native-uniwind, native-unistyles, none)
-  --addons <types...>             Additional addons (pwa, tauri, starlight, biome, husky, turborepo, fumadocs, ultracite, oxlint, none)
+  --addons <types...>             Additional addons (pwa, tauri, starlight, biome, lefthook, husky, turborepo, fumadocs, ultracite, oxlint, none)
   --examples <types...>           Examples to include (todo, ai, none)
   --git                           Initialize git repository
   --no-git                        Skip git initialization
@@ -193,7 +193,7 @@ npx create-better-t-stack --frontend none --backend hono --api trpc --database n
 - **ORM 'none'**: Can be used when you want to handle database operations manually or use a different ORM.
 - **Runtime 'none'**: Only available with Convex backend or when backend is 'none'.
 - **Cloudflare Workers runtime**: Only compatible with Hono backend, Drizzle ORM (or no ORM), and SQLite database (with D1 setup). Not compatible with MongoDB.
-- **Addons 'none'**: Skips all addons (PWA, Tauri, Starlight, Biome, Husky, Turborepo).
+- **Addons 'none'**: Skips all addons (PWA, Tauri, Starlight, Biome, Lefthook,Husky, Turborepo).
 - **Examples 'none'**: Skips all example implementations (todo, AI chat).
 - **SvelteKit, Nuxt, and SolidJS** frontends are only compatible with oRPC API layer
 - **PWA support** requires React with TanStack Router, React Router, or SolidJS

apps/cli/src/constants.ts

@@ -51,6 +51,7 @@ export const ADDON_COMPATIBILITY = {
   tauri: ["tanstack-router", "react-router", "nuxt", "svelte", "solid", "next"],
   biome: [],
   husky: [],
+  lefthook: [],
   turborepo: [],
   starlight: [],
   ultracite: [],

apps/cli/src/helpers/addons/addons-setup.ts

@@ -38,9 +38,15 @@ export async function setupAddons(config: ProjectConfig) {
   const hasUltracite = addons.includes("ultracite");
   const hasBiome = addons.includes("biome");
   const hasHusky = addons.includes("husky");
+  const hasLefthook = addons.includes("lefthook");
   const hasOxlint = addons.includes("oxlint");
 
-  if (!hasUltracite) {
+  if (hasUltracite) {
+    const gitHooks: string[] = [];
+    if (hasHusky) gitHooks.push("husky");
+    if (hasLefthook) gitHooks.push("lefthook");
+    await setupUltracite(config, gitHooks);
+  } else {
     if (hasBiome) {
       await setupBiome(projectDir);
     }
@@ -49,14 +55,19 @@ export async function setupAddons(config: ProjectConfig) {
       await setupOxlint(projectDir, config.packageManager);
     }
 
-    if (hasHusky) {
+    if (hasHusky || hasLefthook) {
       let linter: "biome" | "oxlint" | undefined;
       if (hasOxlint) {
         linter = "oxlint";
       } else if (hasBiome) {
         linter = "biome";
       }
-      await setupHusky(projectDir, linter);
+      if (hasHusky) {
+        await setupHusky(projectDir, linter);
+      }
+      if (hasLefthook) {
+        await setupLefthook(projectDir);
+      }
     }
   }
 
@@ -76,10 +87,6 @@ export async function setupAddons(config: ProjectConfig) {
     await setupWxt(config);
   }
 
-  if (hasUltracite) {
-    await setupUltracite(config, hasHusky);
-  }
-
   if (addons.includes("ruler")) {
     await setupRuler(config);
   }
@@ -136,3 +143,11 @@ export async function setupHusky(projectDir: string, linter?: "biome" | "oxlint"
     await fs.writeJson(packageJsonPath, packageJson, { spaces: 2 });
   }
 }
+
+export async function setupLefthook(projectDir: string) {
+  await addPackageDependency({
+    devDependencies: ["lefthook"],
+    projectDir,
+  });
+  // lefthook.yml is generated by template-generator from templates/addons/lefthook/
+}

apps/cli/src/helpers/addons/ultracite-setup.ts

@@ -41,9 +41,12 @@ type UltraciteAgent =
   | "crush"
   | "qwen"
   | "amazon-q-cli"
-  | "firebender";
+  | "firebender"
+  | "cursor-cli"
+  | "mistral-vibe"
+  | "vercel";
 
-type UltraciteHook = "cursor" | "windsurf";
+type UltraciteHook = "cursor" | "windsurf" | "claude";
 
 const LINTERS = {
   biome: { label: "Biome", hint: "Fast formatter and linter" },
@@ -85,11 +88,15 @@ const AGENTS = {
   qwen: { label: "Qwen" },
   "amazon-q-cli": { label: "Amazon Q CLI" },
   firebender: { label: "Firebender" },
+  "cursor-cli": { label: "Cursor CLI" },
+  "mistral-vibe": { label: "Mistral Vibe" },
+  vercel: { label: "Vercel" },
 } as const;
 
 const HOOKS = {
   cursor: { label: "Cursor" },
   windsurf: { label: "Windsurf" },
+  claude: { label: "Claude" },
 } as const;
 
 function getFrameworksFromFrontend(frontend: string[]): string[] {
@@ -117,7 +124,7 @@ function getFrameworksFromFrontend(frontend: string[]): string[] {
   return Array.from(frameworks);
 }
 
-export async function setupUltracite(config: ProjectConfig, hasHusky: boolean) {
+export async function setupUltracite(config: ProjectConfig, gitHooks: string[]) {
   const { packageManager, projectDir, frontend } = config;
 
   try {
@@ -193,8 +200,12 @@ export async function setupUltracite(config: ProjectConfig, hasHusky: boolean) {
       ultraciteArgs.push("--hooks", ...hooks);
     }
 
-    if (hasHusky) {
-      ultraciteArgs.push("--integrations", "husky", "lint-staged");
+    if (gitHooks.length > 0) {
+      const integrations = [...gitHooks];
+      if (gitHooks.includes("husky")) {
+        integrations.push("lint-staged");
+      }
+      ultraciteArgs.push("--integrations", ...integrations);
     }
 
     const ultraciteArgsString = ultraciteArgs.join(" ");

apps/cli/src/helpers/core/post-installation.ts

@@ -39,7 +39,12 @@ export async function displayPostInstallInstructions(
     packageManager === "npm" ? "npm run" : packageManager === "pnpm" ? "pnpm run" : "bun run";
   const cdCmd = `cd ${relativePath}`;
   const hasHusky = addons?.includes("husky");
-  const hasLinting = addons?.includes("biome") || addons?.includes("oxlint");
+  const hasLefthook = addons?.includes("lefthook");
+  const hasGitHooksOrLinting =
+    addons?.includes("husky") ||
+    addons?.includes("biome") ||
+    addons?.includes("lefthook") ||
+    addons?.includes("oxlint");
 
   const databaseInstructions =
     !isConvex && database !== "none"
@@ -56,7 +61,8 @@ export async function displayPostInstallInstructions(
 
   const tauriInstructions = addons?.includes("tauri") ? getTauriInstructions(runCmd) : "";
   const huskyInstructions = hasHusky ? getHuskyInstructions(runCmd) : "";
-  const lintingInstructions = hasLinting ? getLintingInstructions(runCmd) : "";
+  const lefthookInstructions = hasLefthook ? getLefthookInstructions(packageManager) : "";
+  const lintingInstructions = hasGitHooksOrLinting ? getLintingInstructions(runCmd) : "";
   const nativeInstructions =
     (frontend?.includes("native-bare") ||
       frontend?.includes("native-uniwind") ||
@@ -184,6 +190,7 @@ export async function displayPostInstallInstructions(
   if (databaseInstructions) output += `\n${databaseInstructions.trim()}\n`;
   if (tauriInstructions) output += `\n${tauriInstructions.trim()}\n`;
   if (huskyInstructions) output += `\n${huskyInstructions.trim()}\n`;
+  if (lefthookInstructions) output += `\n${lefthookInstructions.trim()}\n`;
   if (lintingInstructions) output += `\n${lintingInstructions.trim()}\n`;
   if (pwaInstructions) output += `\n${pwaInstructions.trim()}\n`;
   if (alchemyDeployInstructions) output += `\n${alchemyDeployInstructions.trim()}\n`;
@@ -250,6 +257,13 @@ function getLintingInstructions(runCmd: string) {
   )} Format and lint fix: ${`${runCmd} check`}\n`;
 }
 
+function getLefthookInstructions(packageManager: string) {
+  const cmd = packageManager === "npm" ? "npx" : packageManager;
+  return `${pc.bold("Git hooks with Lefthook:")}\n${pc.cyan(
+    "•",
+  )} Install hooks: ${cmd} lefthook install\n`;
+}
+
 async function getDatabaseInstructions(
   database: Database,
   orm: ORM,

apps/cli/src/prompts/addons.ts

@@ -43,6 +43,10 @@ function getAddonDisplay(addon: Addons): { label: string; hint: string } {
       label = "Ruler";
       hint = "Centralize your AI rules";
       break;
+    case "lefthook":
+      label = "Lefthook";
+      hint = "Fast and powerful Git hooks manager";
+      break;
     case "husky":
       label = "Husky";
       hint = "Modern native Git hooks made easy";
@@ -72,7 +76,7 @@ function getAddonDisplay(addon: Addons): { label: string; hint: string } {
 }
 
 const ADDON_GROUPS = {
-  Tooling: ["turborepo", "biome", "oxlint", "ultracite", "husky"],
+  Tooling: ["turborepo", "biome", "oxlint", "ultracite", "husky", "lefthook"],
   Documentation: ["starlight", "fumadocs"],
   Extensions: ["pwa", "tauri", "opentui", "wxt", "ruler"],
 };

apps/cli/test/addons.test.ts

@@ -6,7 +6,7 @@ import { expectError, expectSuccess, runTRPCTest, type TestConfig } from "./test
 
 describe("Addon Configurations", () => {
   describe("Universal Addons (no frontend restrictions)", () => {
-    const universalAddons = ["biome", "husky", "turborepo", "oxlint"];
+    const universalAddons = ["biome", "lefthook", "husky", "turborepo", "oxlint"];
 
     for (const addon of universalAddons) {
       it(`should work with ${addon} addon on any frontend`, async () => {
@@ -195,6 +195,27 @@ describe("Addon Configurations", () => {
       expectSuccess(result);
     });
 
+    it("should work with lefthook and husky together", async () => {
+      const result = await runTRPCTest({
+        projectName: "both-git-hooks",
+        addons: ["lefthook", "husky"],
+        frontend: ["tanstack-router"],
+        backend: "hono",
+        runtime: "bun",
+        database: "sqlite",
+        orm: "drizzle",
+        auth: "none",
+        api: "trpc",
+        examples: ["none"],
+        dbSetup: "none",
+        webDeploy: "none",
+        serverDeploy: "none",
+        install: false,
+      });
+
+      expectSuccess(result);
+    });
+
     it("should fail with incompatible addon combination", async () => {
       const result = await runTRPCTest({
         projectName: "incompatible-addons-fail",

apps/web/content/docs/cli/options.mdx

@@ -291,6 +291,7 @@ Additional features to include:
 - `starlight`: Starlight documentation site
 - `fumadocs`: Fumadocs documentation site
 - `biome`: Biome linting and formatting
+- `lefthook`: Git hooks with Lefthook
 - `husky`: Git hooks with Husky
 - `turborepo`: Turborepo monorepo setup
 - `ultracite`: Ultracite configuration

apps/web/content/docs/index.mdx

@@ -311,7 +311,7 @@ See the full list in the [CLI Reference](/docs/cli). Key flags:
 - `--api`: trpc, orpc, none
 - `--auth`: better-auth, clerk, none
 - `--payments`: polar, none
-- `--addons`: turborepo, pwa, tauri, biome, husky, starlight, fumadocs, ultracite, oxlint, ruler, opentui, wxt, none
+- `--addons`: turborepo, pwa, tauri, biome, lefthook, husky, starlight, fumadocs, ultracite, oxlint, ruler, opentui, wxt, none
 - `--examples`: todo, ai, none
 
 ## Next Steps