Next.js SaaS Cursor Rules Template

Overview

Cursor rules configuration for a production-grade ecommerce SaaS stack is designed to guide Cursor AI through architecture, security, and implementation specifics for Next.js with Stripe, Supabase, Clerk, and Shadcn UI. It provides a direct, copyable .cursorrules block and stack-focused guidance to speed up engineering and maintain quality.

Direct answer: This template sets the expectations, constraints, and actionable steps needed to build, deploy, and operate a Next.js based ecommerce SaaS using the chosen stack, with a safe AI workflow and reproducible project structure.

When to Use These Cursor Rules

• Starting a new Next.js ecommerce SaaS project and aligning with Stripe billing.
• Integrating Clerk for authentication and user management.
• Setting Supabase as the primary data layer with secure row level security.
• Using Shadcn UI for consistent design and component usage.
• Guiding Cursor AI interactions for architecture, coding standards, and security.

Copyable .cursorrules Configuration

Framework Role & Context
Role: Cursor AI Developer for Next.js SaaS with Stripe, Supabase, Clerk, and Shadcn UI
Context: You will generate a copyable .cursorrules configuration block for a production-grade ecommerce SaaS. Enforce best practices and architecture constraints.

Code Style and Style Guides
Language: TypeScript
Framework: Next.js
Styling: Tailwind CSS with Shadcn UI components
Linting: ESLint + Prettier; enforce consistent types
Testing: Vitest for unit, Playwright for end-to-end

Architecture & Directory Rules
Use Next.js app router, server components where appropriate
Directory layout: apps/web, apps/api, libs/ui, components, public, db/migrations
Avoid global state in client components; lift to hooks in server components when possible

Authentication & Security Rules
Auth with Clerk; enforce server-side checks for protected endpoints
Do not expose secret keys on the client; use environment variables and edge functions
Validate user roles before privileged actions

Database and ORM patterns
Supabase Postgres as the primary database; use supabase-js on the frontend and server-side clients on API routes
Prefer Supabase RPCs for complex operations; avoid client-side sensitive data

Testing & Linting Workflows
Unit: Vitest; API tests with supertest if used; E2E: Playwright
CI: run lint, type checks, tests on PRs, and a deployment dry-run

Prohibited Actions and Anti-patterns
Do not bypass Clerk authentication; never trust client-side authorization
Do not embed secret keys in client code
Do not perform privileged data mutations from client components without server enforcement

Recommended Project Structure

apps/
  web/
    app/
      layout.tsx
      page.tsx
    components/
    lib/
    services/
      stripe.ts
      supabase.ts
      clerk.ts
    styles/
  api/
    stripe/
    clerk/
    supabase/
 db/
  migrations/
  seed/
 packages/
  ui/
    components/
    themes/
 public/

Core Engineering Principles

• Clear separation of concerns across frontend, backend, and data layers.
• Secure by default: never trust the client and enforce server-side authorization.
• Idempotent and deterministic data operations with explicit error handling.
• Lean, well-typed code with strong test coverage and CI validation.
• Observability: structured logging, tracing, and metrics from production services.

Code Construction Rules

• Use TypeScript for all new code; define precise types for API boundaries.
• Leverage Next.js server components for data fetching and security checks.
• Abstract external service calls behind service modules (stripe, supabase, clerk).
• Ensure all API routes require proper authentication and authorization.
• Follow a predictable file naming convention and a single source of truth for configuration.

Security and Production Rules

• Store API keys and secrets in environment variables; never commit them.
• Validate Stripe webhooks with signatures; verify event authenticity before processing.
• Enable CSRF protection for state-changing endpoints and use same-site cookies when applicable.
• Implement input validation and server-side validation for all user inputs.
• Set up rate limiting and proper error handling to avoid leaking sensitive information.

Testing Checklist

• Unit tests for utilities and components with Vitest.
• API tests for Next.js API routes or server actions with mocks for Stripe and Clerk.
• End-to-end tests covering signup, plan purchase, and checkout flows with Playwright.
• CI: lint, type check, tests on PRs; perform a dry-run deployment in staging.

Common Mistakes to Avoid

• Not enforcing server-side authorization for sensitive actions.
• Hardcoding credentials or using client-side secrets.
• Skipping Stripe webhooks verification and idempotency handling.
• Overloading client components with business logic that should run on the server.

Related Cursor rules templates

Explore adjacent Cursor rules templates for similar stacks, workflows, and production constraints.

• Cursor Rules Template: Django Subscription Box Platform
• Cursor Rules Template — Real Estate Dashboard with Cash Flow, ROI, and Analytics
• Cursor Rules Template: Next.js Personal Brand Website Generator
• Cursor Rules Template: ERP Dashboard with Next.js, PostgreSQL, Prisma, Clerk and Shadcn UI

FAQ

What is a Cursor Rules Template for a Next.js SaaS?

A Cursor Rules Template provides a structured, copyable .cursorrules block and stack‑specific guidance to help AI produce reliable code and architecture for a Next.js based ecommerce SaaS with Stripe, Supabase, Clerk, and Shadcn UI.

Which stack components are covered by this template?

The template targets Next.js, Stripe for payments, Supabase for data, Clerk for authentication, and Shadcn UI for design components, with Cursor AI guiding implementation, testing, and security.

How do I use the copyable .cursorrules block?

Copy the code within the pre block and paste it into a file named .cursorrules at your project root. It instructs Cursor AI to follow architecture, coding standards, and security patterns for this stack.

What security practices are emphasized?

Key practices include using environment variables for secrets, verifying Stripe webhooks, enforcing server-side authorization, and avoiding client-exposed keys or bypassing Clerk authentication.

How should I structure my Next.js SaaS project?

Follow a Next.js app router layout with server components where possible, organized into apps/web, a separate API layer for Stripe/Clerk, and a shared library for UI components from Shadcn UI.

Can I customize the template for another stack?

Yes. Replace the stack details in the Cursor rules block while preserving the required sections (framework, architecture, testing, security) and adjust the project structure to fit the new stack.