@kood/claude-code 0.3.6 → 0.3.8

package/templates/nextjs/docs/guides/conventions.md

@@ -0,0 +1,343 @@
+# Conventions
+
+> Code writing rules
+
+---
+
+## File Names
+
+| Type | Rule | Example |
+|------|------|---------|
+| Component | kebab-case | `user-profile.tsx` |
+| Route | Next.js convention | `page.tsx`, `layout.tsx`, `[id]/page.tsx` |
+| Server Actions | kebab-case | `create-post.ts`, `posts.ts` |
+| Utilities | kebab-case | `format-date.ts` |
+
+---
+
+## TypeScript
+
+### Variable Declaration
+
+```typescript
+// ✅ Prefer const
+const user = { name: "Alice" }
+const posts = await prisma.post.findMany()
+
+// ❌ Minimize let
+let count = 0 // Only when mutation needed
+```
+
+### Function Declaration
+
+```typescript
+// ✅ const arrow function + explicit return type
+const getUser = async (id: string): Promise<User> => {
+  return prisma.user.findUnique({ where: { id } })
+}
+
+// ❌ function keyword (except export default)
+function getUser(id: string) {
+  return prisma.user.findUnique({ where: { id } })
+}
+```
+
+### Type Definition
+
+```typescript
+// ✅ interface (objects)
+interface User {
+  id: string
+  name: string
+  email: string
+}
+
+// ✅ type (unions, others)
+type Status = "active" | "inactive"
+type UserOrNull = User | null
+
+// ❌ No any → use unknown
+const data: unknown = JSON.parse(jsonString)
+```
+
+---
+
+## Import Order
+
+```typescript
+// 1. External libraries
+import { useState } from "react"
+import { useQuery } from "@tanstack/react-query"
+
+// 2. @/ alias
+import { Button } from "@/components/ui/button"
+import { prisma } from "@/database/prisma"
+
+// 3. Relative paths
+import { UserProfile } from "./-components/user-profile"
+
+// 4. Types (separate)
+import type { User } from "@/types"
+```
+
+---
+
+## Components
+
+### Server Component (default)
+
+```typescript
+// ✅ async function + direct data fetching
+export default async function PostsPage() {
+  const posts = await prisma.post.findMany()
+  return <PostsList posts={posts} />
+}
+```
+
+### Client Component
+
+```typescript
+// ✅ "use client" + interactivity
+"use client"
+
+import { useState } from "react"
+
+export function Counter() {
+  const [count, setCount] = useState(0)
+  return <button onClick={() => setCount(count + 1)}>{count}</button>
+}
+```
+
+---
+
+## Server Actions
+
+### File Top
+
+```typescript
+// ✅ "use server" + multiple functions
+"use server"
+
+export async function createPost(formData: FormData) {
+  // ...
+}
+
+export async function deletePost(id: string) {
+  // ...
+}
+```
+
+### Zod Validation
+
+```typescript
+"use server"
+
+import { z } from "zod"
+
+const schema = z.object({
+  title: z.string().min(1),
+  content: z.string(),
+})
+
+export async function createPost(formData: FormData) {
+  const parsed = schema.parse({
+    title: formData.get("title"),
+    content: formData.get("content"),
+  })
+
+  // ...
+}
+```
+
+---
+
+## Comments
+
+```typescript
+// ✅ Comments per code block
+// Check user authentication
+const session = await auth.api.getSession({ headers: headers() })
+if (!session?.user) redirect("/login")
+
+// Fetch posts
+const posts = await prisma.post.findMany({
+  where: { userId: session.user.id },
+  orderBy: { createdAt: "desc" },
+})
+
+// ❌ Comments on every line
+const session = await auth.api.getSession({ headers: headers() }) // Get session
+if (!session?.user) redirect("/login") // Redirect to login
+```
+
+---
+
+## Prisma
+
+### Multi-File Structure
+
+```
+prisma/schema/
+├── +base.prisma    # datasource, generator
+├── +enum.prisma    # all enums
+└── user.prisma     # User model
+```
+
+### Required Comments
+
+```prisma
+/// User
+model User {
+  id        String   @id @default(cuid())  /// Unique ID
+  email     String   @unique                /// Email (unique)
+  name      String?                         /// Name (optional)
+  role      Role     @default(USER)         /// Role
+  createdAt DateTime @default(now())        /// Created at
+  updatedAt DateTime @updatedAt             /// Updated at
+}
+
+/// Role
+enum Role {
+  USER   /// Regular user
+  ADMIN  /// Administrator
+}
+```
+
+---
+
+## Folder Structure
+
+```
+app/
+├── (auth)/              # Route Group
+│   ├── login/
+│   │   └── page.tsx
+│   └── signup/
+│       └── page.tsx
+├── dashboard/
+│   ├── page.tsx
+│   ├── -components/     # Page-specific (required)
+│   │   ├── stats.tsx
+│   │   └── chart.tsx
+│   └── settings/
+│       └── page.tsx
+└── _components/         # Shared Client Components
+```
+
+**Rules:**
+- `-components/` - Page-specific (cannot import from outside)
+- `_components/` - Shared (not included in routes)
+
+---
+
+## Custom Hook Order
+
+```typescript
+"use client"
+
+export function useExample() {
+  // 1. State (useState, zustand)
+  const [count, setCount] = useState(0)
+
+  // 2. Global Hooks
+  const router = useRouter()
+  const params = useParams()
+  const searchParams = useSearchParams()
+
+  // 3. React Query
+  const { data: posts } = useQuery({ queryKey: ["posts"], queryFn: getPosts })
+  const mutation = useMutation({ mutationFn: createPost })
+
+  // 4. Event Handlers
+  const handleClick = () => {
+    setCount(count + 1)
+  }
+
+  // 5. useMemo
+  const total = useMemo(() => posts?.length || 0, [posts])
+
+  // 6. useEffect
+  useEffect(() => {
+    console.log(count)
+  }, [count])
+
+  return { count, handleClick, total }
+}
+```
+
+---
+
+## Best Practices
+
+### ✅ DO
+
+```typescript
+// 1. Explicit types
+const getUser = async (id: string): Promise<User> => { /* ... */ }
+
+// 2. Zod validation
+const schema = z.object({ email: z.email() })
+const parsed = schema.parse(data)
+
+// 3. Error handling
+try {
+  await prisma.post.create({ data })
+} catch (error) {
+  console.error("Error creating post:", error)
+  throw error
+}
+
+// 4. revalidatePath
+await prisma.post.create({ data })
+revalidatePath("/posts")
+```
+
+### ❌ DON'T
+
+```typescript
+// 1. Using any
+const data: any = await fetchData() // ❌
+
+// 2. Missing validation
+const email = formData.get("email") // ❌ Need Zod validation
+await createUser({ email })
+
+// 3. Ignoring errors
+await prisma.post.create({ data }) // ❌ Need try-catch
+
+// 4. Missing cache invalidation
+await prisma.post.create({ data }) // ❌ Need revalidatePath
+```
+
+---
+
+## Git Commits
+
+```bash
+# ✅ Single line, with prefix
+git commit -m "feat: add post creation feature"
+git commit -m "fix: resolve login bug"
+
+# ❌ Multiple lines, emojis, AI markers
+git commit -m "feat: add post creation feature
+
+Detailed description...
+
+Co-Authored-By: Claude Code <noreply@anthropic.com>"  # ❌
+```
+
+**Prefixes:**
+- `feat` - New feature
+- `fix` - Bug fix
+- `refactor` - Refactoring
+- `style` - Code style
+- `docs` - Documentation
+- `test` - Tests
+- `chore` - Others
+
+---
+
+## References
+
+- [Next.js Official Docs](https://nextjs.org/docs)
+- [TypeScript Official Docs](https://www.typescriptlang.org/)

package/templates/nextjs/docs/guides/getting-started.md

@@ -0,0 +1,367 @@
+# Getting Started
+
+> Start with Next.js 15
+
+---
+
+## Create Project
+
+```bash
+npx create-next-app@latest my-app \
+  --typescript \
+  --tailwind \
+  --app \
+  --src-dir \
+  --import-alias "@/*"
+
+cd my-app
+npm run dev
+```
+
+---
+
+## Required Dependencies
+
+```bash
+# Database
+npm install prisma @prisma/client
+npm install -D prisma
+
+# Validation
+npm install zod
+
+# Auth
+npm install better-auth
+
+# Data Fetching
+npm install @tanstack/react-query
+```
+
+---
+
+## Folder Structure
+
+```
+src/
+├── app/
+│   ├── layout.tsx              # Root layout
+│   ├── page.tsx                # Home
+│   ├── (auth)/
+│   │   ├── login/
+│   │   │   └── page.tsx
+│   │   └── signup/
+│   │       └── page.tsx
+│   ├── dashboard/
+│   │   ├── page.tsx
+│   │   └── -components/        # Page-specific
+│   └── api/
+│       └── auth/
+│           └── [...all]/
+│               └── route.ts
+├── actions/                    # Server Actions (shared)
+│   ├── posts.ts
+│   └── users.ts
+├── components/
+│   └── ui/                     # UI components
+├── lib/
+│   ├── auth.ts                 # Better Auth setup
+│   ├── auth-client.ts          # Auth Client
+│   ├── prisma.ts               # Prisma Client
+│   └── query-client.ts         # React Query Client
+├── database/
+│   └── prisma.ts
+└── middleware.ts
+```
+
+---
+
+## Environment Variables
+
+```bash
+# .env.local
+DATABASE_URL="postgresql://user:password@localhost:5432/mydb"
+BETTER_AUTH_SECRET="your-secret-key"
+BETTER_AUTH_URL="http://localhost:3000"
+
+# Social login (optional)
+GOOGLE_CLIENT_ID="..."
+GOOGLE_CLIENT_SECRET="..."
+GITHUB_CLIENT_ID="..."
+GITHUB_CLIENT_SECRET="..."
+
+# Public client variables
+NEXT_PUBLIC_APP_URL="http://localhost:3000"
+```
+
+---
+
+## Prisma Setup
+
+```bash
+# Initialize
+npx prisma init
+
+# Create schema
+mkdir -p prisma/schema
+```
+
+```prisma
+// prisma/schema/+base.prisma
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+}
+
+generator client {
+  provider = "prisma-client-js"
+  output   = "../node_modules/.prisma/client"
+}
+```
+
+```prisma
+// prisma/schema/+enum.prisma
+enum Role {
+  USER
+  ADMIN
+}
+```
+
+```prisma
+// prisma/schema/user.prisma
+model User {
+  id        String   @id @default(cuid())
+  email     String   @unique
+  name      String?
+  role      Role     @default(USER)
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+}
+```
+
+```bash
+# Sync database
+npx prisma db push
+
+# Generate client
+npx prisma generate
+```
+
+---
+
+## Prisma Client
+
+```typescript
+// src/database/prisma.ts
+import { PrismaClient } from "@prisma/client"
+
+const globalForPrisma = globalThis as unknown as {
+  prisma: PrismaClient | undefined
+}
+
+export const prisma = globalForPrisma.prisma ?? new PrismaClient()
+
+if (process.env.NODE_ENV !== "production") globalForPrisma.prisma = prisma
+```
+
+---
+
+## Better Auth Setup
+
+```typescript
+// src/lib/auth.ts
+import { betterAuth } from "better-auth"
+import { prismaAdapter } from "better-auth/adapters/prisma"
+import { prisma } from "@/database/prisma"
+
+export const auth = betterAuth({
+  database: prismaAdapter(prisma, { provider: "postgresql" }),
+  emailAndPassword: { enabled: true },
+  socialProviders: {
+    google: {
+      clientId: process.env.GOOGLE_CLIENT_ID!,
+      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
+    },
+  },
+})
+```
+
+```typescript
+// src/lib/auth-client.ts
+import { createAuthClient } from "better-auth/react"
+
+export const authClient = createAuthClient({
+  baseURL: process.env.NEXT_PUBLIC_APP_URL!,
+})
+```
+
+```typescript
+// app/api/auth/[...all]/route.ts
+import { auth } from "@/lib/auth"
+
+export const GET = (request: Request) => auth.handler(request)
+export const POST = (request: Request) => auth.handler(request)
+```
+
+---
+
+## React Query Setup
+
+```typescript
+// src/lib/query-client.ts
+import { QueryClient } from "@tanstack/react-query"
+
+export function makeQueryClient() {
+  return new QueryClient({
+    defaultOptions: {
+      queries: {
+        staleTime: 60 * 1000, // 1 minute
+      },
+    },
+  })
+}
+
+let browserQueryClient: QueryClient | undefined = undefined
+
+export function getQueryClient() {
+  if (typeof window === "undefined") {
+    return makeQueryClient()
+  } else {
+    if (!browserQueryClient) browserQueryClient = makeQueryClient()
+    return browserQueryClient
+  }
+}
+```
+
+```typescript
+// app/providers.tsx
+"use client"
+
+import { QueryClientProvider } from "@tanstack/react-query"
+import { getQueryClient } from "@/lib/query-client"
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  const queryClient = getQueryClient()
+
+  return (
+    <QueryClientProvider client={queryClient}>
+      {children}
+    </QueryClientProvider>
+  )
+}
+```
+
+```typescript
+// app/layout.tsx
+import { Providers } from "./providers"
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        <Providers>{children}</Providers>
+      </body>
+    </html>
+  )
+}
+```
+
+---
+
+## First Server Action
+
+```typescript
+// actions/posts.ts
+"use server"
+
+import { z } from "zod"
+import { prisma } from "@/database/prisma"
+import { revalidatePath } from "next/cache"
+
+const createPostSchema = z.object({
+  title: z.string().min(1),
+  content: z.string(),
+})
+
+export async function createPost(formData: FormData) {
+  const parsed = createPostSchema.parse({
+    title: formData.get("title"),
+    content: formData.get("content"),
+  })
+
+  const post = await prisma.post.create({ data: parsed })
+  revalidatePath("/posts")
+  return post
+}
+```
+
+---
+
+## First Page (Server Component)
+
+```typescript
+// app/posts/page.tsx
+import { prisma } from "@/database/prisma"
+
+export default async function PostsPage() {
+  const posts = await prisma.post.findMany()
+
+  return (
+    <div>
+      <h1>Posts</h1>
+      <ul>
+        {posts.map(post => (
+          <li key={post.id}>{post.title}</li>
+        ))}
+      </ul>
+    </div>
+  )
+}
+```
+
+---
+
+## First Form (Client Component)
+
+```typescript
+// app/posts/_components/create-post-form.tsx
+"use client"
+
+import { useMutation, useQueryClient } from "@tanstack/react-query"
+import { createPost } from "@/actions/posts"
+
+export function CreatePostForm() {
+  const queryClient = useQueryClient()
+
+  const mutation = useMutation({
+    mutationFn: createPost,
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ["posts"] })
+    },
+  })
+
+  return (
+    <form
+      onSubmit={(e) => {
+        e.preventDefault()
+        const formData = new FormData(e.currentTarget)
+        mutation.mutate(formData)
+      }}
+    >
+      <input name="title" placeholder="Title" required />
+      <textarea name="content" placeholder="Content" required />
+      <button type="submit" disabled={mutation.isPending}>
+        {mutation.isPending ? "Creating..." : "Create Post"}
+      </button>
+    </form>
+  )
+}
+```
+
+---
+
+## Next Steps
+
+- [Conventions](conventions.md) - Code conventions
+- [Routes](routes.md) - Routing patterns
+- [Server Actions](server-actions.md) - Server Actions patterns
+- [Client Components](client-components.md) - Client Components patterns