@codabytez/create-next-template 0.1.0

package/templates/base/CONTRIBUTING.md

@@ -0,0 +1,120 @@
+# Contributing Guide
+
+## Branching Strategy
+
+### Main Branches
+
+| Branch | Purpose |
+|---|---|
+| `main` | Production — protected, requires 2 approvals |
+| `staging` | Pre-production testing — protected, requires 1 approval |
+| `dev` | Active development — protected, status checks required |
+
+### Working Branches
+
+| Prefix | Use for |
+|---|---|
+| `feature/*` | New features |
+| `fix/*` | Bug fixes |
+| `hotfix/*` | Urgent production fixes |
+| `chore/*` | Maintenance / dependency updates |
+| `docs/*` | Documentation only changes |
+
+---
+
+## Workflow
+
+```bash
+# 1. Pull latest from dev
+git checkout dev
+git pull origin dev
+
+# 2. Create your branch
+git checkout -b feature/your-feature-name
+
+# 3. Work, commit often
+git add .
+git commit -m "feat: add your feature"
+# pre-commit hook will run automatically:
+#   ✔ Prettier format check (auto-fixes if needed)
+#   ✔ ESLint (via lint-staged)
+#   ✔ TypeScript type check
+
+# 4. Push and open a PR into dev
+git push origin feature/your-feature-name
+```
+
+**PR flow:** `feature/*` → `dev` → `staging` → `main`
+
+---
+
+## Commit Message Format
+
+```
+<type>: <short description>
+```
+
+| Type | When to use |
+|---|---|
+| `feat` | New feature |
+| `fix` | Bug fix |
+| `refactor` | Code change that is not a feature or fix |
+| `style` | UI / styling changes |
+| `docs` | Documentation only |
+| `chore` | Maintenance, deps, config |
+| `test` | Adding or updating tests |
+
+**Examples:**
+```
+feat: add user profile page
+fix: correct date formatting on dashboard
+chore: upgrade tailwindcss to v4
+docs: update contributing guide
+```
+
+---
+
+## Git Hooks
+
+This project uses [Husky](https://typicode.github.io/husky/) to enforce quality automatically.
+
+### Pre-commit
+Runs on every `git commit`:
+- Prettier format check (auto-stages fixes if found)
+- ESLint + Prettier via lint-staged (only on staged files)
+- TypeScript type check
+
+### Pre-push
+Runs on every `git push`:
+- Full `next build` — push is blocked if the build fails
+
+If a hook blocks you, fix the issue it reports and try again. **Do not bypass hooks with `--no-verify`.**
+
+---
+
+## Code Standards
+
+- **No `console.log()`** — use `console.warn()` or `console.error()` only
+- **No `var`** — always use `const` or `let`
+- **No `any`** — avoid unless absolutely necessary (triggers a warning)
+- **Self-closing JSX** — `<Component />` not `<Component></Component>`
+- **No unnecessary curly braces in JSX** — `title="Hello"` not `title={"Hello"}`
+- **Unused variables** — prefix with `_` if intentionally unused (e.g. `_unused`)
+
+---
+
+## Code Review Checklist
+
+Before requesting a review, make sure:
+
+- [ ] All hooks pass (`pnpm lint`, `pnpm check-types`, `pnpm build`)
+- [ ] No `console.log` left in the code
+- [ ] New env variables are added to `.env.example`
+- [ ] UI changes are tested on mobile viewport
+- [ ] No commented-out code committed
+
+Reviewers will check:
+- [ ] Logic correctness
+- [ ] TypeScript types are accurate (no sneaky `as any`)
+- [ ] No unnecessary re-renders or missing `useCallback`/`useMemo`
+- [ ] Consistent naming with the rest of the codebase

package/templates/base/app/globals.css

@@ -0,0 +1,28 @@
+@import "tailwindcss";
+
+@theme {
+  /* ================================
+   * Colors — add your custom palette here
+   * ================================ */
+
+  /* --color-primary: #your-color;
+  --color-secondary: #your-color;
+  --color-accent: #your-color;
+  --color-background: #your-color;
+  --color-foreground: #your-color; */
+
+  /* ================================
+   * Typography
+   * ================================ */
+
+  /* --font-sans: "Inter", sans-serif;
+  --font-mono: "JetBrains Mono", monospace; */
+
+  /* ================================
+   * Spacing / Sizing overrides
+   * ================================ */
+
+  /* --radius-sm: 4px;
+  --radius-md: 8px;
+  --radius-lg: 12px; */
+}

package/templates/base/app/page.tsx

@@ -0,0 +1,7 @@
+export default function Home() {
+  return (
+    <main className="flex min-h-screen flex-col items-center justify-center p-24">
+      <h1 className="text-4xl font-bold">Hello World</h1>
+    </main>
+  );
+}

package/templates/base/components/ui/button.tsx

@@ -0,0 +1,40 @@
+import { cva, type VariantProps } from "class-variance-authority";
+import { cn } from "@/lib/utils";
+
+const buttonVariants = cva(
+  "inline-flex items-center justify-center rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50",
+  {
+    variants: {
+      variant: {
+        default: "bg-black text-white hover:bg-black/90",
+        outline: "border border-input bg-transparent hover:bg-accent hover:text-accent-foreground",
+        ghost: "hover:bg-accent hover:text-accent-foreground",
+        link: "text-primary underline-offset-4 hover:underline",
+        destructive: "bg-red-500 text-white hover:bg-red-600",
+      },
+      size: {
+        default: "h-10 px-4 py-2",
+        sm: "h-9 rounded-md px-3",
+        lg: "h-11 rounded-md px-8",
+        icon: "h-10 w-10",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+      size: "default",
+    },
+  }
+);
+
+export interface ButtonProps
+  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
+    VariantProps<typeof buttonVariants> {}
+
+export function Button({ className, variant, size, ...props }: ButtonProps) {
+  return (
+    <button
+      className={cn(buttonVariants({ variant, size, className }))}
+      {...props}
+    />
+  );
+}

package/templates/base/eslint.config.mjs

@@ -0,0 +1,51 @@
+import { dirname } from "path";
+import { fileURLToPath } from "url";
+import { FlatCompat } from "@eslint/eslintrc";
+import prettier from "eslint-plugin-prettier/recommended";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const compat = new FlatCompat({ baseDirectory: __dirname });
+
+const eslintConfig = [
+  ...compat.extends("next/core-web-vitals", "next/typescript"),
+  prettier,
+  {
+    rules: {
+      "prettier/prettier": "error",
+      "no-console": ["error", { allow: ["warn", "error"] }],
+      "no-debugger": "error",
+      "@typescript-eslint/no-unused-vars": [
+        "error",
+        {
+          argsIgnorePattern: "^_",
+          varsIgnorePattern: "^_",
+        },
+      ],
+      "@typescript-eslint/no-explicit-any": "warn",
+      "no-var": "error",
+      "prefer-const": "error",
+      "prefer-arrow-callback": "error",
+      "no-duplicate-imports": "error",
+      "react/self-closing-comp": "error",
+      "react/jsx-curly-brace-presence": [
+        "error",
+        { props: "never", children: "never" },
+      ],
+      "react-hooks/rules-of-hooks": "error",
+      "react-hooks/exhaustive-deps": "warn",
+    },
+  },
+  {
+    ignores: [
+      ".next/**",
+      "out/**",
+      "build/**",
+      "next-env.d.ts",
+      "node_modules/**",
+    ],
+  },
+];
+
+export default eslintConfig;

package/templates/base/lib/env.ts

@@ -0,0 +1,7 @@
+import { z } from "zod";
+
+const envSchema = z.object({
+  NODE_ENV: z.enum(["development", "production", "test"]).default("development"),
+});
+
+export const env = envSchema.parse(process.env);

package/templates/base/lib/utils.ts

@@ -0,0 +1,6 @@
+import { type ClassValue, clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}

package/templates/base/next.config.ts

@@ -0,0 +1,5 @@
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {};
+
+export default nextConfig;

package/templates/base/postcss.config.mjs

@@ -0,0 +1,7 @@
+const config = {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+};
+
+export default config;

package/templates/base/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true,
+    "plugins": [{ "name": "next" }],
+    "paths": {
+      "@/*": ["./*"]
+    }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}

package/templates/convex/.env.example

@@ -0,0 +1 @@
+NEXT_PUBLIC_CONVEX_URL=https://your-project.convex.cloud

package/templates/convex/convex/schema.ts

@@ -0,0 +1,10 @@
+import { defineSchema, defineTable } from "convex/server";
+import { v } from "convex/values";
+
+export default defineSchema({
+  users: defineTable({
+    name: v.string(),
+    email: v.string(),
+    clerkId: v.optional(v.string()),
+  }).index("by_email", ["email"]),
+});

package/templates/convex/convex/users.ts

@@ -0,0 +1,19 @@
+import { query, mutation } from "./_generated/server";
+import { v } from "convex/values";
+
+export const getUsers = query({
+  args: {},
+  handler: async (ctx) => {
+    return await ctx.db.query("users").collect();
+  },
+});
+
+export const createUser = mutation({
+  args: {
+    name: v.string(),
+    email: v.string(),
+  },
+  handler: async (ctx, args) => {
+    return await ctx.db.insert("users", args);
+  },
+});

package/templates/convex/providers/convex-provider.tsx

@@ -0,0 +1,15 @@
+"use client";
+
+import { ConvexProvider, ConvexReactClient } from "convex/react";
+
+const convex = new ConvexReactClient(
+  process.env.NEXT_PUBLIC_CONVEX_URL as string
+);
+
+export function ConvexClientProvider({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return <ConvexProvider client={convex}>{children}</ConvexProvider>;
+}

package/templates/data-fetching/lib/api.ts

@@ -0,0 +1,18 @@
+import axios from "axios";
+
+export const api = axios.create({
+  baseURL: process.env.NEXT_PUBLIC_API_URL ?? "/api",
+  headers: {
+    "Content-Type": "application/json",
+  },
+});
+
+api.interceptors.response.use(
+  (response) => response,
+  (error) => {
+    if (error.response?.status === 401) {
+      // Handle unauthorized — redirect or clear session
+    }
+    return Promise.reject(error);
+  }
+);

package/templates/data-fetching/providers/query-provider.tsx

@@ -0,0 +1,22 @@
+"use client";
+
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { useState } from "react";
+
+export function QueryProvider({ children }: { children: React.ReactNode }) {
+  const [queryClient] = useState(
+    () =>
+      new QueryClient({
+        defaultOptions: {
+          queries: {
+            staleTime: 60 * 1000,
+            retry: 1,
+          },
+        },
+      })
+  );
+
+  return (
+    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+  );
+}

package/templates/forms/components/forms/example-form.tsx

@@ -0,0 +1,58 @@
+"use client";
+
+import { useForm } from "react-hook-form";
+import { zodResolver } from "@hookform/resolvers/zod";
+import { exampleSchema, type ExampleFormValues } from "@/lib/validations/example";
+
+export function ExampleForm() {
+  const {
+    register,
+    handleSubmit,
+    formState: { errors, isSubmitting },
+  } = useForm<ExampleFormValues>({
+    resolver: zodResolver(exampleSchema),
+  });
+
+  async function onSubmit(data: ExampleFormValues) {
+    console.log(data);
+  }
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)} className="flex flex-col gap-4">
+      <div className="flex flex-col gap-1">
+        <label htmlFor="name" className="text-sm font-medium">Name</label>
+        <input
+          id="name"
+          {...register("name")}
+          className="rounded-md border px-3 py-2 text-sm"
+          placeholder="Your name"
+        />
+        {errors.name && (
+          <p className="text-xs text-red-500">{errors.name.message}</p>
+        )}
+      </div>
+
+      <div className="flex flex-col gap-1">
+        <label htmlFor="email" className="text-sm font-medium">Email</label>
+        <input
+          id="email"
+          type="email"
+          {...register("email")}
+          className="rounded-md border px-3 py-2 text-sm"
+          placeholder="you@example.com"
+        />
+        {errors.email && (
+          <p className="text-xs text-red-500">{errors.email.message}</p>
+        )}
+      </div>
+
+      <button
+        type="submit"
+        disabled={isSubmitting}
+        className="rounded-md bg-black px-4 py-2 text-sm text-white hover:bg-black/90 disabled:opacity-50"
+      >
+        {isSubmitting ? "Submitting..." : "Submit"}
+      </button>
+    </form>
+  );
+}

