Cursor Rules Template: Node.js + Express + PostgreSQL for Carbon SaaS

Overview

Cursor rules configuration for a Node.js + Express backend with PostgreSQL, tailored to a carbon accounting SaaS workflow. It covers company data imports, emissions factors management, emissions reporting, and reduction plan features. Direct answer: paste the included .cursorrules block into your project root to enforce stack-specific engineering practices for secure data handling, accurate calculations, and maintainable architecture.

The rules template is designed for Cursor AI to assist in building a scalable SaaS that ingests company data, applies emissions factors, generates reports, and supports reduction planning. It enforces a disciplined project structure, robust authentication, and repeatable testing patterns to reduce drift when integrating data imports and factor libraries.

When to Use These Cursor Rules

• Starting a carbon accounting SaaS using Node.js/Express and PostgreSQL where data integrity is critical.
• Implementing data import pipelines for CSV/JSON company data with validation and schema enforcement.
• Maintaining emissions factors catalogs and ensuring deterministic calculations for reports.
• Building REST API routes for reports and reduction plans with proper authentication and audit trails.
• Setting up CI pipelines with tests, linting, and type-checking to prevent regression during factor updates.

Copyable .cursorrules Configuration

# Cursor Rules Template for Node.js + Express + PostgreSQL Carbon SaaS
# Framework Role & Context
Framework_Role: "You are Cursor AI acting as a software engineering assistant for a Node.js + Express backend with a PostgreSQL database, focused on carbon accounting SaaS workflows."
Framework_Context: "Your guidance enables company data imports, emissions factors management, emissions reporting, and reduction plans with a secure, testable, scalable architecture."

# Code Style and Style Guides
Code_Style: "TypeScript enabled, ESLint + Prettier, consistent naming, strict type checks, and explicit any avoidance."
Lint_Framework: "ESLint with recommended + style guide rules; Prettier for formatting; tsconfig strict types."
File_Formats: ".ts, .tsx, .js, .json, .sql"

# Architecture & Directory Rules
Project_Root: "."
Backend_Dir: "src/backend"
Frontend_Dir: "src/frontend"
DB_Dir: "src/backend/db"
APIs: "/src/backend/routes/**.ts"
Services: "/src/backend/services/**.ts"
Models: "/src/backend/models/**.ts"
Migrations: "/src/backend/db/migrations/**.sql"
Tests: "/tests/**"

# Authentication & Security Rules
Auth_Rules: "JWT (HS256) for API auth; HttpOnly cookies for sessionless flows; Refresh tokens with rotation; Secrets in env vars; Always validate inputs; CSRF protection for cookie-based auth."
Password_Strategy: "Bcrypt with 12+ salt rounds; store only hashes; no plaintext credentials in logs."
OAuth_Scopes: "If used, restrict scopes to read/write as appropriate; never expose admin endpoints publicly."

# Database and ORM patterns
DB_Engine: "PostgreSQL"
ORM_Rules: "Use parameterized queries via pg library; avoid string concatenation; use a simple data mapper layer; migrations in sql format; no auto migrations at runtime."
Migration_Strategy: "Explicit migrations with versioning; run via CI; seeds for dev/test environments."
Data_Validation: "Server-side validation with Joi/Zod; strict typing in TS models; sanitize before persistence."

# Testing & Linting Workflows
Unit_Tests: "Jest + ts-jest for TS types; test isolated services and utils."
Integration_Tests: "Supertest for API endpoints; test data import pipeline with sample CSV/JSON." 
End_to_End: "Optional, if required; use Cypress or Playwright for UI flows in frontend."
CI_Workflows: "GitHub Actions: lint, type-check, unit tests, integration tests on push; enforce status checks."

# Prohibited Actions and Anti-patterns
Prohibited_Actions: "Do not concatenate SQL; Do not embed credentials in code; Do not bypass input validation; Do not trust client-side data for security decisions; Do not use admin endpoints without proper auth."
Anti_Patterns: "Client-side only validation; Magic numbers for IDs; Global state for request-scoped data; Lock-in to a single ORM without migration support."

# Implementation Notes
Note: Ensure environment-specific configs are loaded securely; use migrations for schema changes; isolate data imports from production data; log operations with minimal PII.

