Skip to content
RapidRoot Docs

FAQ & Troubleshooting

This section covers frequently asked questions, common pitfalls, and solutions for performance, setup, and security issues. If you’re stuck on something not covered here, consider opening an issue.

1. Common Setup Issues

1.1 Environment Variables

  • Ensure your .env.local file includes all required variables:
    • Supabase: NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY, SUPABASE_SERVICE_ROLE_KEY
    • Stripe: STRIPE_PUBLIC_KEY, STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET
    • Resend: RESEND_API_KEY, etc.
    • Upstash: UPSTASH_REDIS_REST_URL, UPSTASH_REDIS_REST_TOKEN
    • PostHog: NEXT_PUBLIC_POSTHOG_KEY, NEXT_PUBLIC_POSTHOG_HOST
  • Make sure you’ve copied the values exactly from each service’s dashboard—typos or missing keys will cause errors.
  • Optional variables: Some fields (like RESEND_AUDIENCE_ID) might be optional. Check each service’s docs to confirm.

1.2 Email Configuration

  • Resend Dashboard: Verify your Resend API key is valid and your domain is properly configured (if using a custom domain).
  • Email Schema Validation: If you’re using Zod or another validation layer, confirm your EmailSchema matches what you’re sending.
  • Test Emails:
    • Use Resend’s playground or a local environment to confirm emails are sent successfully.
    • Check your spam/junk folder if you don’t see test messages.

2. Performance Optimization

2.1 Bundle Analysis

  • Add a bundle analysis script in your package.json (if not included by default). For Next.js, you might use next build --profile or specialized plugins like @next/bundle-analyzer.
{
  "scripts": {
    "analyze": "cross-env ANALYZE=true next build"
  }
}
  • Run npm run analyze (or yarn analyze) to see a visual report of your JS bundles.

2.2 Common Performance Issues

  1. Large Page Bundles

    • Use dynamic imports for large components:

      import dynamic from 'next/dynamic';
      const HeavyComponent = dynamic(() => import('./HeavyComponent'));

    • Code splitting: Ensure each page or feature loads only what it needs.

    • Lazy load content not immediately visible (e.g., images or components below the fold).

  2. Slow Database Queries

    • Supabase Query Logging: Check logs in the Supabase dashboard to see slow queries.
    • Indexing: Ensure frequently queried columns have proper indexes in the PostgreSQL database.
    • Edge Functions: If your user base is global, consider using Supabase Edge Functions for geo-distributed operations.

3. Known Limitations

3.1 Development Environment

  • PostHog Events: Some advanced event features may require a production environment to work properly (e.g., user identification).
  • Stripe Webhooks: Locally, you may need a tool like ngrok or stripe listen CLI to receive webhook events.
  • Email Templates: Depending on your setup, you might need to restart the dev server if you make changes to compiled email templates.

3.2 Production Environment

  • Rate Limiting (Upstash)
    • Fine-tune configurations for critical endpoints:
      • Auth attempts
      • High-traffic API routes
      • Email sending or user invitation endpoints

4. Security Considerations

  • Validate User Input
    • Both client-side and server-side checks are essential (e.g., using Zod schemas or a server framework).
  • CORS & CSP
  • Dependencies
    • Keep libraries updated (e.g., npm audit fix or yarn upgrade) to patch vulnerabilities.
  • Secrets & Keys
    • Store keys securely in environment variables—never commit them to version control.
  • Database Access
    • Limit direct access to your production database. Use RLS (Row Level Security) in Supabase.

5. Getting Help

  • Existing GitHub Issues
    • Search for similar problems before opening a new one.
  • Error Logs
    • Check logs in Vercel (or your hosting provider), Supabase, or PostHog for detailed error messages.
  • When Reporting Issues

    • Include:

      Terminal window
      # Environment info
      node -v
      npm -v
      next -v
      # Error messages
      # Steps to reproduce
      # Relevant code snippets

    • This helps maintainers replicate and fix the problem faster.

Final Tips

  • Re-check your environment variables whenever something fails unexpectedly—often a missing or incorrect key is the culprit.
  • Keep an eye on logs (both app logs and external service logs) to spot errors early.
  • For deeper debugging, add console statements or breakpoints around problematic code.

Still Stuck? Don’t hesitate to reach out. The community is here to help you build a smooth, production-ready application.