Next.js Pages Router Legacy Migration Cursor Rules Template

Overview

This Cursor rules template describes a Next.js Pages Router legacy migration blueprint. It targets developers working on Next.js projects who want to migrate or maintain pages-based routing while applying Cursor AI rules for safe, auditable code generation. It includes a paste-ready .cursorrules block, stack-specific guidance, and strict constraints to reduce drift during migration.

When to Use These Cursor Rules

• When migrating a large Next.js project from Pages Router to App Router or hybrid routing, ensuring consistent patterns.
• When you want a repeatable baseline for code structure, linting, testing, and CI in migration scenarios.
• When you need to enforce security, data access patterns, and API route decisions during migration.
• When you want a documented, copyable configuration to share with teammates and automation tooling.

Copyable .cursorrules Configuration

// Cursor Rules Block – Next.js Pages Router Legacy Migration
Framework: Next.js
Framework Role & Context: You are Cursor AI, guiding a Next.js Pages Router legacy migration with a focus on safe, auditable changes and stack-specific constraints.
Code Style and Style Guides: TypeScript, ESLint (eslint-config-next), Prettier; enforce explicit types and consistent naming.
Architecture & Directory Rules: 
  - Keep /pages as the legacy routing layer; /src for components, hooks, and libs
  - Migrate to /app gradually when data fetching benefits from server components
  - Place API routes under /pages/api
  - Centralize shared logic in /src/lib and utilities in /src/utils
  - Do not place non-code assets in /pages; separate concerns
Authentication & Security Rules: 
  - Use HttpOnly cookies for sessions; guard API routes server-side
  - Validate tokens on server; never trust client state
  - Do not embed secrets in client code or config
Database and ORM patterns: 
  - Use PostgreSQL via node-postgres (pg) with parameterized queries
  - Use a dedicated /src/lib/db.ts module for DB access
  - Avoid ORMs that couple server and client code in Next.js paths
Testing & Linting Workflows: 
  - ESLint + TypeScript checks on commit; run npm test for unit tests
  - Jest + React Testing Library for components
  - Playwright for end-to-end migration tests
  - CI should run lint, type-check, unit, and integration tests
Prohibited Actions and Anti-patterns for the AI:
  - Do not mutate client state from server handlers
  - Do not bypass Next.js data-fetching rules or SSR semantics
  - Do not hard-code secrets or credentials
  - Do not mix App Router patterns into a Pages Router baseline

Recommended Project Structure

my-nextjs-project/
  pages/
    _app.tsx
    index.tsx
    api/
      health.ts
    legacy-migrations/
      migrate-use-cases.tsx
  src/
    components/
      SharedLayout.tsx
    hooks/
      useMigration.ts
    lib/
      db.ts
    styles/
      globals.css
  next.config.js
  tsconfig.json
  package.json

Core Engineering Principles

• Clarity and explicitness in migration steps; avoid implicit assumptions.
• Deterministic and idempotent changes; migrations can be reapplied safely.
• Strong type safety with TypeScript and runtime validation where appropriate.
• Security-first defaults; never expose sensitive data in client code.
• Clear separation of concerns between routing, data access, and UI.
• Documented rules for Cursor AI to reduce drift and ensure auditability.

Code Construction Rules

• Follow Next.js Pages Router conventions: place routes under /pages and API routes under /pages/api.
• Prefer server components for SSR data fetch when using Pages Router; avoid client-only data fetching on server path logic.
• Type all API responses; use explicit interfaces for request/response shapes.
• Centralize DB access in /src/lib/db.ts with prepared statements.
• Linting and formatting must pass on commit; rely on ESLint + Prettier with standard Next.js rules.
• Use .cursorrules to constrain the AI; avoid unsafe shortcuts or drift.

Security and Production Rules

• Store secrets in environment variables; never commit them to source control.
• Use HttpOnly secure cookies; set SameSite attributes appropriately.
• Validate all input on the server; implement rate limiting on API routes.
• Audit logs for migration steps; enable telemetry where appropriate without exposing PII.
• Ensure production builds run with performance optimizations and prevented SSR leaks.

Testing Checklist

• Unit tests for data access and utilities in /src/lib.
• Integration tests for API routes and data layer integration.
• Component tests for shared UI elements in pages migration context.
• End-to-end tests simulating migration scenarios (routing, data fetch, auth).
• CI validation: lint, type-check, unit and integration tests; ensure production-like environment.

Common Mistakes to Avoid

• Mixing App Router patterns into a Pages Router baseline; it will confuse data fetching semantics.
• Exposing secrets in client code or in public repos; use environment variables and secret management.
• Assuming SSR behavior without server component compatibility; mismatch leads to runtime errors.
• Skipping tests for migration steps; untested changes can regress production code.
• Failing to document migration steps for future developers; portability suffers.

FAQ

What is the purpose of this Cursor Rules Template?

This Cursor rules template provides a guided, copyable configuration for migrating a Next.js project using the Pages Router. It specifies architecture, security, and testing rules to keep migration aligned with Cursor AI practices and to avoid drift during development and deployment.

How do I use the .cursorrules block in a Next.js project?

Copy the code block into a dedicated .cursorrules file at the project root. Cursor AI will reference this block to constrain automated code generation, ensuring stack-specific patterns for Next.js Pages Router migrations.

What directory rules should I follow during migration?

Keep legacy pages under /pages during migration, place shared logic under /src, and only move to /app when data fetching benefits from server components. This separation reduces risk and improves auditability during migration.

What tests should accompany the migration?

Include unit tests for DB and utilities, integration tests for API routes, component tests for UI, and end-to-end tests simulating migration scenarios. CI should run lint, type checks, and full test suites before production deploys.

Can Cursor AI enforce security during migration?

Yes. The rules enforce secure data handling, token validation, HttpOnly cookies, and server-side validation. Do not rely on client-side checks for security-sensitive decisions; migrate gradually with auditable changes.

How should I structure code to minimize drift?

Adhere to a stable, well-documented project structure with explicit interfaces, central DB access, and clear routing boundaries. The Cursor Rules Template guides migration steps and prevents shortcuts that would introduce drift.