diff --git a/guides/data-apps.mdx b/guides/data-apps.mdx index 83c19192..468bc25d 100644 --- a/guides/data-apps.mdx +++ b/guides/data-apps.mdx @@ -257,7 +257,7 @@ lightdash download --apps-only --apps 8f2b1c4d-1111-2222-3333-444455556666 Each app is written to `lightdash/apps//`, where `` is derived from the app's name. Every folder is a locally buildable project: -- `lightdash-app.yml` — the manifest, including the `appUuid` that identifies the app when you re-upload it, plus editable `name` and `description` fields. +- `lightdash-app.yml` — the manifest, including the `appUuid` that identifies the app when you re-upload it, plus editable `name` and `description` fields. For [data app visualizations](/guides/data-apps/visualizations), the manifest also carries a `vizSchema` field describing the declared fields (dimensions, metrics, series) the viz needs — the schema is stored in the database, not the source tree, so the CLI persists it here to round-trip a viz through download and upload. - `src/` — the app's source tree (React components, styles, etc.). **This is the only directory you should edit.** - `package.json`, `README.md`, `.gitignore`, `AGENTS.md`, and `.claude/skills/` — a template that lets you install dependencies and run `pnpm build` locally to sanity-check that the source compiles. Editing these files has no effect on the deployed app — the server rebuilds against its own trusted template. - `.lightdash/context/` — a read-only, point-in-time snapshot of the source project so you (or an AI agent) have the context needed to edit the app: `semantic-layer.yml` (tables, dimensions, metrics you can query), `parameters.yml`, `prompt-history.md`, and `theme/` styling assets. Re-download to refresh. @@ -274,6 +274,8 @@ Once an app is on disk you can iterate on it locally: The bundled `.claude/skills/` and `AGENTS.md` files describe the SDK surface and this workflow so coding agents (Claude Code and similar) can help you edit apps locally without extra prompting. +Data app visualizations follow the same loop: the download writes the viz's declared field schema into `lightdash-app.yml`, and the upload sends it back so the viz shows up in the viz picker on the destination. If you edit the manifest's `vizSchema` directly, the upload validates it and rejects malformed schemas. Bundles downloaded before viz schemas round-tripped have no `vizSchema` field — re-download from the source project to pick it up before uploading elsewhere. + ### Uploading an app Use `lightdash upload --apps` to send your local changes back: diff --git a/guides/data-apps/themes.mdx b/guides/data-apps/themes.mdx index fa24a02f..45c2c87c 100644 --- a/guides/data-apps/themes.mdx +++ b/guides/data-apps/themes.mdx @@ -20,6 +20,12 @@ A theme is a bundle of resources the agent uses when it builds an app: The quality of a theme depends largely on the specificity of the instructions in `skill.md` and the extra instructions field. The more concretely you describe how the agent should use the CSS, fonts, and images - and what the app should feel like - the more consistent your results will be. +### Size limit + +A theme's files are streamed into the app sandbox. To keep things fast and predictable, themes have a hard limit of **100 MB total across all uploaded assets** (fonts, images, and instruction files combined). Individual files are capped at 10 MB. + +The cap is on aggregate bytes, not file count — a theme with many small text files is cheap, but a handful of large images can blow past it. Compress or downscale image assets, or split them into a smaller curated set, if you're near the limit. + ## Extra instructions Each theme has an **Extra instructions** field that you can edit directly from the theme detail panel in **Settings → Themes**. These instructions are passed to the agent alongside any uploaded instruction markdown files when an app is built with the theme. diff --git a/references/lightdash-cli.mdx b/references/lightdash-cli.mdx index ae311d00..c1f0bb1a 100644 --- a/references/lightdash-cli.mdx +++ b/references/lightdash-cli.mdx @@ -705,7 +705,7 @@ You can make changes to the code and upload these changes back to your Lightdash - (default: false) - opt-in flag to download every [virtual view](/guides/developer/dashboards-as-code#virtual-views) in the project as code. Use `--virtual-views ` instead when you only want specific views. - `--apps ` - - opt-in flag to also download specific [data apps](/guides/data-apps#data-apps-as-code) as code (enterprise only). Pass one or more app UUIDs to download just those apps — this is the only way to download apps that haven't been added to a space. Each app is written to `lightdash/apps//` as a locally buildable project: `lightdash-app.yml` manifest, the app's `src/` tree, `package.json`, a read-only `.lightdash/context/` snapshot of the project's semantic layer, and agent skill files. The built output is not included — the server rebuilds it on upload. + - opt-in flag to also download specific [data apps](/guides/data-apps#data-apps-as-code) as code (enterprise only). Pass one or more app UUIDs to download just those apps — this is the only way to download apps that haven't been added to a space. Each app is written to `lightdash/apps//` as a locally buildable project: `lightdash-app.yml` manifest, the app's `src/` tree, `package.json`, a read-only `.lightdash/context/` snapshot of the project's semantic layer, and agent skill files. For [data app visualizations](/guides/data-apps/visualizations), the manifest also carries a `vizSchema` field with the viz's declared fields so the viz round-trips to the destination on upload. The built output is not included — the server rebuilds it on upload. - `--include-apps` - (default: false) - opt-in flag to download every [data app](/guides/data-apps#data-apps-as-code) in the project that has been added to a space (enterprise only), capped at the first 10. Use `--apps ` to reach apps that aren't in a space, or to download more than 10. @@ -852,7 +852,7 @@ If there have been changes made to a chart or dashboard in the application that - (default: false) - skip uploading virtual views, even when `lightdash/virtual-views/` contains files - `--apps [appUuids...]` - - opt-in flag to also upload [data apps](/guides/data-apps#data-apps-as-code) as code (enterprise only). Bare `--apps` uploads every app folder under `lightdash/apps/`. Pass one or more app UUIDs to upload just those apps. The CLI posts each app's `src/` tree and returns immediately — the destination rebuilds the app in its sandbox and publishes a new version. The app shows a `building` status in the UI until the build finishes. Uploading to the same project appends a new version and applies any edits to the manifest's `name` or `description`; uploading to a different project prompts for confirmation (in non-interactive shells the app is skipped with an error unless you also pass `--create-new`) and creates a new app in the target. After any create, the CLI prints the new app's URL and offers to retarget the local `lightdash-app.yml` (updating `appUuid`, `projectUuid`, and `version`) so future uploads update the new app. + - opt-in flag to also upload [data apps](/guides/data-apps#data-apps-as-code) as code (enterprise only). Bare `--apps` uploads every app folder under `lightdash/apps/`. Pass one or more app UUIDs to upload just those apps. The CLI posts each app's `src/` tree and returns immediately — the destination rebuilds the app in its sandbox and publishes a new version. The app shows a `building` status in the UI until the build finishes. Uploading to the same project appends a new version and applies any edits to the manifest's `name` or `description`; uploading to a different project prompts for confirmation (in non-interactive shells the app is skipped with an error unless you also pass `--create-new`) and creates a new app in the target. After any create, the CLI prints the new app's URL and offers to retarget the local `lightdash-app.yml` (updating `appUuid`, `projectUuid`, and `version`) so future uploads update the new app. For [data app visualizations](/guides/data-apps/visualizations), the manifest's `vizSchema` is sent alongside the source and persisted on the new version — so a downloaded viz appears in the destination project's viz picker after upload without needing to be regenerated. Uploading requires the [`create:DataApp` scope](/references/workspace/roles), which is granted to Editor, Developer, and Admin roles. - `--create-new` - (default: false) - always create a new data app from the uploaded source instead of appending a new version to the app referenced by `lightdash-app.yml`. Combine with `--apps` and `--project` when copying an app to a different project or instance in a non-interactive shell. diff --git a/references/workspace/roles.mdx b/references/workspace/roles.mdx index 0d818b0d..f85b70d3 100644 --- a/references/workspace/roles.mdx +++ b/references/workspace/roles.mdx @@ -195,7 +195,7 @@ Project Admins can invite users to their project and assign users or [groups](/r | View Data App | | | | | | | Manage Data App | | | | | | | Manage Data App Space | | | | | | -| Create Data App | | | | | | +| Create Data App | | | | | | | View Data App Self | | | | | | | Manage Data App Self | | | | | | | View External Connection | | | | | |