new-package
Scaffold a new publishable @grafana/* package in the monorepo via the turbo generator, with TypeScript build, vitest, AGENTS.md, and publish config wired up.
- License 许可
- Apache-2.0
- 所属仓库
- torkelo/scenes2
- 最近更新
- 2026-11-14
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- new-package
- metadata
- { "source": ".hatch/_skills/new-package/SKILL.md", "generated": "hatch@v1.2.0" }
- description
- Scaffold a new publishable @grafana/* package in the monorepo via the turbo generator, with TypeScript build, vitest, AGENTS.md, and publish config wired up.
03 SKILL.md 正文
Scaffold new package
Create a new publishable package named @grafana/$ARGUMENTS[0] in the monorepo.
If a description is provided as $ARGUMENTS[1], use that. Otherwise ask the
user for a short description of the package's purpose before proceeding.
Step 1 — Use the turbo generator
The repo ships a package generator that creates everything in one go:
pnpm gen
# pick "package"
# enter the name (without @grafana/)
# enter the description
This produces, under packages/<name>/:
package.json— Apache-2.0,type: module, ESM-only build withtsc,publishConfig: { access: "public" }, vitest devDeptsconfig.json— extends../../tsconfig.base.jsonvitest.config.tssrc/index.ts— empty entry pointREADME.md,CHANGELOG.md,AGENTS.md— populated from templates
The generator is the source of truth — review the templates in
turbo/generators/templates/package/ before deviating from them.
Step 2 — Determine package shape
The generator output is a pure ESM TypeScript build (tsc --build). That
is the right default. If the new package needs more, pick the matching
adjustment:
| Shape | What to change |
|---|---|
| React library | Add "jsx": "react-jsx" to tsconfig.json compilerOptions. Add peerDependencies: { "react": ">=18" } to package.json. Pull in @types/react as a devDep. |
| Dual CJS + ESM | Replace tsc --build with the Rollup pipeline used by @grafana/icons (rollup-plugin-esbuild + rollup-plugin-dts). Update main / module / types / exports per packages/icons/package.json. Refer to the note in the AGENTS.md template. |
| Uses styling | This repo uses @emotion/css. Add it as a runtime dependency, not a peer dep, unless the package is a component library where consumers should provide their own emotion runtime — match what @grafana/components does. |
| Exports CSS | For every .css file exposed via exports, the entry must be a conditional { types, default } pair AND the build must emit a sibling <name>.css.d.ts next to the CSS. Without this, consumers on moduleResolution: "bundler" | "node16" | "nodenext" get TS2307 on the recommended side-effect import. Refer to CSS subpath exports below. |
Do not invent a new build shape — copy from an existing package
(design-tokens, icons, components, prototype) that matches the type
you need.
CSS subpath exports
If the package exports any .css files, two things have to line up:
-
exportsuses the conditional form. Each CSS subpath entry must carry both atypesand adefaultcondition. Examples from the monorepo:// single file "./tokens.css": { "types": "./generated/tokens.css.d.ts", "default": "./generated/tokens.css" } // wildcard "./css/legacy/*.css": { "types": "./dist/css/legacy/*.css.d.ts", "default": "./dist/css/legacy/*.css" } -
The build emits a sibling
<name>.css.d.tsnext to every published.css. The stub is canonical and one line:// Side-effect-only stylesheet. This file exists so that // `import '@grafana/<pkg>/<path>.css'` typechecks // under moduleResolution: "bundler" | "node16" | "nodenext". export {};For an example pipeline, refer to
packages/design-tokens/scripts/postProcessCss.ts(single-file emission),packages/components/scripts/emitCssTypes.ts(sweeps a directory after rollup writes the CSS), orpackages/fonts/scripts/build.ts(inline next to the CSS write). -
The
filesarray publishes the.d.ts. Usually covered for free by adistor matchinggenerated/<dir>entry, but check.
Why this is required: under moduleResolution: "bundler" | "node16" | "nodenext" TypeScript honors the package's exports field and refuses
a wildcard declare module '*.css' shim from the consumer's project.
The recommended side-effect import — import '@grafana/<pkg>/<path>.css';
— would otherwise fail with TS2307 in every modern Vite / esbuild /
Rollup / webpack 5 / Bun project. Shipping a sibling .d.ts makes the
package self-contained.
Step 3 — Install and verify
The generator does not run pnpm install for you.
pnpm install
pnpm turbo run build typecheck lint --filter=@grafana/$ARGUMENTS[0]
If lint fails because there's no source code yet, that's fine. The build and typecheck must pass.
Step 4 — First publish
A brand-new package needs a one-time bootstrap publish before OIDC trusted publishing can be wired up — the package has to exist on npm before the trusted publisher can be configured against it.
The initial-publish skill (/initial-publish) walks through this end-to-end:
generates a stub shape (pnpm gen → "stub"), prompts for the grafanabot
credentials, publishes 0.0.0, prompts to configure the trusted publisher on
npmjs.com, and logs out.
Routine releases after that go through changesets — refer to
docs/RELEASING.md and the /changeset command.
Step 5 — Report
Summarize:
- What was created (package name, shape, file list)
- What adjustments (if any) you made beyond the generator defaults
- Whether the package needs the
initial-publishbootstrap before its first release - Reminder to run
pnpm changesetwhen the first real change is ready
Rules
- pnpm only — never use
npmoryarn. - No per-package TypeScript —
typescriptis a root devDependency. - No per-package ESLint / Prettier configs — these are repo-wide.
- Never manually edit
version— it's owned by changesets. - License is Apache-2.0, not UNLICENSED.
- Run
pnpm installafter creatingpackage.jsonso the workspace link resolves.
04 同仓库更多 Skills
validate-plugin
validate a Grafana plugin using the official Grafana plugin validator
build-plugin
build a Grafana plugin using the standard build process (frontend and backend if applicable)
validate-plugin
暂无简介
build-plugin
暂无简介
stop-slop
Remove AI writing patterns from prose. Use when drafting, editing, or reviewing text to eliminate predictable AI tells.
snag-fixer
Lightweight agent for quick fixes, tweaks, and small improvements. Optimized for single-task focused work without bloating context. Used by snag workflow for sequential fix processing.