@amirulabu/create-recurring-rabbit-app 0.0.0-alpha

package/templates/default/docs/adding-features.md

@@ -0,0 +1,439 @@
+# Adding Features
+
+## Creating New Database Tables
+
+1. **Define schema** in `src/server/db/schema.ts`
+2. **Generate migration** with `npm run db:generate`
+3. **Apply migration** with `npm run db:migrate`
+
+Example:
+
+```typescript
+import { sqliteTable, text, integer } from 'drizzle-orm/sqlite-core'
+import { createId } from '@paralleldrive/cuid2'
+
+export const posts = sqliteTable('posts', {
+  id: text('id')
+    .primaryKey()
+    .$defaultFn(() => createId()),
+  title: text('title').notNull(),
+  content: text('content').notNull(),
+  published: integer('published', { mode: 'boolean' }).default(false),
+  userId: text('user_id').references(() => users.id, { onDelete: 'cascade' }),
+  createdAt: integer('created_at', { mode: 'timestamp' }).$defaultFn(
+    () => new Date()
+  ),
+  updatedAt: integer('updated_at', { mode: 'timestamp' }).$defaultFn(
+    () => new Date()
+  ),
+})
+```
+
+### Adding Relations
+
+```typescript
+import { relations } from 'drizzle-orm'
+
+export const usersRelations = relations(users, ({ many }) => ({
+  posts: many(posts),
+}))
+```
+
+## Adding tRPC Procedures
+
+1. **Create router** in `src/server/api/[feature].ts`
+2. **Add to root router** in `src/server/api/root.ts`
+3. **Use in components** via `api.[feature].[procedure].useQuery()`
+
+Example:
+
+```typescript
+import { z } from 'zod'
+import { router, protectedProcedure } from '../trpc'
+import { db } from '@/server/db'
+import { posts, users } from '@/server/db/schema'
+import { eq } from 'drizzle-orm'
+
+export const postsRouter = router({
+  list: protectedProcedure.query(async ({ ctx }) => {
+    return await db.select().from(posts).where(eq(posts.userId, ctx.user.id))
+  }),
+
+  create: protectedProcedure
+    .input(z.object({ title: z.string(), content: z.string() }))
+    .mutation(async ({ ctx, input }) => {
+      const result = await db
+        .insert(posts)
+        .values({
+          ...input,
+          userId: ctx.user.id,
+        })
+        .returning()
+      return result[0]
+    }),
+
+  update: protectedProcedure
+    .input(z.object({ id: z.string(), title: z.string(), content: z.string() }))
+    .mutation(async ({ ctx, input }) => {
+      const result = await db
+        .update(posts)
+        .set({
+          title: input.title,
+          content: input.content,
+          updatedAt: new Date(),
+        })
+        .where(eq(posts.id, input.id))
+        .returning()
+      return result[0]
+    }),
+
+  delete: protectedProcedure
+    .input(z.object({ id: z.string() }))
+    .mutation(async ({ ctx, input }) => {
+      await db.delete(posts).where(eq(posts.id, input.id))
+      return { success: true }
+    }),
+})
+```
+
+Add to root router:
+
+```typescript
+import { postsRouter } from './routers/posts'
+
+export const appRouter = router({
+  user: userRouter,
+  dashboard: dashboardRouter,
+  posts: postsRouter,
+})
+```
+
+## Creating New Pages
+
+1. **Add route file** in `src/app/[route].tsx`
+2. **Implement component** with TanStack Start conventions
+3. **Add navigation** in layout components
+
+Example:
+
+```typescript
+import { createFileRoute } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/posts')({
+  component: PostsPage,
+})
+
+function PostsPage() {
+  return (
+    <div>
+      <h1>Posts</h1>
+      <PostsList />
+    </div>
+  )
+}
+```
+
+## Protected Pages
+
+Protected pages require authentication and use `beforeLoad` guards:
+
+```typescript
+import { createFileRoute, redirect } from '@tanstack/react-router'
+import { api } from '@/lib/api'
+
+export const Route = createFileRoute('/dashboard/settings')({
+  beforeLoad: async ({ context }) => {
+    if (!context.auth.user) {
+      throw redirect({ to: '/auth/login' })
+    }
+  },
+  component: SettingsPage,
+})
+
+function SettingsPage() {
+  const { data: user } = api.user.getProfile.useQuery()
+
+  return <div>Settings for {user?.name}</div>
+}
+```
+
+## Adding UI Components
+
+### Using shadcn/ui Components
+
+1. Install shadcn component: `npx shadcn-ui add [component]`
+2. Use in your code with imports from `@/components/ui/[component]`
+
+Example:
+
+```bash
+npx shadcn-ui add dialog
+npx shadcn-ui add select
+```
+
+```typescript
+import { Dialog, DialogContent, DialogHeader, DialogTitle } from '@/components/ui/dialog'
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@/components/ui/select'
+
+function MyComponent() {
+  return (
+    <Dialog>
+      <DialogContent>
+        <DialogHeader>
+          <DialogTitle>Select Option</DialogTitle>
+        </DialogHeader>
+        <Select>
+          <SelectTrigger>
+            <SelectValue />
+          </SelectTrigger>
+          <SelectContent>
+            <SelectItem value="option1">Option 1</SelectItem>
+            <SelectItem value="option2">Option 2</SelectItem>
+          </SelectContent>
+        </Select>
+      </DialogContent>
+    </Dialog>
+  )
+}
+```
+
+### Creating Feature-Specific Components
+
+Create components in `src/components/features/[feature]/` to keep related code together:
+
+```typescript
+import { Button } from '@/components/ui/button'
+import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card'
+
+interface PostCardProps {
+  post: {
+    id: string
+    title: string
+    content: string
+    createdAt: Date
+  }
+}
+
+export function PostCard({ post }: PostCardProps) {
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>{post.title}</CardTitle>
+      </CardHeader>
+      <CardContent>
+        <p>{post.content}</p>
+        <p className="text-sm text-gray-500">{new Date(post.createdAt).toLocaleDateString()}</p>
+      </CardContent>
+    </Card>
+  )
+}
+```
+
+## Data Fetching Patterns
+
+### Query with tRPC
+
+```typescript
+function PostsList() {
+  const { data: posts, isLoading, error } = api.posts.list.useQuery()
+
+  if (isLoading) return <div>Loading...</div>
+  if (error) return <div>Error loading posts</div>
+
+  return (
+    <div>
+      {posts?.map((post) => (
+        <PostCard key={post.id} post={post} />
+      ))}
+    </div>
+  )
+}
+```
+
+### Mutation with tRPC
+
+```typescript
+function CreatePost() {
+  const createPost = api.posts.create.useMutation({
+    onSuccess: () => {
+      api.posts.list.invalidate()
+    },
+  })
+
+  const handleSubmit = (data: { title: string, content: string }) => {
+    createPost.mutate(data)
+  }
+
+  return (
+    <form onSubmit={(e) => {
+      e.preventDefault()
+      const formData = new FormData(e.currentTarget)
+      handleSubmit({
+        title: String(formData.get('title')),
+        content: String(formData.get('content')),
+      })
+    }}>
+      {/* form fields */}
+    </form>
+  )
+}
+```
+
+### Optimistic Updates
+
+```typescript
+const deletePost = api.posts.delete.useMutation({
+  onMutate: async (deletedId) => {
+    await queryClient.cancelQueries({ queryKey: ['posts.list'] })
+    const previousPosts = queryClient.getQueryData(['posts.list']) as Post[]
+
+    queryClient.setQueryData(
+      ['posts.list'],
+      previousPosts?.filter((p) => p.id !== deletedId.id)
+    )
+
+    return { previousPosts }
+  },
+  onError: (err, variables, context) => {
+    queryClient.setQueryData(['posts.list'], context?.previousPosts)
+  },
+  onSettled: () => {
+    queryClient.invalidateQueries({ queryKey: ['posts.list'] })
+  },
+})
+```
+
+## Common Patterns
+
+### Form Handling
+
+```typescript
+import { useState } from 'react'
+
+function MyForm() {
+  const [formData, setFormData] = useState({ name: '', email: '' })
+  const [errors, setErrors] = useState<Record<string, string>>({})
+  const [loading, setLoading] = useState(false)
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault()
+    setLoading(true)
+    setErrors({})
+
+    try {
+      await api.myProcedure.mutateAsync(formData)
+    } catch (error) {
+      setErrors({ submit: 'An error occurred' })
+    } finally {
+      setLoading(false)
+    }
+  }
+
+  return (
+    <form onSubmit={handleSubmit}>
+      {/* form fields */}
+      {errors.submit && <div className="error">{errors.submit}</div>}
+    </form>
+  )
+}
+```
+
+### Error Handling
+
+```typescript
+function MyComponent() {
+  const { data, error, isLoading } = api.myProcedure.useQuery()
+
+  if (error) {
+    return (
+      <div className="p-4 bg-red-50 border border-red-200 rounded-md">
+        <p className="text-red-600">Error: {error.message}</p>
+        <button onClick={() => api.myProcedure.refetch()}>Retry</button>
+      </div>
+    )
+  }
+
+  // render content
+}
+```
+
+### Loading States
+
+```typescript
+function MyComponent() {
+  const { data, isLoading } = api.myProcedure.useQuery()
+
+  if (isLoading) {
+    return (
+      <div className="flex items-center justify-center p-8">
+        <div className="animate-spin rounded-full h-8 w-8 border-b-2 border-blue-600" />
+        <span className="ml-2">Loading...</span>
+      </div>
+    )
+  }
+
+  return <div>{data?.content}</div>
+}
+```
+
+## Adding Third-Party Integrations
+
+### Stripe for Payments
+
+1. Install Stripe SDK: `npm install stripe`
+2. Add environment variable: `STRIPE_SECRET_KEY`
+3. Create webhook handler in `src/app/api/stripe-webhook.ts`
+4. Add procedures to handle payments
+
+```typescript
+import Stripe from 'stripe'
+
+const stripe = new Stripe(env.STRIPE_SECRET_KEY)
+
+export const paymentRouter = router({
+  createCheckout: protectedProcedure
+    .input(z.object({ priceId: z.string() }))
+    .mutation(async ({ ctx, input }) => {
+      const session = await stripe.checkout.sessions.create({
+        customer_email: ctx.user.email,
+        mode: 'payment',
+        line_items: [{ price: input.priceId, quantity: 1 }],
+        success_url: `${env.PUBLIC_APP_URL}/success`,
+        cancel_url: `${env.PUBLIC_APP_URL}/cancel`,
+      })
+      return { url: session.url }
+    }),
+})
+```
+
+### Email Service Extensions
+
+Customize email templates in `src/lib/email-templates/`:
+
+```typescript
+import { Resend } from 'resend'
+
+const resend = new Resend(env.RESEND_API_KEY)
+
+await resend.emails.send({
+  from: 'your-app@yourdomain.com',
+  to: 'user@example.com',
+  subject: 'Welcome!',
+  html: '<h1>Welcome to our app</h1>',
+})
+```
+
+## Testing New Features
+
+1. **Add table** → `npm run db:generate && npm run db:migrate`
+2. **Add tRPC procedure** → Test in tRPC DevTools
+3. **Add UI component** → Test in isolation
+4. **Add page** → Test navigation and rendering
+5. **Update types** → Verify type safety throughout
+
+Best practices:
+
+- Test each layer independently (database → tRPC → UI)
+- Use TypeScript to catch errors at compile time
+- Add loading and error states for better UX
+- Invalidate queries after mutations for data consistency

