WordPress Headless GraphQL Next.js Cursor Rules Template

Overview

This Cursor Rules Template documents a WordPress headless GraphQL architecture using Next.js, enabling Cursor AI to generate consistent, safe code for data fetching, rendering, and SEO. It covers the WPGraphQL stack with Next.js frontend integration and defines rules to keep AI-assisted development predictable and auditable.

When to Use These Cursor Rules

• Building a WordPress headless site with GraphQL and Next.js where data contracts must be stable across releases.
• Standardizing GraphQL queries, fragments, and types to reduce duplication between client components.
• Incorporating Cursor AI into the development workflow to auto-suggest safe patterns and enforce architecture decisions.
• Enforcing security best practices around GraphQL endpoints and client-server boundaries.

Copyable .cursorrules Configuration

Framework Role & Context
- You are Cursor AI configured for WordPress Headless GraphQL with Next.js.
- You generate deterministic, testable templates and guardrails for this stack.

Code Style and Style Guides
- Use TypeScript with Next.js 14+ and React 18.
- Follow the project’s ESLint + Prettier rules and declare explicit GraphQL types.
- Prefer functional components, clear props typing, and accessible markup.

Architecture & Directory Rules
- Source lives under wordpress-nextjs-app in a monorepo layout:
  - src/pages, src/components, src/graphql, src/lib
  - public assets for images and static files
- Data access should live in src/graphql with clearly named queries/fragments
- Use getStaticProps / getServerSideProps as appropriate for ISR vs SSR

Authentication & Security Rules
- WPGraphQL endpoint protected behind environment-controlled URLs.
- Do not embed admin credentials in client code; use server-side fetch with tokens stored in env vars.
- Validate all GraphQL responses and implement field-level whitelisting for public data.

Database and ORM patterns
- WordPress uses its own database; interact via WPGraphQL; no ORM layer on client side.
- Cache GraphQL results on the client and at the edge where possible; respect WP caching headers.

Testing & Linting Workflows
- Unit tests for components and hooks; integration tests for GraphQL queries; e2e tests for critical flows.
- CI runs lint, type check, unit/integration tests, and a preview deployment.

Prohibited Actions and Anti-patterns
- Do not bypass WordPress nonce / capability checks.
- Do not call WP REST endpoints from Next.js if you intend GraphQL-first data retrieval.
- Do not hardcode secrets or credentials in client code.
- Do not assume GraphQL responses are always cached; validate in code.

Recommended Project Structure

wordpress-nextjs-app/
├─ next.config.js
├─ package.json
├─ tsconfig.json
├─ .env.local
├─ public/
├─ src/
│  ├─ pages/
│  │  ├─ index.tsx
│  │  └─ posts/[slug].tsx
│  ├─ components/
│  │  ├─ Header.tsx
│  │  └─ PostCard.tsx
│  ├─ graphql/
│  │  ├─ queries.ts
│  │  └─ fragments.ts
│  ├─ lib/
│  │  ├─ fetchGraphQL.ts
│  │  └─ api.ts
│  └─ hooks/
│     └─ useWPGraphQL.ts
├─ graphql-schema.generated.d.ts

Core Engineering Principles

• Explicit data contracts and stable interfaces across WPGraphQL queries and frontend components.
• Security by default: protect WPGraphQL endpoints, avoid leaking secrets, and validate responses.
• Type safety and explicit typing for all GraphQL data and Next.js props.
• Reproducible builds and verifiable tests for every change.
• Performance: memoize heavy queries, use ISR, and preload critical data.
• Observability: structured logging and error boundaries for data fetching layers.
• Cursor AI governance: auditable prompts, safe defaults, and explicit anti-patterns.

Code Construction Rules

• Fetch GraphQL data from a single WPGraphQL endpoint configured via environment variables.
• Define GraphQL queries in src/graphql with explicit types and fragments; generate TS types if possible.
• Use getStaticProps with revalidate for public blog-like content; use getServerSideProps for personalized data.
• Client components should not perform GraphQL requests directly; use a centralized data layer.
• All data fetching should handle GraphQL errors gracefully and provide fallback UI.
• Respect WordPress data schema; do not request non-existent fields.

Security and Production Rules

• Store secrets in environment variables; never in client code.
• Enable CSRF protection when using forms that trigger GraphQL mutations.
• Validate all inputs and sanitize data returned from WordPress before rendering.
• Use HTTPS, secure cookies, and proper CORS settings for GraphQL endpoints.

Testing Checklist

• Unit tests for React components and hooks that render GraphQL data.
• Integration tests for GraphQL queries against a test WPGraphQL instance.
• End-to-end tests that cover content rendering and navigation in Next.js.
• CI checks for linting, type checking, and test suites; ensure reproducible builds.

Common Mistakes to Avoid

• Relying on REST endpoints for data that is available via GraphQL; this duplicates data paths and introduces drift.
• Exposing secret tokens in client-side code or public repos.
• Assuming WordPress data structure is static; WordPress content evolves and can vary by site configuration.
• Ignoring WordPress nonce and capability checks where mutations are performed.

FAQ

What is a Cursor rules template?

A Cursor rules template defines a repeatable set of AI-guided rules for a specific stack. For WordPress headless GraphQL with Next.js, it codifies how Cursor AI should generate, validate, and optimize code, data fetching, and security practices for this integration.

How do I use this template in my project?

Copy the included .cursorrules block into your project root as .cursorrules and tailor environment values. Then run Cursor AI commands to scaffold or validate the WordPress GraphQL Next.js integration against the template rules.

What stack considerations are included?

The template focuses on WPGraphQL, WordPress as a headless CMS, and a Next.js frontend. It emphasizes GraphQL queries, type safety, ISR/SSR decisions, and secure data access patterns for WordPress data in Next.js.

What should I test to ensure correctness?

Test GraphQL query validity against WPGraphQL, component rendering for data-driven pages, and end‑to‑end flows from Next.js pages to WordPress data. Include security tests for mutations and proper handling of failed requests.

Can I extend this template to other stacks?

Yes, use it as a baseline. Replace WPGraphQL specifics with the equivalent data layer for another CMS, but preserve safe AI usage rules, data contracts, and testing practices described in the template.