package/templates/forms/lib/validations/example.ts

@@ -0,0 +1,8 @@
+import { z } from "zod";
+
+export const exampleSchema = z.object({
+  name: z.string().min(2, "Name must be at least 2 characters"),
+  email: z.string().email("Invalid email address"),
+});
+
+export type ExampleFormValues = z.infer<typeof exampleSchema>;

package/templates/prisma/.env.example

@@ -0,0 +1 @@
+DATABASE_URL="postgresql://user:password@localhost:5432/mydb?schema=public"

package/templates/prisma/lib/db.ts

@@ -0,0 +1,11 @@
+import { PrismaClient } from "@prisma/client";
+
+const globalForPrisma = globalThis as unknown as { prisma: PrismaClient };
+
+export const db =
+  globalForPrisma.prisma ??
+  new PrismaClient({
+    log: process.env.NODE_ENV === "development" ? ["query", "error", "warn"] : ["error"],
+  });
+
+if (process.env.NODE_ENV !== "production") globalForPrisma.prisma = db;

package/templates/prisma/prisma/schema.prisma

@@ -0,0 +1,16 @@
+generator client {
+  provider = "prisma-client-js"
+}
+
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+}
+
+model User {
+  id        String   @id @default(cuid())
+  email     String   @unique
+  name      String?
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+}

package/templates/ui/components.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "default",
+  "rsc": true,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "app/globals.css",
+    "baseColor": "neutral",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  }
+}