grandstack
docs / grandstack-web / Agents

AGENTS.md: guide for coding agents

React + Vite client for grandstack-server: faceted movie and people search, compare, graph views, and create/edit/delete. urql with typed operations from GraphQL Code Generator. Read docs/architecture.md first, then docs/recipes.md for the change you are making.

Commands

  • Whole stack: cd ../grandstack && docker compose up --build (web http://localhost:3000, GraphQL http://localhost:4000/graphql).
  • Dev server: npm ci && npm run dev (server must be running; VITE_GRAPHQL_URL changes the endpoint).
  • After changing any GraphQL document or the server schema: npm run codegen (needs the server running), commit src/graphql/generated/.
  • Before you finish: npm run typecheck && npm test && npm run docs:check. With a freshly seeded stack also npm run e2e.

Rules that are easy to get wrong

  • Write operations with graphql() from src/graphql/generated; never edit that folder by hand. Operation names must be unique across the app.
  • Filters live in the URL (docs/architecture.md). Text inputs that write to the URL need local state plus a debounce.
  • Clearing filters: add new fields to emptyFilters with an explicit undefined, or { ...filters, ...emptyFilters } will not clear them.
  • Relationship edits are diffs (buildUpdateInput in src/forms/model.ts), never “disconnect all, then connect”. Scalar updates are { set: value }.
  • Title search is case-sensitive in the API; buildWhere matches several casings.
  • Do not add @neo4j-ndl/* (GPL-3.0; this repo is Apache-2.0). The Needle-style tokens are approximations. See docs/customising.md.
  • VITE_GRAPHQL_URL is fixed at build time and must be reachable from the browser. The compare tray is hidden on form pages on purpose.
  • No authentication: edit screens show a banner and deletes ask for confirmation. Do not expose the app publicly.
  • Keep graphql on 16.x to match the server. Pin exact dependency versions.
  • New code files need the copyright header (two lines: Copyright (c) "Neo4j" and Neo4j Sweden AB [http://neo4j.com], in the file’s comment syntax). Run node ../grandstack/scripts/add-headers.mjs (or node ../.github/scripts/headers.mjs --root . for one repository) to add it; --check lists what is missing. Generated files are exempt.

Keep the docs true

When you change behaviour, update the matching doc in the same change (routes and folder map in docs/architecture.md, feature behaviour in docs/features.md, new gotchas here or in docs/testing.md). npm run docs:check fails on a broken relative link. Diagrams are SVG files in docs/diagrams/: edit the SVG and its numbered legend together when behaviour changes; npm run docs:check fails on a missing alt text, unsafe SVG content, or legend numbers that do not match the callouts drawn.

  • Releases use the release-cut workflow (Actions tab), which sets the version in every package.json, tags and publishes. Do not bump versions or push tags by hand; see grandstack/docs/releasing.md.

Source: grandstack-web/AGENTS.md (this page is a copy; edit it in the repository)