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

package/templates/default/docs/troubleshooting.md

@@ -0,0 +1,668 @@
+# Troubleshooting
+
+## Development Issues
+
+### pnpm Native Module Build Issues
+
+**Error:** `Error: Cannot find module 'better-sqlite3'`
+
+**Cause:** pnpm blocks build scripts for native modules by default
+
+**Solution 1:** Rebuild native module
+
+```bash
+pnpm rebuild better-sqlite3
+```
+
+**Solution 2:** Use npm/yarn instead
+
+```bash
+npm install
+# or
+yarn install
+```
+
+### Drizzle-kit Migrate Issues with SQLite
+
+**Error:** `Error: cannot start a transaction within a transaction`
+
+**Cause:** Multi-statement SQL files don't work well with better-sqlite3
+
+**Solution:** Use `drizzle-kit push` instead of `migrate`
+
+```bash
+# Instead of:
+npm run db:migrate
+
+# Use:
+npx drizzle-kit push
+```
+
+### Database Locked (SQLite)
+
+**Error:** `Error: database is locked`
+
+**Cause:** WAL (Write-Ahead Logging) file still open from previous session
+
+**Solution:** Clean build artifacts
+
+```bash
+npm run clean
+# This removes data/*.db-shm and data/*.db-wal files
+```
+
+### Port Already in Use
+
+**Error:** `Error: Port 3000 is already in use`
+
+**Solution 1:** Kill process on port 3000
+
+```bash
+# Linux/Mac
+lsof -ti:3000 | xargs kill -9
+
+# Windows
+netstat -ano | findstr :3000
+# Then kill the process
+```
+
+**Solution 2:** Change port
+
+```bash
+# In app.config.ts or pass environment variable
+PORT=3001 npm run dev
+```
+
+## Installation Issues
+
+### Dependencies Not Installing
+
+**Error:** `Error: Cannot resolve dependency`
+
+**Cause:** npm registry issues or network problems
+
+**Solution 1:** Clear cache and reinstall
+
+```bash
+rm -rf node_modules package-lock.json
+npm install
+```
+
+**Solution 2:** Use different registry
+
+```bash
+npm install --registry=https://registry.npmjs.org
+```
+
+### TypeScript Errors After Install
+
+**Error:** Type errors in VS Code but not in terminal
+
+**Cause:** VS Code not using workspace TypeScript version
+
+**Solution:** Reload TypeScript server
+
+1. Command Palette (Ctrl/Cmd + Shift + P)
+2. Type: "TypeScript: Restart TS Server"
+3. Select option
+
+### Module Not Found Errors
+
+**Error:** `Error: Cannot find module '@/lib/auth'`
+
+**Cause:** Path alias not configured or incorrect import path
+
+**Solution:**
+
+1. Check `tsconfig.json` has path alias:
+
+```json
+{
+  "compilerOptions": {
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  }
+}
+```
+
+2. Restart TypeScript server
+3. Verify file exists at `src/lib/auth.ts`
+
+## Authentication Issues
+
+### Email Not Sending
+
+**Error:** User registers but doesn't receive verification email
+
+**Cause 1:** RESEND_API_KEY not set
+
+```bash
+# Check .env.local
+cat .env.local | grep RESEND_API_KEY
+```
+
+**Cause 2:** RESEND_API_KEY is test key
+
+- Test keys only send to verified email addresses
+- Production key required for all emails
+
+**Cause 3:** Domain not verified in Resend
+
+1. Go to [Resend Dashboard](https://resend.com/domains)
+2. Verify your domain
+3. Configure SPF/DKIM records
+
+### Session Not Persisting
+
+**Error:** User logs in but is immediately logged out
+
+**Cause:** Cookie not set correctly or browser blocking cookies
+
+**Solution 1:** Check browser cookie settings
+
+1. Open DevTools → Application → Cookies
+2. Verify `better-auth.session_token` cookie exists
+3. Check cookie domain matches current domain
+
+**Solution 2:** Clear cookies and try again
+
+```bash
+# In DevTools → Application → Storage → Clear site data
+# Or manually delete all cookies for localhost:3000
+```
+
+### CSRF Token Errors
+
+**Error:** `Error: Invalid CSRF token`
+
+**Cause:** CSRF protection enabled but cookies not set correctly
+
+**Solution:** Check authentication configuration
+
+```typescript
+// src/server/auth/config.ts
+export const auth = betterAuth({
+  csrf: {
+    enabled: true, // Should be true
+    // Check cookie settings
+  },
+})
+```
+
+## Build Issues
+
+### Build Fails with TypeScript Errors
+
+**Error:** Type errors during `npm run build`
+
+**Solution 1:** Run typecheck first
+
+```bash
+npm run typecheck
+```
+
+**Solution 2:** Check for `any` types
+
+```bash
+# Check if any types are used
+grep -r "any" src/ --include="*.ts" --include="*.tsx"
+```
+
+**Solution 3:** Fix specific errors
+
+- Follow VS Code TypeScript errors
+- Check IMPLEMENTATION_PLAN.md for known issues
+
+### Production Build is Slow
+
+**Issue:** Build takes more than 30 seconds
+
+**Cause 1:** Large dependencies
+
+- Check bundle size
+- Remove unused dependencies
+
+**Cause 2:** Source maps enabled in production
+
+```typescript
+// tsconfig.json
+{
+  "compilerOptions": {
+    "sourceMap": false // Set to false for production builds
+  }
+}
+```
+
+## Production Issues
+
+### Environment Variables Not Found
+
+**Error:** `Error: BETTER_AUTH_SECRET is required`
+
+**Cause:** Environment variables not set in deployment platform
+
+**Vercel:**
+
+1. Go to project settings → Environment Variables
+2. Add `BETTER_AUTH_SECRET`
+3. Add `DATABASE_URL`
+4. Add `RESEND_API_KEY`
+
+**Railway:**
+
+1. Go to project → Variables
+2. Add all required variables
+3. Redeploy
+
+**Docker:**
+
+```bash
+docker run -e BETTER_AUTH_SECRET="..." -e DATABASE_URL="..." my-app
+```
+
+### Database Connection Failed
+
+**Error:** `Error: connect ECONNREFUSED` or `Error: invalid input syntax`
+
+**Cause 1:** Wrong DATABASE_URL format
+
+**Solution:** Verify connection string format
+
+```
+# PostgreSQL format:
+postgres://user:password@host:port/database
+
+# SQLite (dev):
+file:data/app.db
+```
+
+**Cause 2:** Database not accessible from production server
+
+- Check database firewall settings
+- Verify VPC/network configuration
+- Check database is running
+
+### Page Not Found (404)
+
+**Cause:** Route not configured or incorrect path
+
+**Solution 1:** Check route file exists
+
+```bash
+# Verify file exists
+ls src/app/dashboard/index.tsx
+
+# Verify correct naming (not index.ts)
+```
+
+**Solution 2:** Check TanStack Start router
+
+1. Open DevTools Console
+2. Check for route registration errors
+3. Restart dev server
+
+## Performance Issues
+
+### Hot Reload Slow
+
+**Issue:** Changes take > 1 second to reflect
+
+**Cause 1:** Large files being rebuilt
+
+**Solution 1:** Split large components into smaller files
+**Solution 2:** Use code splitting for routes
+
+**Cause 2:** File watchers not working
+
+**Solution:** Restart dev server
+
+```bash
+# Stop (Ctrl+C) and restart
+npm run dev
+```
+
+### Page Load Slow
+
+**Issue:** First Contentful Paint (FCP) > 2 seconds
+
+**Cause 1:** Large bundle size
+
+**Solution 1:** Check bundle size
+
+```bash
+# Run bundle analyzer
+npm run build:analyze
+
+# This will build and generate stats.html
+# Open the file in your browser to visualize bundle size
+```
+
+**Solution 2:** Optimize images
+
+- Use WebP format
+- Compress images before uploading
+
+**Cause 2:** Database queries slow
+
+**Solution:** Add indexes and optimize queries (see docs/database.md)
+
+## Bundle Analyzer Issues
+
+### Bundle Analyzer Not Opening
+
+**Issue:** `stats.html` file not opening automatically
+
+**Cause:** `ANALYZE_BUNDLE` environment variable not set or auto-open disabled
+
+**Solution 1:** Use the build:analyze script
+
+```bash
+npm run build:analyze
+```
+
+This script automatically sets `ANALYZE_BUNDLE=true` and opens the visualization.
+
+**Solution 2:** Manually open stats.html
+
+```bash
+# Build with analyzer
+ANALYZE_BUNDLE=true npm run build
+
+# Then manually open the file
+# Find stats.html in .vinxi or build output directory
+open .vinxi/stats.html  # macOS
+xdg-open .vinxi/stats.html  # Linux
+start .vinxi/stats.html  # Windows
+```
+
+### Bundle Size Too Large
+
+**Issue:** JavaScript bundle > 150KB
+
+**Common causes:**
+
+1. **Large dependencies included in bundle**
+   - Check if libraries are being imported properly
+   - Use dynamic imports for code splitting
+
+2. **Duplicate dependencies**
+   - Check bundle analyzer for duplicates
+   - Deduplicate using package.json resolutions
+
+3. **Unused code not tree-shaken**
+   - Use ES modules (import/export)
+   - Avoid CommonJS imports
+
+**Solutions:**
+
+1. **Check bundle analyzer for largest modules**
+   - Open `stats.html`
+   - Look for large rectangles (bigger = larger size)
+   - Identify which dependencies are taking space
+
+2. **Replace large dependencies**
+   - Use lighter alternatives when possible
+   - Example: Replace moment.js with date-fns
+
+3. **Use dynamic imports**
+
+   ```typescript
+   // Instead of:
+   import { Chart } from 'chart.js'
+
+   // Use:
+   const Chart = await import('chart.js')
+   ```
+
+4. **Optimize images**
+   - Compress images before adding to project
+   - Use WebP format
+   - Lazy load images below the fold
+
+### stats.html File Not Found
+
+**Issue:** Cannot locate `stats.html` after running build analyzer
+
+**Cause:** Build output directory different than expected
+
+**Solution 1:** Check common locations
+
+```bash
+# Build output locations to check:
+ls -la .vinxi/stats.html
+ls -la .output/stats.html
+ls -la dist/stats.html
+ls -la build/stats.html
+
+# Or search for it:
+find . -name "stats.html" -type f
+```
+
+**Solution 2:** Verify bundle analyzer configuration
+
+Check `app.config.ts`:
+
+```typescript
+// Ensure visualizer plugin is configured
+export default defineConfig({
+  vite: {
+    plugins: [
+      visualizer({
+        filename: 'stats.html', // Note this filename
+        open: true,
+      }),
+    ],
+  },
+})
+```
+
+### Bundle Analyzer Shows Empty Results
+
+**Issue:** `stats.html` loads but shows no modules or data
+
+**Cause 1:** Build failed but analyzer still ran
+
+**Solution:** Check build logs for errors
+
+```bash
+# Check terminal output for build errors
+npm run build:analyze
+
+# If there are errors, fix them first
+npm run typecheck
+npm run lint
+```
+
+**Cause 2:** No code or empty routes
+
+**Solution:** Verify your application has code
+
+- Check that `src/app/` has route files
+- Ensure components have actual code
+- Verify dependencies are installed
+
+**Cause 3:** Incorrect bundler configuration
+
+**Solution:** Verify TanStack Start config
+
+```typescript
+// app.config.ts
+import { defineConfig } from '@tanstack/start/config'
+
+export default defineConfig({
+  tsr: {
+    appDirectory: 'src/app',
+    routesDirectory: 'src/app',
+  },
+  // ... rest of config
+})
+```
+
+## Email Delivery Issues
+
+### Emails Going to Spam
+
+**Cause 1:** SPF record not configured
+
+**Solution:** Add SPF record to DNS
+
+```
+@  IN  TXT  "v=spf1 include:resend.com ~all"
+```
+
+**Cause 2:** DKIM record not configured
+
+**Solution:** Add DKIM record
+
+1. Go to Resend → Domains → Your domain → DKIM
+2. Copy the TXT record
+3. Add to DNS
+
+**Cause 3:** Domain reputation is new
+
+**Solution:**
+
+- Send emails to verified email addresses first
+- Start with small volume
+- Gradually increase over time
+
+## Deployment Issues
+
+### Deployment Fails
+
+**Error:** Build failed in Vercel/Railway
+
+**Cause 1:** Build errors not caught locally
+
+**Solution:** Run production build locally
+
+```bash
+npm run build
+# Check for errors
+```
+
+**Cause 2:** Environment variables missing
+
+**Solution:** Check deployment logs for missing variables
+
+- Add all required variables
+- Redeploy
+
+### Deployment succeeds but app doesn't work
+
+**Cause 1:** Wrong environment for DATABASE_URL
+
+**Solution:** Ensure DATABASE_URL points to production database, not SQLite
+
+**Cause 2:** Node version mismatch
+
+**Solution:** Check Node.js version in platform
+
+```bash
+# Should match package.json engines field
+node -v
+# Should be >= 18
+```
+
+## Getting Help
+
+### Check Logs
+
+**Development:**
+
+- Terminal output from `npm run dev`
+- Browser console (DevTools)
+- tRPC DevTools
+- React DevTools
+
+**Production:**
+
+- Vercel: Build logs and function logs
+- Railway: Service logs
+- Application monitoring (Sentry, LogRocket if configured)
+
+### Common Debugging Steps
+
+1. **Restart everything**
+   - Stop dev server
+   - Clear node_modules (if needed)
+   - Reinstall dependencies
+   - Restart dev server
+
+2. **Check environment variables**
+   - Verify `.env.local` exists
+   - Verify all required variables set
+   - Restart server after changes
+
+3. **Check database**
+   - Run `npm run db:studio` to browse database
+   - Verify data exists
+   - Check for corrupted data
+
+4. **Check logs**
+   - Dev server logs
+   - Browser console
+   - Network tab for API calls
+
+### Community Resources
+
+- **GitHub Issues:** Check [project issues page](../../issues)
+- **Documentation:** See [README.md](../README.md)
+- **TanStack Start:** https://tanstack.com/start/latest/docs
+- **tRPC:** https://trpc.io/docs
+- **Drizzle:** https://orm.drizzle.team/docs
+- **Better-auth:** https://www.better-auth.com/docs
+
+## Known Limitations
+
+### Current Limitations
+
+1. **No OAuth providers** configured yet (only email/password)
+2. **No multi-tenancy** support (single-organization)
+3. **No background jobs** queue system
+4. **No admin dashboard** for managing users
+
+### Workarounds
+
+**OAuth Providers:**
+
+- Use accounts table (already in schema)
+- Configure Better-auth with Google/GitHub providers
+- See Better-auth documentation for setup
+
+**Multi-tenancy:**
+
+- Add `organizationId` to user tables
+- Filter queries by organization
+- Update auth context to include organization
+
+## Reporting Issues
+
+When reporting issues, include:
+
+1. **Node.js version:** `node -v`
+2. **Package manager:** `npm -v` or `pnpm -v`
+3. **Operating system:** Mac/Linux/Windows
+4. **Error message:** Full error from console
+5. **Steps to reproduce:** What you did before error
+6. **Expected vs actual:** What you expected vs what happened
+
+**Example issue report:**
+
+```
+Node: v20.11.0
+pnpm: 8.15.0
+OS: macOS 14.2
+
+Error: Cannot find module '@/lib/auth'
+
+Steps:
+1. Cloned repo
+2. Ran `pnpm install`
+3. Started `pnpm dev`
+4. Got error in terminal
+
+Expected: Dev server starts
+Actual: Module not found error
+```

package/templates/default/drizzle/migrations/0001_initial_schema.sql

@@ -0,0 +1,39 @@
+CREATE TABLE `accounts` (
+	`id` text PRIMARY KEY NOT NULL,
+	`user_id` text NOT NULL,
+	`account_id` text NOT NULL,
+	`provider_id` text NOT NULL,
+	`access_token` text,
+	`refresh_token` text,
+	`expires_at` integer,
+	`created_at` integer DEFAULT (strftime('%s', 'now')) NOT NULL,
+	FOREIGN KEY (`user_id`) REFERENCES `users`(`id`) ON UPDATE no action ON DELETE cascade
+);
+
+CREATE TABLE `sessions` (
+	`id` text PRIMARY KEY NOT NULL,
+	`user_id` text NOT NULL,
+	`expires_at` integer NOT NULL,
+	`created_at` integer DEFAULT (strftime('%s', 'now')) NOT NULL,
+	FOREIGN KEY (`user_id`) REFERENCES `users`(`id`) ON UPDATE no action ON DELETE cascade
+);
+
+CREATE TABLE `users` (
+	`id` text PRIMARY KEY NOT NULL,
+	`email` text NOT NULL,
+	`name` text NOT NULL,
+	`email_verified` integer DEFAULT false,
+	`image` text,
+	`created_at` integer DEFAULT (strftime('%s', 'now')) NOT NULL,
+	`updated_at` integer
+);
+
+CREATE TABLE `verifications` (
+	`id` text PRIMARY KEY NOT NULL,
+	`identifier` text NOT NULL,
+	`value` text NOT NULL,
+	`expires_at` integer NOT NULL,
+	`created_at` integer DEFAULT (strftime('%s', 'now')) NOT NULL
+);
+
+CREATE UNIQUE INDEX `users_email_unique` ON `users` (`email`);