package/templates/default/docs/adr/001-use-sqlite-for-development-database.md

@@ -0,0 +1,22 @@
+# ADR-001: Use SQLite for Development Database
+
+## Status
+
+Accepted
+
+## Context
+
+Need development database with zero external dependencies but can migrate to production PostgreSQL
+
+## Decision
+
+Use SQLite for local development with automatic file creation
+
+## Consequences
+
+- **Positive**: Instant setup, no Docker/external services needed
+- **Negative**: Some PostgreSQL features not available in development
+
+## Implementation
+
+Auto-create data/app.db if DATABASE_URL not provided, use same Drizzle schema for both SQLite and PostgreSQL

package/templates/default/docs/adr/002-use-tanstack-start-over-nextjs.md

@@ -0,0 +1,22 @@
+# ADR-002: Use TanStack Start over Next.js
+
+## Status
+
+Accepted
+
+## Context
+
+Need modern React framework with SSR and file-based routing
+
+## Decision
+
+Use TanStack Start instead of Next.js
+
+## Consequences
+
+- **Positive**: Better TypeScript integration, file-based routing without App Router complexity, smaller bundle size
+- **Negative**: Smaller community, less documentation
+
+## Implementation
+
+Configure Vinxi bundler, file-based routing in src/app/, SSR enabled by default

