Developing Data Apps Locally
Developmentdeveloping-data-apps-locallyDeveloping Data Apps Locally is an Agent Skill for development published in the lightdash/lightdash repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Use when editing a downloaded Lightdash data app on your machine — how local editing, building, and re-uploading work, and what is read-only.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/lightdash/lightdash/blob/HEAD/packages/cli/src/handlers/apps/authoring/developing-data-apps-locally/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/developing-data-apps-locally, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Developing Lightdash Data Apps Locally
You are editing a Lightdash data app that was downloaded with the Lightdash CLI (lightdash download).
The only way to reach data is the SDK
- All data access goes through
@lightdash/query-sdk(a postMessage bridge to Lightdash). There is nofetch, no REST calls, no other network access at runtime — anything else is blocked. - For the SDK surface (query builder,
useLightdash, filters, downloads), read thelightdash-data-appskill in this folder.
Library boundaries — build with what's preinstalled
- The app builds against a fixed template dependency set — see
package.json(React, Recharts, d3 + d3-cloud/d3-sankey, Radix primitives, Tailwind, lucide-react, date-fns, html-to-image, jspdf, and more). Design within this set; it covers almost all data-app needs. - Adding new npm packages only works when the Lightdash instance has custom dependencies enabled — assume it does not. When disabled, upload rejects new dependencies and apps that declare them cannot be downloaded. Do not attempt
pnpm addto find out; ask the user whether their instance has custom dependencies enabled before considering a new library. - Do not work around a missing library by vendoring its source into
src/, inlining minified code, or fetching code at runtime. If the template set genuinely cannot express what's asked, say so and let the user decide.
The edit → build → upload loop
- Edit files under
src/only. - Optionally,
pnpm installthenpnpm buildto check it compiles. This is an optional local pre-check — see below. lightdash upload --apps <appUuid>(theappUuidfrom this folder'slightdash-app.yml) — the server rebuilds and serves the app. The server rebuild, not your local build, is what ships.
The local build is optional — never fight a failing install
- If
pnpm installfails (registry policy, an unavailable pinned SDK version, no network access), skip the local build entirely and go straight to upload. The server rebuild is authoritative and surfaces build errors on the app page. - Do not modify machine configuration,
.npmrcfiles, registry settings, or the project's dependency files to force an install to work. - A missing
node_modulesis a normal state, not a problem to fix. Never run installs just because it is absent. - Exception — adding a dependency (only on instances with custom dependencies enabled — see "Library boundaries" above). Upload rejects new dependencies unless
pnpm-lock.yamlwas regenerated to matchpackage.json, so dependency resolution MUST succeed locally. Usepnpm add <pkg>, or after editingpackage.jsonrunpnpm install --lockfile-only(updates the lockfile without installing). If resolution fails, stop and report the exact pnpm error to the user — never hand-editpackage.jsonand proceed without the lockfile; the upload will fail. - Never run dependency lifecycle scripts. The app's
.npmrcsetsignore-scripts=true— leave it. A downloaded app can be authored by someone else, and their dependencies' install scripts must not execute on this machine. Explicitpnpm build/pnpm devstill work.
Project context (read-only reference)
.lightdash/context/ holds a point-in-time snapshot of the source project:
semantic-layer.yml— the real tables/dimensions/metrics you can query. Use these exact names.parameters.yml— project-wide parameters (if any).prompt-history.md— the prompts used to generate each version.theme/— styling instructions and assets.
Read-only files
Most root config is reference only — editing it has no effect because the server rebuilds against its trusted template. This applies to vite.config.js, tailwind.config.js, tsconfig.json, and other build/tooling files.
package.json is partially editable only when custom dependencies are enabled on the Lightdash instance — see "Library boundaries" above; treat it as read-only otherwise. When enabled, you may add npm dependencies with pnpm add <pkg> — registry packages with plain semver versions only (no git/file/url specs), up to 60 direct dependencies, and pnpm-lock.yaml must be updated alongside (see the exception above — this is the one step that must succeed locally). On upload the CLI warns which packages will be installed in the build sandbox; install scripts never run. Other root config (vite/tailwind/tsconfig) remains read-only.