@lightdash/cli 2.153.1 → 2.155.0

package/dist/vendor/authoring/chart-type/README.md.tmpl

@@ -0,0 +1,19 @@
+# {{APP_NAME}} — Lightdash custom chart type (local copy)
+
+Created or downloaded with the Lightdash CLI. This is a **custom chart type** (a reusable visualization): one chart component that Lightdash hands data and settings to. It runs no query of its own — the same component is reused across many different queries.
+
+## Edit → validate → upload
+1. Edit files under `src/`. The component's contract with Lightdash — the fields it maps and the config options viewers can change — is declared in `lightdash-app.yml` under `vizSchema` and must match what `src/App.jsx` reads (see `.claude/skills/reusable-visualization`).
+2. Run `lightdash apps validate` to check the source and manifest; `lightdash apps validate --build` adds the Cloud-parity Vite production build.
+3. `lightdash upload --chart-types <slug>` (the `slug` from `lightdash-app.yml`) — Lightdash rebuilds and serves it.
+4. Open any explore in Lightdash, run a query, and pick this chart type in the chart type picker to see it against real data.
+
+There is no standalone preview: the component waits for the Lightdash host's data, so `npm run dev` shows a blank page. Upload and verify in the explorer.
+
+## What's read-only
+Root config (`vite.config.js`, `tsconfig.json`, etc.) is read-only reference — the server rebuilds against a trusted template. Build within the template's fixed dependency set (see `package.json`); chart types published to the official registry must stay template-deps-only.
+
+`.npmrc` sets `ignore-scripts=true` so dependencies' lifecycle scripts never run on your machine. Keep it; explicit commands such as `npm run build` still work.
+
+## Publishing to the official registry
+Once it works in your instance, a chart type can be proposed for the official chart registry (`lightdash/lightdash-gallery`): copy this folder under that repo's `charts/<slug>/`, run `node scripts/prepare-chart.mjs charts/<slug>` there (it prunes the local scaffold and shapes the folder for the registry), add real screenshots, and open a PR — see that repo's README.

package/dist/vendor/authoring/developing-chart-types-locally/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: developing-chart-types-locally
+description: Use when editing a locally created or downloaded Lightdash custom chart type (data_app_viz) — the vizSchema/component lockstep contract, the upload-and-verify loop, why there is no standalone preview, and how a chart type reaches the official registry.
+---
+
+# Developing Lightdash Custom Chart Types Locally
+
+You are editing a Lightdash **custom chart type** (a reusable visualization, the `data_app_viz` template) that was created or downloaded with the Lightdash CLI. It is ONE chart component that Lightdash hands data and settings to — not a data app.
+
+## The contract is the reusable-visualization skill
+
+Read `.claude/skills/reusable-visualization` before editing. It defines everything the component may do: `useVizContext()` is the only channel to the host (data, options, resolved colours), the component runs no query, owns no explore, and never fetches anything itself. App-level SDK APIs (query builder, `useLightdash`, filters, `externalFetch`) do not apply here and must not be introduced.
+
+## The declaration lives in lightdash-app.yml — keep it in lockstep
+
+In the in-product builder the declaration is emitted by the generation run; **locally it is the `vizSchema` block in this folder's `lightdash-app.yml`**, and upload round-trips it to the server (without it the chart type never appears in the explorer's chart type picker).
+
+The correspondence must be exact in both directions: every key the component reads from `fieldMapping` or `options` is declared in `vizSchema`, and everything declared there is read by the component. When an edit changes what the component reads — a new field, a renamed option, a removed control — update `vizSchema` in the same edit. A declared option nothing reads is a dead control; a read key nothing declares never receives a value.
+
+## The edit → validate → upload → verify loop
+
+1. Edit files under `src/` (and `vizSchema` when the declaration changes).
+2. `lightdash apps validate` checks source and manifest (including that `vizSchema` parses); `lightdash apps validate --build` adds the Cloud-parity Vite production build. A build failure is a validation error with the Vite output.
+3. `lightdash upload --chart-types <slug>` (the `slug` from `lightdash-app.yml`) — the server rebuilds and serves it.
+4. Verify in Lightdash: open any explore, run a query with at least the required fields' shapes (e.g. a dimension and a metric), pick this chart type in the chart type picker, and map its fields. Check every config option you declared actually changes the chart.
+
+**There is no standalone preview.** `useVizContext()` waits for the Lightdash host to push context, so outside Lightdash the component renders nothing: `npm run dev` and `lightdash apps preview` show a blank page. Do not build a mock harness or feed the hook fake data to work around this — upload and verify in the explorer instead.
+
+Saved charts already using this chart type may pin a version; unpinned charts move to the newly uploaded version right away. While iterating in a shared project, prefer verifying on a throwaway chart.
+
+## Dependencies: template-deps-only, strictly
+
+Build with the template's preinstalled set (see `package.json` — React, Recharts, d3 and friends). Do not add npm packages and do not vendor library source into `src/`. This is stricter than for data apps: the official chart registry rejects any dependency drift from its template, so a chart type that grows custom dependencies becomes unpublishable.
+
+Root config files (`vite.config.js`, `tsconfig.json`, ...) are read-only reference — the server rebuilds against a trusted template. `.npmrc` sets `ignore-scripts=true`; never remove it or run installs with scripts enabled.
+
+## Publishing to the official registry
+
+Once the chart type works in an instance, it can be proposed for the official chart registry (the `lightdash/lightdash-gallery` repo, served to every Lightdash deployment with the chart type library enabled):
+
+1. Copy this folder into that repo under `charts/<slug>/`.
+2. Run `node scripts/prepare-chart.mjs charts/<slug>` there — it prunes the local scaffold (these skills, configs, AGENTS/README), scrubs instance-side manifest fields, and shapes the folder for the registry. The folder name becomes the **permanent official registry slug**; pass `--slug <official-slug>` if the local slug isn't the identity that should ship.
+3. Add real screenshots from the in-product preview under `screenshots/` (the first is the gallery thumbnail) and fill in `registry.yml` (version, tags, changelog). New versions default to the beta channel; releasing to customers requires an explicit `channel: stable`.
+4. Open a PR there. On merge, publishing is automatic; published versions are immutable — any later change needs a version bump.
+
+Report the registry step as a suggestion to the user rather than doing it unprompted: publishing makes the chart type public.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightdash/cli",
-  "version": "2.153.1",
+  "version": "2.155.0",
   "description": "Lightdash CLI tool",
   "license": "MIT",
   "repository": {
@@ -45,8 +45,8 @@
     "unique-names-generator": "4.7.1",
     "uuid": "11.1.1",
     "yaml": "2.8.3",
-    "@lightdash/common": "2.153.1",
-    "@lightdash/warehouses": "2.153.1"
+    "@lightdash/common": "2.155.0",
+    "@lightdash/warehouses": "2.155.0"
   },
   "devDependencies": {
     "@types/inquirer": "8.2.4",