package/templates/default/docs/adr/003-use-better-auth-over-nextauth.md

@@ -0,0 +1,22 @@
+# ADR-003: Use Better-auth over NextAuth
+
+## Status
+
+Accepted
+
+## Context
+
+Need authentication library with email/password, session management, and TypeScript support
+
+## Decision
+
+Use Better-auth instead of NextAuth
+
+## Consequences
+
+- **Positive**: Simpler configuration for basic email/password auth, better TypeScript support, database session storage built-in
+- **Negative**: Less mature, smaller ecosystem
+
+## Implementation
+
+Configure with Drizzle adapter, email verification flow, session management

package/templates/default/docs/adr/004-use-drizzle-over-prisma.md

@@ -0,0 +1,22 @@
+# ADR-004: Use Drizzle over Prisma
+
+## Status
+
+Accepted
+
+## Context
+
+Need ORM with type safety and migration management for micro-SaaS
+
+## Decision
+
+Use Drizzle ORM instead of Prisma
+
+## Consequences
+
+- **Positive**: Zero runtime overhead with compile-time query building, better migration control with SQL-first approach, lighter weight
+- **Negative**: Less intuitive API, fewer built-in features
+
+## Implementation
+
+Define schema in src/server/db/schema.ts, use drizzle-kit for migrations

package/templates/default/docs/adr/005-use-trpc-for-api-layer.md

@@ -0,0 +1,22 @@
+# ADR-005: Use tRPC for API Layer
+
+## Status
+
+Accepted
+
+## Context
+
+Need type-safe API with zero manual interface definitions
+
+## Decision
+
+Use tRPC v11 for API layer
+
+## Consequences
+
+- **Positive**: End-to-end type safety from database to UI, automatic type inference, zero code generation
+- **Negative**: Learning curve, different patterns from REST APIs
+
+## Implementation
+
+Define routers in src/server/api/routers/, integrate with TanStack Query

package/templates/default/docs/adr/006-use-tailwind-css-v4-with-shadcn-ui.md

@@ -0,0 +1,22 @@
+# ADR-006: Use Tailwind CSS v4 with shadcn/ui
+
+## Status
+
+Accepted
+
+## Context
+
+Need styling system with rapid development and professional components
+
+## Decision
+
+Use Tailwind CSS v4 with shadcn/ui components
+
+## Consequences
+
+- **Positive**: Rapid development, consistent design system, no need for custom CSS
+- **Negative**: Large HTML classes, potential bundle size increase
+
+## Implementation
+
+Configure Tailwind v4, install shadcn/ui components, use for all UI