Development workflow

The day-to-day inner loop for changing Grafana. Setup is documented in Getting started — this page focuses on while you're working.

Run servers in two terminals

# Terminal 1: Go backend with hot reload (air)
make run                # localhost:3000, login admin/admin

# Terminal 2: Frontend dev server (webpack watch)
yarn start

The Go server proxies the frontend, so visiting http://localhost:3000 always serves the most recent webpack build.

Iterate

• Backend change: save a .go file under pkg/. Air will detect the change, recompile, and restart the server. SQLite state under data/ survives restarts so you don't lose dashboards/users.
• Frontend change: save a .ts/.tsx file under public/app/ or packages/. Webpack rebuilds and the browser hot-reloads.
• Schema change (CUE under kinds/ or apps): run make gen-cue or make gen-apps. Air will pick up the regenerated Go.
• Feature toggle change: edit pkg/services/featuremgmt/registry.go and run make gen-feature-toggles. Commit the regenerated toggles_gen.* files.

Frontend tooling notes

• Yarn 4 via Corepack is enforced — don't npm install.
• Workspaces are declared in the root package.json's workspaces array. packages/grafana-*, public/app/plugins/datasource/<name> (some), and the apps/* test plugins all live as workspaces.
• Nx (nx.json) is used for caching and "affected" runs (yarn nx affected -t test).

Backend tooling notes

• Go workspaces are defined in go.work. When you add a new module under apps/ you must run make update-workspace.
• Wire DI is regenerated with make gen-go (which runs wire against pkg/server/wire.go). The generated file is pkg/server/wire_gen.go.
• make build-backend produces bin/<arch>/grafana — useful for ad-hoc CLI runs.

Debugging tips

• make run builds with debug symbols (-gcflags all=-N -l). Attach a Go debugger to PID 0's bra child process.
• yarn start honors React fast-refresh — most edits do not lose UI state.
• data/grafana.db is the SQLite store; you can poke it with sqlite3 while the server is stopped.
• The default config is a merge of conf/defaults.ini and any conf/custom.ini you create. Many local quirks are easier as custom.ini overrides than as command-line flags.

See Debugging for more.

Pull request flow

1. Branch off main.
2. Implement and test.
3. Push and open a PR. The PR template asks about user-facing impact and tests.
4. Wait for CI: lint, frontend tests, backend tests, e2e, sometimes integration tests against Postgres/MySQL.
5. CODEOWNERS-driven reviewers will be auto-requested.
6. Address feedback in additional commits — squash on merge keeps the final history clean.

Pre-commit hooks

Lefthook is configured in lefthook.yml. Install with:

make lefthook-install

This runs Prettier, ESLint, and gofmt on staged files. You can skip with git commit --no-verify but CI will catch it.