@ggts-sh/svelte

中文文档
0.48.3发布于 2026/11/06MITTypeScriptES Module构建来源已验证近 30 天下载 4256

ggts: a layered grammar of graphics for Svelte 5 — ggplot2 semantics, JSON-serializable specs, agent-friendly validation, and hybrid SVG/canvas rendering. The ggts render CLI ships separately as @ggts-sh/cli.

原始使用文档
文档目录5 节
  1. Example
  2. Smaller bundles: the lean entry
  3. Agent skill
  4. Migrating old code
  5. Links

@ggts-sh/svelte

codecov

Svelte 5 components for ggts. Re-exports @ggts-sh/spec and @ggts-sh/core. The agent skill ships separately as @ggts-sh/skill, and the ggts render CLI as @ggts-sh/cli — install both in every sandbox where an agent authors specs.

bun add @ggts-sh/svelte @ggts-sh/core
# or: npm install @ggts-sh/svelte @ggts-sh/core

Requires Node.js 22+ and Svelte 5.33.1+. The example imports bundled data from @ggts-sh/core/data, so it installs core as a direct dependency. Charts with inline data need only @ggts-sh/svelte.

Example

Compose with declaration-only children (theme, scales, labs, geoms). Do not put theme, scales, labs, guides, facet, coord, or legend on <GGPlot> — those props were removed in 0.13.0.

<script lang="ts">
  import {
    GeomPoint,
    GeomSmooth,
    GGPlot,
    Labs,
    ThemeMinimal,
  } from "@ggts-sh/svelte";
  import { kyotoSakura } from "@ggts-sh/core/data";
</script>

<GGPlot data={kyotoSakura} aes={{ x: "year", y: "bloomDoy" }}>
  <GeomSmooth method="loess" se={false} />
  <GeomPoint size={2} alpha={0.7} />
  <ThemeMinimal />
  <Labs
    title="Kyoto cherry blossom full-bloom dates, 812–2026"
    subtitle="Full bloom moved about ten days earlier after the industrial era"
    x="Year"
    y="Day of year"
  />
</GGPlot>

Convention (ggplot2 thinking order): mark layers first, then scales / coords / facets, then theme / guides / labs, then host-only <Inspect> last. Dense points may render on canvas; axes, legends, text, and accessible descriptions stay in the DOM. Prefer <Inspect /> and <GuideLegend channel focus> / <GuideLegend channel filter> for interaction — not plot-level inspect, legendFocus, or legendFilter.

Smaller bundles: the lean entry

@ggts-sh/svelte registers the basic geoms, stats, and color and style scale kinds when you import it. To ship only what your charts use, import from @ggts-sh/svelte/lean and call the register functions once at startup:

<script lang="ts" module>
  import {
    registerBasicLines,
    registerBasicPoints,
    registerDefaultOrdinalColor,
  } from "@ggts-sh/svelte/lean";

  registerBasicPoints();
  registerBasicLines();
  registerDefaultOrdinalColor();
</script>

<script lang="ts">
  import { GeomLine, GeomPoint, GGPlot } from "@ggts-sh/svelte/lean";
</script>

For a point and line chart with mapped color, this saves about 26 KB gzip. If a chart needs a family that is not registered, GGPlot throws an error that names the register function to call. One import from @ggts-sh/svelte anywhere in the app brings back the full basic registration.

Agent skill

Published separately as @ggts-sh/skill: node_modules/@ggts-sh/skill/SKILL.md. Copy it into your agent's skills directory as ggts/ and re-copy on version bumps — dependabot surfaces those. (Removed from this package in 0.27.0.)

Emit PortableSpec JSON, run validate(), apply fix.example at path, re-validate, then render with <GGPlot spec={…} />, renderToSVGString, or ggts render. Schema: schema/v0.json.

Migrating old code

If you still have pre-0.13 sources with grammar props on <GGPlot>, the codemod rewrites them to children:

npm exec --package=@ggts-sh/svelte -- ggts-codemod src          # show what would change
npm exec --package=@ggts-sh/svelte -- ggts-codemod --write src  # apply

Shapes it will not rewrite mechanically are printed as manual change required with a link to the upgrading guide, never half-migrated.

Pre-1.0. Lifecycle and compatibility contracts are on the docs site.

MIT © Liam O'Dea

版本与发布记录

@ggts-sh/svelte 共发布 11 个版本,首次发布于 2026/09/08;过去 12 个月发布了 11 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.48.3latest2026/11/0610 天前
0.48.22026/11/0610 天前
0.48.12026/11/0510 天前
0.48.02026/11/0511 天前
0.47.02026/11/0313 天前
0.46.02026/11/0313 天前

关于 @ggts-sh/svelte 的常见问题

@ggts-sh/svelte 是什么?

ggts: a layered grammar of graphics for Svelte 5 — ggplot2 semantics, JSON-serializable specs, agent-friendly validation, and hybrid SVG/canvas rendering. The ggts render CLI ships separately as @ggts-sh/cli.

如何安装 @ggts-sh/svelte?

在项目目录运行 npm install @ggts-sh/svelte,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:svelte(^5.33.1)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。它还提供命令行工具 ggts-codemod,可以用 npx ggts-codemod 直接运行。

@ggts-sh/svelte 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@ggts-sh/svelte 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@ggts-sh/svelte 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=22。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@ggts-sh/svelte 可以商用吗?

@ggts-sh/svelte 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@ggts-sh/svelte 的下载量有多少?

根据 npm 官方下载统计,@ggts-sh/svelte 在 2026/10/17 – 2026/11/15 这 30 天内被下载 4,256 次,日均约 142 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@ggts-sh/svelte 还在维护吗?

最新版本 0.48.3 发布于 2026/11/06(10 天前);至今共发布 11 个版本,其中过去 12 个月发布了 11 个;首次发布于 2026/09/08。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。