Recommended Project Structure

project-root/
  src/
    backend/
      controllers/
      routes/
      services/
      models/
      middleware/
      db/
        migrations/
        seeds/
      config/
      utils/
    frontend/
      pages/
      components/
      hooks/
      styles/
  tests/
    unit/
    integration/
  .env.example
  package.json
  tsconfig.json
  next.config.js

Core Engineering Principles

• Explicitness over magic: all data flows and schema changes are explicit and auditable.
• Security by default: authentication, authorization, input validation, and least privilege are enforced at API boundaries.
• Strong typing: TypeScript types prevent runtime errors and improve maintainability.
• Data integrity: strict validation for imports and emissions calculations; no silent data corruption.
• Test-driven risk management: unit, integration, and CI checks catch regressions early.

Code Construction Rules

• Backend API routes use Express with TS types; controllers call services; services interact with a repository layer that uses parameterized queries.
• All data imports validate schema; mappings are explicit; invalid rows are logged and skipped with a summary report.
• Emissions factors are versioned; each calculation uses a factor_version_id to ensure reproducibility.
• Reports are generated via server-side calculations, not client-side, to ensure data privacy and accuracy.
• Environment variables provide DB credentials, JWT secrets, and API keys; never commit secrets.

Security and Production Rules

• Use TLS for all endpoints; enforce secure cookies; CSRF protection for state-changing endpoints.
• Limit API rate per IP; implement per-user quotas for report generation to prevent abuse.
• Audit logging for data imports, factor changes, and report generations; store logs in a separate schema or service.
• Isolate production data from development/test data; use dedicated environments and secret management.
• Regular dependency audits and vulnerability scanning; pin exact versions for critical libraries.

Testing Checklist

• Unit tests for data validators, converters, and utilities with deterministic fixtures.
• Integration tests for API endpoints, including data import routes and report generation flows.
• Migration tests to verify schema changes do not break existing data; smoke tests in CI.
• Linting and type-checking in CI; ensure no TS errors; enforce formatting via Prettier.
• Performance tests for large CSV imports and factor lookups; monitor query plans and indices.

Common Mistakes to Avoid

• Relying on client-side validation to secure endpoints; always validate server-side.
• Embedding credentials or secrets in code or logs; use environment-based configuration.
• Non-parameterized SQL leading to SQL injection; always use parameterized queries.
• Skipping migrations in production; rely on strict, versioned migrations for schema changes.
• Coupling import logic to a single data source; design adapters for CSV/JSON imports to decouple formats.

Related Cursor rules templates

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

• Cursor Rules Template: Construction Project Management Stack
• Cursor Rules Template: Cash Flow SaaS with Bank Imports, Invoices, and AI Predictions
• Field Sales Cursor Rules Template: Location Check-ins, Visits, Notes, Tasks, and Manager Analytics
• Cursor Rules Template: Node.js Express PostgreSQL Kanban SaaS

FAQ

What stack does this Cursor Rules Template target?

This template targets a Node.js + Express backend with PostgreSQL, paired with a Next.js/React frontend for a carbon accounting SaaS. It includes guidelines for data imports, emissions factors, reporting, and reduction plans, all enforced by Cursor AI rules to prevent drift.

Can I adapt this template to other runtimes?

Yes. The rules are stack-specific but can be adapted for similar stacks (e.g., NestJS with PostgreSQL or a serverless Node API). Replace backend notes and DB patterns with equivalents in the target runtime, keeping the same security and testing discipline.

How should company data imports be handled?

Imports must validate schema (CSV/JSON), map fields deterministically, and run through a staging surface before persisting to the production database. Record import metadata for traceability and rollback if needed.

How are emissions factors versioned?

Emissions factors live in a versioned catalog. Each calculation ties to a factor_version_id to ensure reproducibility across reports and audits, with a change log for factor updates.

What testing should I prioritize for this stack?

Unit tests for validation utilities, integration tests for API endpoints including data import and reporting, and migration tests to ensure schema changes are safe. Include CI checks for linting, type-safety, and test coverage.

Do not forget security checks during development?

Always enforce authentication, authorize access by role, protect cookies, rotate tokens, validate inputs, and log sensitive events with redaction. Do not expose secrets in logs or frontend code.