Skip to content

AGENTS.md

Latest commit

 

History

History
232 lines (163 loc) · 7.33 KB

AGENTS.md

File metadata and controls

232 lines (163 loc) · 7.33 KB

AGENTS.md

This file provides guidance to AI coding assistants when working with code in this repository.

Project Overview

Directus is a real-time API and App dashboard for managing SQL database content. This is a pnpm monorepo containing:

  • /api - Node.js backend with REST & GraphQL APIs (Express.js, Knex.js)
  • /app - Vue 3 dashboard application (Vite, Pinia)
  • /sdk - TypeScript SDK for Directus API clients
  • /packages/* - 35+ shared packages (types, utils, storage drivers, extensions, etc.)

Requirements

  • Node.js 22
  • pnpm >=10 <11

Common Commands

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Build specific package
pnpm --filter @directus/api build

# Run development servers (API on :8055, App on :8080)
cd api && pnpm dev    # API with hot reload
cd app && pnpm dev    # App with Vite HMR

# Linting and formatting
pnpm lint             # ESLint
pnpm lint:style       # Stylelint for CSS/SCSS/Vue
pnpm format           # Prettier check

# Testing
pnpm test                           # Run all unit tests
pnpm --filter @directus/api test    # Test specific package
cd api && pnpm test:watch           # Watch mode in package
pnpm test:coverage                  # Coverage report

# Blackbox/E2E tests (requires building first)
pnpm test:blackbox
TEST_DB=postgres pnpm test:blackbox  # Against specific database

Architecture

API (/api/src)

  • controllers/ - REST API endpoint handlers (40+ controllers)
  • services/ - Business logic layer
  • database/ - Knex.js database utilities and migrations
  • middleware/ - Express middleware (auth, caching, rate limiting)
  • auth/ - Authentication providers (LDAP, SAML, OAuth, local)
  • extensions/ - Runtime extension loading
  • websocket/ - Real-time WebSocket support

App (/app/src)

  • components/ - 145+ Vue components
  • views/ - Page views
  • composables/ - 53+ Vue composables
  • stores/ - 24 Pinia stores
  • interfaces/ - 45+ field input types
  • displays/ - 21 field display renderers
  • layouts/ - 8 data layout views
  • operations/ - 18 flow operation types
  • panels/ - 14 dashboard panel types
  • modules/ - Feature modules

Key Shared Packages

  • @directus/types - Shared TypeScript types
  • @directus/utils - Shared utilities (node/browser/shared)
  • @directus/schema - Database schema utilities
  • @directus/extensions - Extension framework
  • @directus/storage - Abstract storage interface
  • @directus/storage-driver-* - Storage backends (S3, Azure, GCS, Local, etc.)

Code Style

  • TypeScript for all new code
  • ES modules (import/export syntax)
  • Prefer const over let, avoid var
  • Follow existing ESLint and Prettier configurations
  • Test files named *.test.ts, placed next to source files

Testing Conventions

import { describe, expect, test, vi } from 'vitest';

describe('function name', () => {
	test('should do something specific', () => {
		// Test implementation
	});
});

Database Support

Directus works with multiple SQL databases via Knex.js: PostgreSQL, MySQL, MariaDB, SQLite, MS SQL Server, OracleDB, CockroachDB.

Dependency Management

  • Use workspace:* for internal package dependencies
  • Use catalog: for external dependencies (versions defined in pnpm-workspace.yaml)
  • Add new shared dependencies to the catalog first

Changesets

All code changes require a changeset to document what changed for the release notes.

Creating a Changeset

pnpm changeset

This interactive command will:

  1. Ask which packages are affected
  2. Ask whether the change is a major, minor, or patch (see versioning guidance below)
  3. Prompt for a description of the change

Changeset Description Format

IMPORTANT: All changeset descriptions must be written in past tense, as they document changes that have already been made.

Examples:

  • ✅ "Added support for multi-provider AI"
  • ✅ "Fixed race condition in WebSocket connections"
  • ✅ "Replaced deprecated ldapjs with ldapts"
  • ❌ "Add support for multi-provider AI" (present tense - incorrect)
  • ❌ "Adding support for multi-provider AI" (present continuous - incorrect)

Versioning Guidelines

Follow semantic versioning:

  • Patch (0.0.x) - Bug fixes, dependency updates, internal improvements that don't affect the public API

    • Example: "Fixed validation error in date field"

  • Minor (0.x.0) - New features, enhancements to existing features, non-breaking changes

    • Example: "Added visual editing support to live preview"

  • Major (x.0.0) - Breaking changes that require user action or code updates

    • Example: "Removed deprecated GET /items endpoint"

Breaking Changes

When introducing a breaking change:

  1. Use major version bump
  2. In the changeset description, clearly document:
    • What changed (past tense)
    • Why it changed (if not obvious)
    • Migration steps or what users need to update

Example breaking change changeset:

---
'@directus/api': major
---

Removed support for Node.js 18. Directus now requires Node.js 20 or higher.

**Migration**: Update your Node.js installation to version 20 or higher before upgrading.

Pull Requests

Code Quality Requirements

IMPORTANT: Before creating a pull request, ensure all linters and formatters pass successfully. This is a mandatory requirement for all PRs.

Run these commands to verify code quality:

pnpm lint         # ESLint - checks JavaScript/TypeScript code
pnpm lint:style   # Stylelint - checks CSS/SCSS/Vue styles
pnpm format       # Prettier - checks code formatting

All three commands must pass with no errors before raising a PR. If any issues are found:

  1. Many issues can be auto-fixed:

    • pnpm lint --fix - Auto-fix ESLint issues
    • pnpm lint:style --fix - Auto-fix Stylelint issues
    • prettier --cache --write . - Auto-format with Prettier

  2. Review and manually fix any remaining issues that cannot be auto-fixed

PR Template

When creating a new pull request, always use the PR template located at .github/pull_request_template.md. The template includes:

  • Scope: List what changed in the PR
  • Potential Risks / Drawbacks: Document any risks or trade-offs
  • Tested Scenarios: Describe how the changes were tested
  • Review Notes / Questions: Highlight areas needing attention or questions for reviewers
  • Checklist: Confirm tests, documentation, and OpenAPI updates

Replace the placeholder "Lorem ipsum" content with actual details about your changes. Always reference the related issue at the bottom using Fixes #<num> format.

Handling Change Requests (AI Agents Only)

Note: This section applies only to AI coding agents. Human contributors should push commits directly to their PR branches as usual.

When triggering AI agents to resolve change requests or feedback on a pull request, they must create a Sub-PR (a new pull request that bases to the original PR branch) to address those changes instead of pushing commits directly to the existing PR branch.

Why Sub-PRs for AI Agents?

  • Allows reviewers to evaluate AI-generated changes in isolation
  • Maintains clear separation between original work and revisions
  • Enables easier rollback if AI-generated fixes introduce issues
  • Provides an additional review checkpoint for AI changes