Headless Commerce Admin Panel Cursor Rules Template

Overview

The Cursor rules configuration provides guardrails and actionable prompts for Cursor AI to help you build a complete headless commerce admin panel. This template targets a modern Next.js + TypeScript stack with Prisma as the ORM, PostgreSQL as the database, and NextAuth for authentication. It covers architecture decisions, coding conventions, security, and testing patterns required to manage products, orders, customers, discounts, and fulfillment workflows.

Direct answer: copy the large copyable .cursorrules block below and paste it into your project root. It will constrain Cursor AI behavior to your stack and ensure consistent, safe scaffolding and reviews.

When to Use These Cursor Rules

• Starting a Next.js + TypeScript admin panel for a headless commerce backend.
• Enforcing Prisma-based data access and safe query patterns to avoid N+1 and leakage of secrets.
• Defining authentication and authorization across admin routes with NextAuth and RBAC.
• Guiding architecture decisions for products, orders, customers, discounts, and fulfillment flows.
• Integrating testing, linting, and CI checks early in the development lifecycle.

Copyable .cursorrules Configuration

framework: Next.js, TypeScript, Prisma, PostgreSQL, NextAuth
role: Framework Engineer
context: You are Cursor AI tasked with scaffolding and guiding development of a headless commerce admin panel that manages products, orders, customers, discounts, and fulfillment workflows. Produce concrete examples, file paths, and safe defaults. Avoid unsafe actions.
code_style: TypeScript strict, ESLint, Prettier
architecture: Next.js app router; API routes in /api; server components when appropriate; Prisma as ORM; PostgreSQL database
directories:
  - apps/admin/src/app
  - apps/admin/src/components
  - prisma/
  - apps/admin/prisma
authentication: NextAuth; admin sessions; role-based access control; CSRF protection
database: Prisma models: Product, Order, Customer, Discount, Fulfillment; migrations; seed data; use transactions for discounts and fulfillment
security: env vars for secrets; avoid exposing secrets in code; use HTTP-only cookies; rotate keys; enforce RBAC
testing: Vitest unit tests; Playwright/integration tests; CI lint/type checks
anti_patterns:
  - Do not call the database from client components
  - Do not bypass authentication
  - Do not hardcode secrets
  - Do not bypass Prisma validations
  - Do not create N+1 query patterns

Recommended Project Structure

apps/
  admin/
    src/
      app/
        layout.tsx
        page.tsx
      components/
      styles/
    prisma/
      schema.prisma
    package.json
prisma/
  schema.prisma

Core Engineering Principles

• Clear separation of concerns across UI, API, and data layers.
• Security by default with RBAC, CSRF, and secrets management.
• Predictable, idempotent operations and auditable changes.
• Encourage testable, modular components and services.
• Reproducible builds, well-documented contracts, and code reviews.

Code Construction Rules

• Use Next.js app router with server components for data fetching and minimal client payloads.
• Define Prisma models for Product, Order, Customer, Discount, and Fulfillment; use migrations for schema changes.
• Validate inputs with a strict schema (eg, Zod) and enforce type-safe API contracts.
• All admin APIs require an authenticated session and role-based checks on user.role.
• Avoid client-side DB access; all data access must occur on the server or via API routes with proper authorization.

Security and Production Rules

• Store secrets in environment variables; do not commit them; rotate keys regularly.
• Use HTTP-only cookies for sessions; enable CSRF protection for API routes.
• Limit data exposure by scope and access level; implement RBAC checks on every request.
• Enforce input validation and output escaping to prevent injection attacks.
• Guard against mass assignment by using explicit DTOs for create/update operations.

Testing Checklist

• Unit tests for utility and data access layers (Prisma services).
• Integration tests for admin flows (products, orders, discounts, fulfillment).
• End-to-end tests for critical admin paths (login, CRUD operations, workflow triggers).
• Linting and type-checks run in CI; ensure no ts-check errors.
• Database migrations tested in a staging environment before production.

Common Mistakes to Avoid

• Not enforcing RBAC on admin endpoints or API routes.
• Embedding secrets in client code or repository files.
• Bypassing Prisma validations or introducing unsafe raw queries.
• Over-fetching data or creating N+1 queries due to naive data access patterns.
• Skipping tests or relying solely on manual QA for data workflows.

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: ERP Dashboard with Next.js, PostgreSQL, Prisma, Clerk and Shadcn UI
• Cursor Rules Template: Waste Management Operations Dashboard
• Cursor Rules Template for Fitness Trainer SaaS

FAQ

What stack does this Cursor Rules Template cover?

This template targets a Next.js + TypeScript stack with Prisma for PostgreSQL and NextAuth for authentication, tailored for a headless commerce admin panel. It emphasizes safe data access, RBAC, and clean API contracts. Cursor AI uses these rules to generate scaffold code, enforce conventions, and guide development in every layer.

How do I use the copyable .cursorrules block?

Copy the entire code block from the Copyable .cursorrules Configuration section and paste it into a file named .cursorrules at your project root. Cursor AI will then apply the rules to subsequent prompts, guiding architecture decisions, file layouts, and security practices for your stack.

Which directories are recommended in the project structure?

The recommended structure focuses on a Next.js app with a dedicated admin scope and Prisma integration. It includes apps/admin/src/app for pages and components, a prisma folder for the ORM schema, and a minimal server API surface. Avoid adding unrelated folders that do not contribute to the admin workflow.

How is authentication implemented for the admin panel?

Authentication is implemented with NextAuth, providing admin sessions and role-based access control. Server routes enforce session presence and check user roles to authorize actions such as product management, order operations, and fulfillment workflow updates.

How can I customize for my product models and fulfillment flows?

Customize the Prisma schema to reflect your product, order, customer, discount, and fulfillment attributes. Update admin pages to render your models and adjust API routes to align with your business logic. Cursor AI will guide these customizations, ensuring type safety, data integrity, and test coverage.