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

package/templates/default/.eslintrc.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "https://json.schemastore.org/eslintrc",
+  "extends": [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/recommended",
+    "plugin:react/recommended",
+    "plugin:react-hooks/recommended"
+  ],
+  "plugins": ["@typescript-eslint", "react", "react-hooks"],
+  "parser": "@typescript-eslint/parser",
+  "parserOptions": {
+    "ecmaVersion": "latest",
+    "sourceType": "module",
+    "ecmaFeatures": {
+      "jsx": true
+    }
+  },
+  "settings": {
+    "react": {
+      "version": "detect"
+    }
+  },
+  "rules": {
+    "@typescript-eslint/no-unused-vars": [
+      "error",
+      {
+        "argsIgnorePattern": "^_"
+      }
+    ],
+    "@typescript-eslint/no-explicit-any": "error",
+    "react/react-in-jsx-scope": "error",
+    "react-hooks/rules-of-hooks": "error",
+    "react-hooks/exhaustive-deps": "warn"
+  }
+}

package/templates/default/.prettierrc.json

@@ -0,0 +1,7 @@
+{
+  "semi": false,
+  "trailingComma": "es5",
+  "singleQuote": true,
+  "tabWidth": 2,
+  "useTabs": false
+}

package/templates/default/README.md

@@ -0,0 +1,346 @@
+# Recurring Rabbit
+
+> A production-ready micro-SaaS starter built with TanStack Start, tRPC, Drizzle, Better-auth, and Tailwind CSS.
+
+## Quick Start
+
+```bash
+# Install dependencies
+npm install
+
+# Start development server
+npm run dev
+
+# Open http://localhost:3000 and create an account
+```
+
+## What's Included
+
+- 🔐 **Authentication** - Email/password with verification via Better-auth
+- 🗄️ **Database** - SQLite (dev) / Postgres (prod) with Drizzle ORM
+- 🌐 **Full-stack** - TanStack Start with tRPC for type-safe APIs
+- 🎨 **Styling** - Tailwind CSS with shadcn/ui components
+- ⚡ **TypeScript** - End-to-end type safety
+- 🔧 **Developer Tools** - Hot reload, ESLint, Prettier, VS Code config
+
+## Project Structure
+
+```
+src/
+├── app/           # TanStack Start routes
+├── server/        # tRPC API and database
+├── components/    # Reusable UI components
+└── lib/           # Shared utilities
+```
+
+## Key Commands
+
+```bash
+# Development
+npm run dev              # Start development server
+npm run build            # Build for production
+npm run start            # Start production server
+
+# Bundle Analysis
+npm run build:analyze    # Build with bundle analyzer (opens stats.html)
+
+# Database
+npm run db:generate      # Generate migration files
+npm run db:migrate       # Apply migrations
+npm run db:studio        # Open Drizzle Studio
+npm run db:seed          # Seed database with sample data
+
+# Code Quality
+npm run typecheck       # Run TypeScript checks
+npm run lint             # Run ESLint
+npm run lint:fix         # Fix ESLint issues
+npm run format           # Format code with Prettier
+npm run clean            # Clean build artifacts
+```
+
+## Environment Setup
+
+Copy `.env.example` to `.env.local` and customize:
+
+```bash
+cp .env.example .env.local
+```
+
+Required variables:
+
+- `BETTER_AUTH_SECRET` - Random 32+ character string (auto-generated during setup)
+- `RESEND_API_KEY` - For email verification (get from [Resend](https://resend.com))
+
+Optional variables (production):
+
+- `DATABASE_URL` - PostgreSQL connection string
+- `BETTER_AUTH_URL` - Your production domain (https://yourdomain.com)
+- `PUBLIC_APP_URL` - Same as BETTER_AUTH_URL
+
+## Development
+
+### Bundle Analysis
+
+Analyze your bundle size to identify large dependencies and optimize performance:
+
+```bash
+npm run build:analyze
+```
+
+This will build your application and generate a `stats.html` file in build output directory (`.vinxi`). Open this file in your browser to explore:
+
+- **Treemap view** - Visual representation of module sizes
+- **Gzip/Brotli sizes** - Real-world compression impact
+- **Module hierarchy** - See which modules depend on what
+
+**Tips for optimization:**
+
+- Look for large dependencies that could be tree-shaken
+- Identify duplicate code that can be deduplicated
+- Check if route-based code splitting is working
+- Remove unused dependencies when possible
+
+### Performance Monitoring
+
+Monitor application performance to identify bottlenecks:
+
+```bash
+# Run Lighthouse CI to check performance budgets
+npm run lighthouse
+```
+
+The project includes performance monitoring tools:
+
+**Slow Query Logging** (Development):
+
+- Database queries over 1 second are logged to console
+- Helps identify database performance issues
+- Enabled automatically in development mode
+
+**Client Hydration Timing** (Development):
+
+- Track component hydration time
+- Components taking over 100ms to hydrate trigger warnings
+- Use `markHydrationStart()` and `markHydrationEnd()` in components
+
+**Performance Budgets** (Lighthouse CI):
+
+- First Contentful Paint: < 2000ms
+- Largest Contentful Paint: < 2500ms
+- Time to Interactive: < 3500ms
+- JavaScript bundles: < 150KB
+- Total page size: < 500KB
+
+**Using Monitoring in Code:**
+
+```typescript
+// Track database queries
+import { measureQuery } from '@/lib/monitoring'
+
+const result = await measureQuery('SELECT * FROM users', () => {
+  return db.query(users.findMany())
+})
+
+// Track hydration
+import { markHydrationStart, markHydrationEnd } from '@/lib/hydration-timing'
+
+export function MyComponent() {
+  markHydrationStart('MyComponent')
+
+  useEffect(() => {
+    markHydrationEnd('MyComponent')
+  }, [])
+
+  return <div>...</div>
+}
+```
+
+### Adding New Features
+
+**Database Tables**
+
+1. Define schema in `src/server/db/schema.ts`
+2. Generate migration: `npm run db:generate`
+3. Apply migration: `npm run db:migrate`
+
+```typescript
+export const posts = sqliteTable('posts', {
+  id: text('id')
+    .primaryKey()
+    .$defaultFn(() => createId()),
+  title: text('title').notNull(),
+  content: text('content').notNull(),
+  userId: text('user_id').references(() => users.id, { onDelete: 'cascade' }),
+  createdAt: integer('created_at', { mode: 'timestamp' }).$defaultFn(
+    () => new Date()
+  ),
+})
+```
+
+**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()`
+
+```typescript
+export const postsRouter = router({
+  create: protectedProcedure
+    .input(z.object({ title: z.string(), content: z.string() }))
+    .mutation(async ({ ctx, input }) => {
+      return await ctx.db
+        .insert(posts)
+        .values({
+          ...input,
+          userId: ctx.user.id,
+        })
+        .returning()
+    }),
+})
+```
+
+**New Pages**
+
+1. Add route file in `src/app/[route].tsx`
+2. Implement component with TanStack Start conventions
+3. Add navigation in layout components
+
+**Protected Pages**
+
+```typescript
+export const Route = createFileRoute('/dashboard')({
+  beforeLoad: ({ context }) => {
+    if (!context.auth.user) {
+      throw redirect({ to: '/auth/login' })
+    }
+  },
+  component: Dashboard,
+})
+```
+
+### Adding UI Components
+
+1. Install shadcn component: `npx shadcn-ui add [component]`
+2. Customize styling in component file or CSS variables
+3. Create feature-specific components in `src/components/features/`
+
+## Deployment
+
+### Vercel (Recommended)
+
+```bash
+vercel deploy
+```
+
+Set environment variables in Vercel dashboard and add production PostgreSQL database.
+
+### Railway
+
+```bash
+railway up
+```
+
+Railway provides built-in PostgreSQL hosting.
+
+### Environment Variables for Production
+
+- `BETTER_AUTH_SECRET` - New random 32+ character string
+- `DATABASE_URL` - Production PostgreSQL connection string
+- `BETTER_AUTH_URL` - Your production domain (https://yourdomain.com)
+- `PUBLIC_APP_URL` - Same as BETTER_AUTH_URL
+- `RESEND_API_KEY` - Production API key from Resend
+
+### Database Migrations in Production
+
+When deploying to production with PostgreSQL:
+
+```bash
+npm run db:migrate
+```
+
+Make sure to test migrations locally with PostgreSQL before deploying.
+
+## Database Schema
+
+The database includes the following tables:
+
+- **users** - User accounts with email verification
+- **sessions** - Active user sessions
+- **accounts** - OAuth provider accounts (for future use)
+- **verifications** - Email verification and password reset tokens
+
+View and edit the schema in `src/server/db/schema.ts`.
+
+## Authentication Flow
+
+1. User registers with email/password
+2. Email verification required before dashboard access
+3. Sessions stored in database with automatic cleanup
+4. CSRF protection enabled on all authenticated routes
+5. Password reset flow available (requires Resend setup)
+
+## Troubleshooting
+
+### pnpm Native Module Build Issues
+
+pnpm blocks build scripts for native modules by default. If you encounter better-sqlite3 issues:
+
+```bash
+pnpm rebuild better-sqlite3
+```
+
+Or use npm/yarn instead of pnpm.
+
+### Drizzle-kit Migrate with SQLite
+
+Use `drizzle-kit push` instead of `drizzle-kit migrate` for SQLite to avoid multi-statement SQL issues.
+
+### Email Not Sending
+
+1. Verify RESEND_API_KEY is set in `.env.local`
+2. Check Resend dashboard for API key status
+3. Verify email domain is verified in Resend
+4. Configure SPF/DKIM records for email deliverability
+
+### Database Locked (SQLite)
+
+If you get "database is locked" errors:
+
+```bash
+npm run clean
+# Then restart dev server
+```
+
+This removes SQLite WAL files that can cause locking issues.
+
+## Documentation
+
+- [Architecture Overview](docs/architecture.md) - System design and key decisions
+- [Adding Features](docs/adding-features.md) - Common patterns and examples
+- [Deployment Guide](docs/deployment.md) - Platform-specific deployment instructions
+- [Database Schema](docs/database.md) - Complete schema documentation
+- [Troubleshooting](docs/troubleshooting.md) - Common issues and solutions
+
+## Architecture Decisions
+
+### Why TanStack Start over Next.js?
+
+- Better TypeScript integration with less configuration
+- File-based routing without App Router complexity
+- Smaller bundle size for micro-SaaS use cases
+
+### Why Better-auth over NextAuth?
+
+- Simpler configuration for basic email/password auth
+- Better TypeScript support with fewer generic type issues
+- Database session storage built-in for scalability
+
+### Why Drizzle over Prisma?
+
+- Zero runtime overhead with compile-time query building
+- Better migration control with SQL-first approach
+- Lighter weight for simple SaaS data models
+
+## License
+
+MIT - See LICENSE file for details.

package/templates/default/app.config.ts

@@ -0,0 +1,20 @@
+import { defineConfig } from '@tanstack/start/config'
+import { visualizer } from 'rollup-plugin-visualizer'
+
+export default defineConfig({
+  tsr: {
+    appDirectory: 'src/app',
+    routesDirectory: 'src/app',
+  },
+  vite: {
+    plugins: [
+      visualizer({
+        filename: 'stats.html',
+        open: process.env.ANALYZE_BUNDLE === 'true',
+        gzipSize: true,
+        brotliSize: true,
+        template: 'treemap',
+      }),
+    ],
+  },
+})