Skip to content

AGENTS.md

Latest commit

 

History

History
166 lines (132 loc) · 6 KB

AGENTS.md

File metadata and controls

166 lines (132 loc) · 6 KB

Nuxtype Agent Guide

This guide orients coding agents for the Nuxtype monorepo. It consolidates build/lint/test commands, repo conventions, and the Copilot instructions that apply to this workspace.

No Cursor rules were found (.cursor/rules/ or .cursorrules).

Repository Overview

  • Monorepo managed by pnpm workspaces.
  • Frontend: Nuxt 4 + Vue 3 app in apps/web.
  • Collaboration server: Hocuspocus WebSocket in apps/collab.
  • Shared schema/types: packages/shared.
  • Database: PostgreSQL with Drizzle ORM.

Repository Layout

  • apps/web/app/ Nuxt app source (pages, layouts, components, composables).
  • apps/web/server/ Nuxt server routes (auto-discovered).
  • apps/web/app/components/ui/ Shadcn Vue components.
  • apps/web/app/components/editor/ Tiptap editor and collab UI.
  • apps/collab/src/index.ts Hocuspocus WebSocket server entry.
  • packages/shared/src/schema.ts Drizzle schema (source of truth).
  • packages/shared/src/types.ts Shared API types and domain models.
  • packages/shared/src/zod-schema.ts Zod validators for inputs.
  • .github/copilot-instructions.md Required coding instructions.

Data Flow (High Level)

  1. User edits in web app update local Y.js document state.
  2. Changes broadcast to collab server and sync across clients.
  3. Persistent updates stored in PostgreSQL via Drizzle.
  4. Schema changes in packages/shared flow to both apps.

Commands

Root commands:

pnpm install
pnpm dev           # web app (http://localhost:3000)
pnpm dev:collab    # collab server (ws://localhost:1234)
pnpm build
pnpm lint
pnpm lint:fix
pnpm run db:generate
pnpm run db:push
pnpm run db:studio

Package-scoped:

pnpm --filter web dev
pnpm --filter web build
pnpm --filter collab dev
pnpm --filter collab build

Testing

  • No test scripts are wired yet in package.json.
  • No *.test.* or *.spec.* files exist currently. Vitest (if/when added to web):
pnpm --filter web vitest
pnpm --filter web vitest run
pnpm --filter web vitest run path/to/test.spec.ts
pnpm --filter web vitest run -t "test name"

Development Notes

  • Web and collab dev servers are separate processes.
  • Collab dev/start use dotenv-cli with root .env.
  • After schema changes, run pnpm run db:push before servers.
  • Shared package uses workspace:*; no publish step required.
  • Drizzle Studio is available via pnpm run db:studio.
  • Nuxt devtools are enabled in apps/web/nuxt.config.ts.
  • Hocuspocus logs are visible in the collab server terminal.
  • Prefer @nuxtype/shared imports over duplicate types.
  • Avoid adding new tooling unless required for the task.

Copilot Instructions (Required)

These are taken from .github/copilot-instructions.md and must be followed:

  • Schema source of truth: packages/shared/src/schema.ts.
  • Shared types live in packages/shared/src/types.ts.
  • Document content stored as Tiptap JSON (JSONB in Postgres).
  • API responses use ApiResponse<T> with success, data, error.
  • Nuxt server routes are under apps/web/server/ (auto-discovered).
  • UI components are in apps/web/components/, styling uses Tailwind + Shadcn.
  • Use clsx for conditional class names.
  • After schema changes, run pnpm run db:push.
  • Dev servers for web and collab are separate processes.
  • Env vars required: DATABASE_URL, JWT_SECRET, NUXT_PUBLIC_WS_URL.

Code Style and Conventions

  • Linting/formatting: ESLint with @antfu/eslint-config, Vue + TS + formatters.
  • Linting/formatting: lint-staged runs eslint --fix on *.{js,ts,vue}.
  • Linting/formatting: double quotes enforced (style/quotes).
  • Linting/formatting: any warned; console warned.
  • Imports: prefer explicit named imports; use type-only imports for types.
  • Imports: group by source (builtin, external, internal, relative).
  • Imports: use @nuxtype/shared for shared types and schema.
  • TypeScript: strict mode expected; avoid implicit any and casting.
  • TypeScript: reuse packages/shared/src/types.ts for API contracts.
  • Vue/Nuxt: components in apps/web/app/components/ and apps/web/components/.
  • Vue/Nuxt: PascalCase SFC names; single-word names are allowed.
  • Vue/Nuxt: avoid process.env outside nuxt.config.* (use runtimeConfig).
  • Vue/Nuxt: server routes go under apps/web/server/.
  • Naming: components PascalCase, composables useXxx, functions camelCase.
  • Naming: types/interfaces PascalCase; avoid unclear abbreviations.
  • Error handling: always return ApiResponse<T> with success/data/error.
  • Error handling: validate inputs with Zod; avoid leaking secrets.
  • Database: schema source in packages/shared/src/schema.ts.
  • Database: run pnpm run db:push after schema changes.
  • Database: Tiptap editor state stored directly as JSONB.
  • Collab: server in apps/collab/src/index.ts, uses Hocuspocus + Y.js.
  • Collab: keep auth aligned with JWT_SECRET used by web app.
  • UI: Tailwind + Shadcn Vue are standard; use clsx for conditional classes.

API and Auth Patterns

  • API responses must be ApiResponse<T> with success, data, error.
  • Validate inputs with Zod at route boundaries.
  • Avoid leaking secrets; sanitize error messages.
  • JWT auth uses JWT_SECRET; keep collab auth aligned with web.

Nuxt Runtime Config

  • Use runtimeConfig for server-only secrets.
  • Use runtimeConfig.public for client-exposed values.
  • process.env is allowed only in nuxt.config.*.

Environment Variables

Required for local development:

  • DATABASE_URL
  • JWT_SECRET
  • NUXT_PUBLIC_WS_URL Optional for uploads:
  • R2_ACCESS_KEY_ID
  • R2_SECRET_ACCESS_KEY
  • R2_BUCKET_NAME
  • R2_ENDPOINT
  • R2_PUBLIC_DOMAIN

Agent Workflow Tips

  • Prefer changes in shared package for cross-app types/schema.
  • Start web and collab dev servers in separate terminals.
  • Avoid introducing new tooling unless a task requires it.
  • Keep changes aligned with existing folder structure.

If Unsure

  • Schema questions: check packages/shared/src/schema.ts.
  • Types: check packages/shared/src/types.ts.
  • API: check apps/web/server/ routes.
  • UI: check apps/web/components/ and Tailwind utility patterns.