cursorrules

EloquentJS — Cursor Rules

Project Tech Stack

• Runtime: Node.js (ESM, "type": "module")
• ORM: EloquentJS (@eloquentjs/core)
• Database: PostgreSQL via @eloquentjs/pgsql (or MongoDB via @eloquentjs/mongodb)
• Validation: @eloquentjs/validator
• REST API: @eloquentjs/api (Express/Fastify)
• GraphQL: @eloquentjs/graphql
• Realtime: @eloquentjs/realtime

Code Style Rules

Imports

• Always use ESM imports (import, not require)
• Import from package names, not file paths for EloquentJS packages
• Default export for Model classes; named exports for utilities

// ✅ Correct
import { Model } from '@eloquentjs/core'
import { v }     from '@eloquentjs/validator'
import User      from './models/User.js'

// ❌ Wrong
const { Model } = require('@eloquentjs/core')

Model files

• One model per file in app/models/
• PascalCase filename matching class name
• Always declare static table, static fillable, and static casts
• Soft deletes: add static softDeletes = true (never delete rows in user-facing apps)

// ✅ Standard model structure
export default class Product extends Model {
  static table    = 'products'
  static fillable = ['name', 'price', 'sku', 'category_id']
  static hidden   = []
  static casts    = { price: 'decimal:2', in_stock: 'boolean', tags: 'array' }
  static softDeletes = true

  category() { return this.belongsTo(Category) }
  static scopeInStock(qb) { return qb.where('in_stock', true) }
}

Querying

• Always await query results
• Use .with() for any relations accessed after fetching
• Use findOrFail() when record absence should be an error
• Use paginate() for list endpoints (never .all() without limit in production)

// ✅
const product = await Product.findOrFail(id)
const page    = await Product.inStock().with('category').paginate(page, 20)

// ❌
const product = Product.find(id)     // missing await
const all     = await Product.all()  // dangerous in production

Validation

• Always validate before create() or update()
• Use @eloquentjs/validator fluent schema for complex validation
• Use schema.parseAsync() when rules include unique() or exists()