| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 1 | 25 | 0% |
| Commands | 0 | 0 | 38 | 0% |
| Section tags | 1 | 0 | 9 | 10% |
What each file covers
Sections
0 shared · 1 only in A · 25 only in B- − Frontend features — agent guide
- + AGENTS.md
- + Project Overview
- + Principles
- + Comments
- + Human Review Gates
- + Commands
- + Build & Run
- + Test
- + Backend
- + Frontend
- + E2E
- + Lint & Format
- + Code Generation
- + Dev Environment
- + Architecture
- + Backend (`pkg/`)
- + Frontend (`public/app/`)
- + Shared Packages (`packages/`)
- + Backend Apps (`apps/`)
- + Plugin Workspaces
- + Key Notes
- + Cursor Cloud specific instructions
- + Prerequisites
- + Running services
- + Testing gotchas
Commands
0 shared · 0 only in A · 38 only in B- + make run
- + make build-backend
- + yarn start
- + yarn build
- + go test -run TestName ./pkg/services/myservice/
- + make test-go-unit
- + make test-go-integration
- + yarn test path/to/file
- + yarn test -t "pattern"
- + yarn test -u
- + yarn e2e:playwright path/to/test.spec.ts
- + make lint-go
- + yarn lint
- + yarn lint:fix
- + yarn prettier:write
- + yarn typecheck
- + make gen-go
- + make gen-cue
- + make gen-apps
- + make swagger-gen
- + make gen-feature-toggles
- + make i18n-extract
- + make update-workspace
- + yarn install --immutable
- + make devenv sources=influxdb
- + make devenv-down
- + make lefthook-install
- + git push
- + yarn workspace @grafana-plugins/<name> dev
- + go.work
- + make devenv sources=postgres_tests,mysql_tests
- + make test-go-integration-postgres
- + node
- + yarn
- + jest
- + go.mod
- + yarn test
- + yarn jest --no-watch
Section tags
1 shared · 0 only in A · 9 only in B- + setup
- + build
- + test
- + lint-format
- + architecture
- + testing-strategy
- + git-pr
- + dependencies
- + docs
- agent-behaviour
Line diff
grafana/grafana · public/app/features/AGENTS.md
@@ −1 @@
1# Frontend features — agent guide
2
3This tree contains Grafana visualization code (canvas, geo, dimensions, table, and more).
4When you are adding or changing visualization code or its tests here, invoke these skills
5with the Skill tool — each skill's own description states exactly when it applies:
6
7- **`panel-testing-strategy`** — how visualization unit + E2E tests should be written:
8 assert real behavior (not existence), the canvas draw-call snapshot harness, honest
9 test descriptions, and the anti-flake rules.
10- **`add-e2e-selectors`** — add versioned `@grafana/e2e-selectors` and wire
11 `data-testid` into JSX when making UI testable.
12
grafana/grafana · AGENTS.md
@@ +1 @@
1# AGENTS.md
2
3<!-- version: 2.0.0 -->
4
5This file provides guidance to AI agents when working with code in the Grafana repository.
6
7**Directory-scoped agent files exist for specialized areas — read them when working in those directories:**
8
9- `docs/AGENTS.md` — Documentation style guide (for work under `docs/`)
10- `public/app/features/alerting/unified/AGENTS.md` — Alerting squad patterns
11- `pkg/storage/unified/AGENTS.md` — Unified storage/search compatibility rules (for work under `pkg/storage/unified/`)
12- `public/app/core/journeys/AGENTS.md` — Critical User Journey instrumentation
13
14## Project Overview
15
16Grafana is a monitoring and observability platform. Go backend, TypeScript/React frontend, monorepo with Yarn workspaces (frontend) and Go workspaces (backend).
17
18## Principles
19
20- Follow existing patterns in the surrounding code
21- Write tests for new functionality
22- Keep changes focused — avoid over-engineering
23- Separate PRs for frontend and backend changes (deployed at different cadences)
24- Security: prevent XSS, SQL injection, command injection
25
26## Comments
27
28- Only add a comment when it explains **why** something is done or reveals non-obvious logic that a reader must know to safely change the code. If the code is self-explanatory, no comment is needed.
29- Never include links (Slack, GitHub, Jira, etc.) in code comments.
30
31## Human Review Gates
32
33Before running `git push`, stop and get explicit human approval. When changes are ready, show a summary of changes and wait for instruction. "Open a PR" in a task description is intent, not permission to push without review.
34
35## Commands
36
37### Build & Run
38
39```bash
40make run # Backend with hot reload (localhost:3000, admin/admin)
41make build-backend # Backend only
42yarn start # Frontend dev server (watches for changes)
43yarn build # Frontend production build
44```
45
46### Test
47
48```bash
49# Backend
50go test -run TestName ./pkg/services/myservice/ # Specific test
51make test-go-unit # All unit tests
52make test-go-integration # Integration tests
53
54# Frontend
55yarn test path/to/file # Specific file
56yarn test -t "pattern" # By name pattern
57yarn test -u # Update snapshots
58
59# E2E
60yarn e2e:playwright path/to/test.spec.ts # Specific test
61```
62
63### Lint & Format
64
65```bash
66make lint-go # Go linter
67yarn lint # ESLint
68yarn lint:fix # ESLint auto-fix
69yarn prettier:write # Prettier auto-format
70yarn typecheck # TypeScript check
71```
72
73### Code Generation
74
75```bash
76make gen-go # Wire DI (after changing service init)
77make gen-cue # CUE schemas (after changing kinds/)
78make gen-apps # App SDK apps
79make swagger-gen # OpenAPI/Swagger specs
80make gen-feature-toggles # Feature flags (pkg/services/featuremgmt/)
81make i18n-extract # i18n strings
82make update-workspace # Go workspace (after adding modules)
83```
84
85### Dev Environment
86
87```bash
88yarn install --immutable # Install frontend deps
89make devenv sources=influxdb # Start backing services
90make devenv-down # Stop backing services
91make lefthook-install # Pre-commit hooks
92```
93
94## Architecture
95
96### Backend (`pkg/`)
97
98| Directory | Purpose |
99| ----------------- | ----------------------------------------------------------- |
100| `pkg/api/` | HTTP API handlers and routes |
101| `pkg/services/` | Business logic by domain (alerting, dashboards, auth, etc.) |
102| `pkg/server/` | Server init and Wire DI setup (`wire.go`) |
103| `pkg/tsdb/` | Time series database query backends |
104| `pkg/plugins/` | Plugin system and loader |
105| `pkg/infra/` | Logging, metrics, database access |
106| `pkg/middleware/` | HTTP middleware |
107| `pkg/setting/` | Configuration management |
108
109**Patterns**: Wire DI (regenerate with `make gen-go`), services implement interfaces in same package, business logic in `pkg/services/<domain>/` not in API handlers, database via `sqlstore`, plugin communication via gRPC/protobuf.
110
111### Frontend (`public/app/`)
112
113| Directory | Purpose |
114| ---------------------- | ----------------------------------------------------- |
115| `public/app/core/` | Shared services, components, utilities |
116| `public/app/features/` | Feature code by domain (dashboard, alerting, explore) |
117| `public/app/plugins/` | Built-in plugins (many are Yarn workspaces) |
118| `public/app/types/` | TypeScript type definitions |
119| `public/app/store/` | Redux store configuration |
120
121**Patterns**: Redux Toolkit with slices (not old Redux), function components with hooks, Emotion CSS-in-JS via `useStyles2`, RTK Query for data fetching, React Testing Library for tests.
122
123### Shared Packages (`packages/`)
124
125`@grafana/data` (data structures), `@grafana/ui` (components), `@grafana/runtime` (runtime services), `@grafana/schema` (CUE-generated types), `@grafana/scenes` (dashboard framework).
126
127### Backend Apps (`apps/`)
128
129Standalone Go apps using Grafana App SDK: `apps/dashboard/`, `apps/folder/`, `apps/alerting/`.
130
131### Plugin Workspaces
132
133These built-in plugins require separate build steps: `azuremonitor`, `loki`, `grafana-testdata-datasource`.
134
135Build a specific plugin: `yarn workspace @grafana-plugins/<name> dev`
136
137## Key Notes
138
139- **Wire DI**: Backend service init changes require `make gen-go`. Wire catches circular deps at compile time.
140- **CUE schemas**: Dashboard/panel schemas in `kinds/` generate both Go and TS code via `make gen-cue`.
141- **Feature toggles**: Defined in `pkg/services/featuremgmt/`, auto-generate code. Run `make gen-feature-toggles` after changes.
142- **Go workspace**: Defined in `go.work`. Run `make update-workspace` when adding Go modules.
143- **Build tags**: `oss` (default), `enterprise`, `pro`.
144- **Config**: Defaults in `conf/defaults.ini`, overrides in `conf/custom.ini`.
145- **Database migrations**: Live in `pkg/services/sqlstore/migrations/`. Test with `make devenv sources=postgres_tests,mysql_tests` then `make test-go-integration-postgres`.
146- **CI sharding**: Backend tests use `SHARD`/`SHARDS` env vars for parallelization.
147- **Service compatibility**: Unified storage/search (`pkg/storage/unified/`) can be deployed as separate services at a different cadence than the Grafana API layer. Changes spanning API-layer callers and `pkg/storage/unified/` must be backwards compatible in both directions — see `pkg/storage/unified/AGENTS.md`.
148
149## Cursor Cloud specific instructions
150
151### Prerequisites
152
153- **Node.js** — version pinned in `.nvmrc` (check that file for the exact version). Installed via nvm and set as the nvm default. **PATH gotcha:** the infra injects `/exec-daemon/node` ahead of nvm, so the plain non-login shell may resolve `node` to an older version — check it satisfies the `engines` range in `package.json` (it does today, so builds/tests work), but it is not the pinned version. Login shells (tmux sessions, `bash -lc '...'`) get the pinned version because `~/.bashrc` prepends the nvm bin. Run `yarn` / `yarn start` / `jest` / webpack via a login shell (tmux or `bash -lc`) to use the pinned Node.
154- **Go** — version pinned in `go.mod` (check that file for the exact version), installed at `/usr/local/go` and symlinked to `/usr/local/bin/go`. The distro `/usr/bin/go` is older; `/usr/local/bin` wins in PATH so `go` resolves correctly. If `go.mod` bumps Go, reinstall a matching toolchain into `/usr/local/go`.
155- **Yarn** via corepack — version pinned by `package.json` `packageManager` (check that field for the exact version). Run `corepack enable` if `yarn` is not found. `.yarnrc.yml` sets `enableScripts: false`, so dependency build/lifecycle scripts are disabled by default.
156- **GCC** required for CGo/SQLite compilation of the backend.
157- Repos in this environment live under `/agent/repos/<repo>` (e.g. `/agent/repos/grafana`); this is a multi-repo workspace, not the single `~/grafana` layout described in `grafana-enterprise/AGENTS.md`.
158
159### Running services
160
161- **Backend**: `make run` — builds and starts Grafana backend with hot-reload (air) on `localhost:3000`. Default login: `admin`/`admin`. First build takes ~3 minutes due to debug symbols (`-gcflags all=-N -l`); subsequent hot-reload rebuilds are faster.
162- **Frontend**: `yarn start` — starts webpack dev server that watches for changes. The backend proxies to it. First compile takes ~45s.
163- No external databases required — Grafana uses embedded SQLite by default.
164
165### Testing gotchas
166
167- **Frontend tests**: The `yarn test` script includes `--watch` by default. Always use `yarn jest --no-watch` or add `--watchAll=false` to run tests once and exit.
168- **Backend tests**: Some packages (e.g. `pkg/api/`) have slow test compilation (~2 min) due to large dependency graphs. Use targeted test runs with `-run TestName` where possible.
169- All standard build/test/lint commands are documented in the Commands section above.
170
@@ −1 +1 @@
1−# Frontend features — agent guide
1+# AGENTS.md
22
3−This tree contains Grafana visualization code (canvas, geo, dimensions, table, and more).
4−When you are adding or changing visualization code or its tests here, invoke these skills
5−with the Skill tool — each skill's own description states exactly when it applies:
3+<!-- version: 2.0.0 -->
64
7−- **`panel-testing-strategy`** — how visualization unit + E2E tests should be written:
8− assert real behavior (not existence), the canvas draw-call snapshot harness, honest
9− test descriptions, and the anti-flake rules.
10−- **`add-e2e-selectors`** — add versioned `@grafana/e2e-selectors` and wire
11− `data-testid` into JSX when making UI testable.
5+This file provides guidance to AI agents when working with code in the Grafana repository.
6+
7+**Directory-scoped agent files exist for specialized areas — read them when working in those directories:**
8+
9+- `docs/AGENTS.md` — Documentation style guide (for work under `docs/`)
10+- `public/app/features/alerting/unified/AGENTS.md` — Alerting squad patterns
11+- `pkg/storage/unified/AGENTS.md` — Unified storage/search compatibility rules (for work under `pkg/storage/unified/`)
12+- `public/app/core/journeys/AGENTS.md` — Critical User Journey instrumentation
13+
14+## Project Overview
15+
16+Grafana is a monitoring and observability platform. Go backend, TypeScript/React frontend, monorepo with Yarn workspaces (frontend) and Go workspaces (backend).
17+
18+## Principles
19+
20+- Follow existing patterns in the surrounding code
21+- Write tests for new functionality
22+- Keep changes focused — avoid over-engineering
23+- Separate PRs for frontend and backend changes (deployed at different cadences)
24+- Security: prevent XSS, SQL injection, command injection
25+
26+## Comments
27+
28+- Only add a comment when it explains **why** something is done or reveals non-obvious logic that a reader must know to safely change the code. If the code is self-explanatory, no comment is needed.
29+- Never include links (Slack, GitHub, Jira, etc.) in code comments.
30+
31+## Human Review Gates
32+
33+Before running `git push`, stop and get explicit human approval. When changes are ready, show a summary of changes and wait for instruction. "Open a PR" in a task description is intent, not permission to push without review.
34+
35+## Commands
36+
37+### Build & Run
38+
39+```bash
40+make run # Backend with hot reload (localhost:3000, admin/admin)
41+make build-backend # Backend only
42+yarn start # Frontend dev server (watches for changes)
43+yarn build # Frontend production build
44+```
45+
46+### Test
47+
48+```bash
49+# Backend
50+go test -run TestName ./pkg/services/myservice/ # Specific test
51+make test-go-unit # All unit tests
52+make test-go-integration # Integration tests
53+
54+# Frontend
55+yarn test path/to/file # Specific file
56+yarn test -t "pattern" # By name pattern
57+yarn test -u # Update snapshots
58+
59+# E2E
60+yarn e2e:playwright path/to/test.spec.ts # Specific test
61+```
62+
63+### Lint & Format
64+
65+```bash
66+make lint-go # Go linter
67+yarn lint # ESLint
68+yarn lint:fix # ESLint auto-fix
69+yarn prettier:write # Prettier auto-format
70+yarn typecheck # TypeScript check
71+```
72+
73+### Code Generation
74+
75+```bash
76+make gen-go # Wire DI (after changing service init)
77+make gen-cue # CUE schemas (after changing kinds/)
78+make gen-apps # App SDK apps
79+make swagger-gen # OpenAPI/Swagger specs
80+make gen-feature-toggles # Feature flags (pkg/services/featuremgmt/)
81+make i18n-extract # i18n strings
82+make update-workspace # Go workspace (after adding modules)
83+```
84+
85+### Dev Environment
86+
87+```bash
88+yarn install --immutable # Install frontend deps
89+make devenv sources=influxdb # Start backing services
90+make devenv-down # Stop backing services
91+make lefthook-install # Pre-commit hooks
92+```
93+
94+## Architecture
95+
96+### Backend (`pkg/`)
97+
98+| Directory | Purpose |
99+| ----------------- | ----------------------------------------------------------- |
100+| `pkg/api/` | HTTP API handlers and routes |
101+| `pkg/services/` | Business logic by domain (alerting, dashboards, auth, etc.) |
102+| `pkg/server/` | Server init and Wire DI setup (`wire.go`) |
103+| `pkg/tsdb/` | Time series database query backends |
104+| `pkg/plugins/` | Plugin system and loader |
105+| `pkg/infra/` | Logging, metrics, database access |
106+| `pkg/middleware/` | HTTP middleware |
107+| `pkg/setting/` | Configuration management |
108+
109+**Patterns**: Wire DI (regenerate with `make gen-go`), services implement interfaces in same package, business logic in `pkg/services/<domain>/` not in API handlers, database via `sqlstore`, plugin communication via gRPC/protobuf.
110+
111+### Frontend (`public/app/`)
112+
113+| Directory | Purpose |
114+| ---------------------- | ----------------------------------------------------- |
115+| `public/app/core/` | Shared services, components, utilities |
116+| `public/app/features/` | Feature code by domain (dashboard, alerting, explore) |
117+| `public/app/plugins/` | Built-in plugins (many are Yarn workspaces) |
118+| `public/app/types/` | TypeScript type definitions |
119+| `public/app/store/` | Redux store configuration |
120+
121+**Patterns**: Redux Toolkit with slices (not old Redux), function components with hooks, Emotion CSS-in-JS via `useStyles2`, RTK Query for data fetching, React Testing Library for tests.
122+
123+### Shared Packages (`packages/`)
124+
125+`@grafana/data` (data structures), `@grafana/ui` (components), `@grafana/runtime` (runtime services), `@grafana/schema` (CUE-generated types), `@grafana/scenes` (dashboard framework).
126+
127+### Backend Apps (`apps/`)
128+
129+Standalone Go apps using Grafana App SDK: `apps/dashboard/`, `apps/folder/`, `apps/alerting/`.
130+
131+### Plugin Workspaces
132+
133+These built-in plugins require separate build steps: `azuremonitor`, `loki`, `grafana-testdata-datasource`.
134+
135+Build a specific plugin: `yarn workspace @grafana-plugins/<name> dev`
136+
137+## Key Notes
138+
139+- **Wire DI**: Backend service init changes require `make gen-go`. Wire catches circular deps at compile time.
140+- **CUE schemas**: Dashboard/panel schemas in `kinds/` generate both Go and TS code via `make gen-cue`.
141+- **Feature toggles**: Defined in `pkg/services/featuremgmt/`, auto-generate code. Run `make gen-feature-toggles` after changes.
142+- **Go workspace**: Defined in `go.work`. Run `make update-workspace` when adding Go modules.
143+- **Build tags**: `oss` (default), `enterprise`, `pro`.
144+- **Config**: Defaults in `conf/defaults.ini`, overrides in `conf/custom.ini`.
145+- **Database migrations**: Live in `pkg/services/sqlstore/migrations/`. Test with `make devenv sources=postgres_tests,mysql_tests` then `make test-go-integration-postgres`.
146+- **CI sharding**: Backend tests use `SHARD`/`SHARDS` env vars for parallelization.
147+- **Service compatibility**: Unified storage/search (`pkg/storage/unified/`) can be deployed as separate services at a different cadence than the Grafana API layer. Changes spanning API-layer callers and `pkg/storage/unified/` must be backwards compatible in both directions — see `pkg/storage/unified/AGENTS.md`.
148+
149+## Cursor Cloud specific instructions
150+
151+### Prerequisites
152+
153+- **Node.js** — version pinned in `.nvmrc` (check that file for the exact version). Installed via nvm and set as the nvm default. **PATH gotcha:** the infra injects `/exec-daemon/node` ahead of nvm, so the plain non-login shell may resolve `node` to an older version — check it satisfies the `engines` range in `package.json` (it does today, so builds/tests work), but it is not the pinned version. Login shells (tmux sessions, `bash -lc '...'`) get the pinned version because `~/.bashrc` prepends the nvm bin. Run `yarn` / `yarn start` / `jest` / webpack via a login shell (tmux or `bash -lc`) to use the pinned Node.
154+- **Go** — version pinned in `go.mod` (check that file for the exact version), installed at `/usr/local/go` and symlinked to `/usr/local/bin/go`. The distro `/usr/bin/go` is older; `/usr/local/bin` wins in PATH so `go` resolves correctly. If `go.mod` bumps Go, reinstall a matching toolchain into `/usr/local/go`.
155+- **Yarn** via corepack — version pinned by `package.json` `packageManager` (check that field for the exact version). Run `corepack enable` if `yarn` is not found. `.yarnrc.yml` sets `enableScripts: false`, so dependency build/lifecycle scripts are disabled by default.
156+- **GCC** required for CGo/SQLite compilation of the backend.
157+- Repos in this environment live under `/agent/repos/<repo>` (e.g. `/agent/repos/grafana`); this is a multi-repo workspace, not the single `~/grafana` layout described in `grafana-enterprise/AGENTS.md`.
158+
159+### Running services
160+
161+- **Backend**: `make run` — builds and starts Grafana backend with hot-reload (air) on `localhost:3000`. Default login: `admin`/`admin`. First build takes ~3 minutes due to debug symbols (`-gcflags all=-N -l`); subsequent hot-reload rebuilds are faster.
162+- **Frontend**: `yarn start` — starts webpack dev server that watches for changes. The backend proxies to it. First compile takes ~45s.
163+- No external databases required — Grafana uses embedded SQLite by default.
164+
165+### Testing gotchas
166+
167+- **Frontend tests**: The `yarn test` script includes `--watch` by default. Always use `yarn jest --no-watch` or add `--watchAll=false` to run tests once and exit.
168+- **Backend tests**: Some packages (e.g. `pkg/api/`) have slow test compilation (~2 min) due to large dependency graphs. Use targeted test runs with `-run TestName` where possible.
169+- All standard build/test/lint commands are documented in the Commands section above.
12170
