Supercharge Your Next.js + Supabase Development with Cursor Custom Modes

Sick of hunting through docs every time you forget how Next.js auth works with Supabase? Tired of making the same mistakes with those new async APIs in Next.js 15? There's a better way.

Cursor's custom modes let you create specialized AI assistants that actually understand your tech stack. I've been experimenting with this for Next.js and Supabase development, and it's a game-changer for productivity.

Let me show you how to set this up in 5 minutes.

What Are Cursor Custom Modes?

Custom modes let you create specialized versions of Cursor's AI assistant tailored to specific tasks or frameworks. Think of them as "personalities" for your AI that know exactly how to help with particular workflows.

Unlike the default assistant, custom modes can be loaded with specialized knowledge about framework-specific patterns, breaking changes, and best practices that general AI models might miss.

Docs - https://docs.cursor.com/chat/custom-modes

You can quickly switch between modes from the Cursor sidebar

Why I Created a Next.js + Supabase Mode

Next.js 15 dropped with some significant breaking changes (like those mandatory async patterns for cookies and headers), and keeping track of all the best practices for Supabase integration was becoming a pain.

I found myself repeatedly:

• Checking docs for the correct Supabase SSR auth patterns
• Forgetting the new async/await patterns for cookies()
• Making mistakes with real-time subscriptions
• Struggling to remember Row Level Security configuration

Rather than bookmarking a dozen documentation pages, I decided to encode all this knowledge into a custom AI mode.

Setting Up Your Own Next.js + Supabase Mode

Here's how to do it yourself:

1. Enable custom modes in Cursor: Settings → Features → Chat → Custom modes

2. Create a new mode: Click the mode selector in chat and choose "Add custom mode"

3. Configure the basics:

   • Name: "Next.js + Supabase"
   • Icon: 🔷 (or whatever you prefer)
   • Shortcut: Alt+S (customize as needed)

4. Choose relevant tools:

   • Codebase search
   • Edit
   • Terminal (for running Supabase commands)
   • Web search (for checking latest updates)

5. Add specialized instructions:

   You are an expert in Next.js 15+ and Supabase integration. Help me write code that follows current best practices, especially:
   
   1. Always use async patterns for Next.js request APIs:
      - await cookies()
      - await headers()
   
   2. Implement proper Supabase auth with SSR:
      - Use createServerClient from @supabase/ssr
      - Handle cookie management correctly
   
   3. Use appropriate caching strategies:
      - GET routes are no longer cached by default
      - Explicitly set dynamic = 'force-static' when needed
   
   4. Properly separate client and server components with Supabase
   
   5. Implement secure Row Level Security policies
   
   6. Ensure real-time subscriptions are properly cleaned up
   
   When helping, prioritize current patterns over older approaches and warn me about common pitfalls.
   

6. Save your mode

Now you can instantly switch to this mode whenever you're working on Next.js and Supabase code!

See It In Action

Here's a quick example of how this custom mode helps in real situations:

Without custom mode:

Me: How do I set up Supabase auth in Next.js?

AI: You can use the createClient function from Supabase to set up authentication...
[Provides general information but misses critical Next.js 15 SSR patterns]

With custom mode:

Me: How do I set up Supabase auth in Next.js?

AI: For Next.js 15+, you'll need to create a server-side client using the async cookies() API:

```typescript
// utils/supabase/server.ts
import { createServerClient } from "@supabase/ssr";
import { cookies } from "next/headers";

export const createClient = async () => {
  const cookieStore = await cookies(); // Note: async/await required in Next.js 15
  
  return createServerClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
    {
      cookies: {
        getAll() {
          return cookieStore.getAll();
        },
        // ... other handlers
      },
    }
  );
};

Notice I'm using the async pattern with cookies() which is required in Next.js 15. This prevents hydration errors and future deprecation warnings.

The custom mode immediately provides:
- Current, framework-specific patterns
- Awareness of breaking changes
- Explanations of why certain approaches are needed

## More Practical Custom Mode Ideas

This approach works for any tech stack or workflow. Here are some other custom modes I've found useful:

- **CSS Wizard**: Specializes in modern CSS techniques, animations, and responsive design
- **Performance Optimizer**: Focuses on identifying and fixing performance bottlenecks
- **Accessibility Expert**: Ensures your code follows WCAG guidelines and best practices
- **TDD Coach**: Helps you write tests first, then implementation
- **React Native Helper**: Specializes in mobile-specific patterns and APIs

## The Real Benefits

Custom modes have saved me countless hours by:

1. **Eliminating context switching** between coding and documentation
2. **Preventing common errors** before they happen
3. **Keeping the entire team aligned** on current best practices
4. **Smoothing onboarding** for new team members
5. **Adapting instantly** when frameworks update

## Try It Today

Setting up custom modes takes just a few minutes but saves hours of debugging and documentation hunting. The Next.js + Supabase example is just the start—think about your own workflows and how specialized AI assistance could make them smoother.

If you're using Cursor, enable custom modes today and start experimenting. Your future self will thank you when you're not hunting through docs for the tenth time to remember that one specific pattern.