Terminal
Terminal/Skill
Builds, watches, and validates Sanity npm libraries using the pkg CLI and its package.json exports.
By Sanity
Works with
npx skills add sanity-io/pkg-utils --skill sanity-pkg-utils@sanity/pkg-utilsUse pkg for conventional Sanity library packages whose authored package.json#exports describe
what to build. @sanity/pkg-utils composes tsdown with @sanity/tsdown-config, adds
browserslist-derived targets and Sanity package conventions, and reconciles generated exports.
For direct tsdown.config.ts builds, install and use the sanity-tsdown-config skill instead.
Use the separate tsdown skill for generic tsdown options.
@sanity/pkg-utils 13.x requires Node.js ^22.18.0 || ^24.11.0 || >=26.0.0.
pnpm add -D @sanity/pkg-utils
Prefer the short pkg binary in scripts; pkg-utils is an alias:
{
"scripts": {
"build": "pkg build --strict --check",
"watch": "pkg watch"
}
}
Useful commands:
pkg build # build once
pkg build --strict # enable configured strict checks
pkg build --check # build, then run pkg check
pkg build --no-clean # preserve dist for this run
pkg build --quiet # show only errors, warnings, and checks
pkg watch # rebuild on source/config changes
pkg check # validate the package without building
pkg init is an interactive raw-TTY command. Do not automate it through piped input; edit or
scaffold package files directly in non-interactive agent environments.
Unlike a bare tsdown project, pkg-utils derives entries, formats, and runtime-specific builds from
the hand-written exports map:
{
"type": "module",
"exports": {
".": {
"source": "./src/index.ts",
"default": "./dist/index.js"
},
"./package.json": "./package.json"
}
}
pkg build keeps local exports source-aware for development and writes publishable,
source-free targets to publishConfig.exports. It does this in CI too. For browser or node
conditions it creates the additional platform builds required by the map.
After changing entries, conditions, formats, type, main, or module, run a full pkg build
and review both export maps. Preserve condition order deliberately: earlier matching conditions
win.
package.config.tspkg build never loads tsdown.config.*. Its only config file is package.config.ts (also
.mts, .js, or .mjs):
import {defineConfig} from '@sanity/pkg-utils'
export default defineConfig({
tsconfig: 'tsconfig.dist.json',
})
Most packages need little configuration because package metadata supplies the entries. Common options include:
tsconfig ('tsconfig.json' by default)dist to override the output directory inferred from authored export targets (commonly dist)clean (true), sourcemap (true), and minify (false for full minification)runtime ('*'), deps, dts, define, and extra Rolldown pluginsreactCompiler, styledComponents, vanillaExtract, css, and bundleAnalyzertsdoc (true)bundles for entry points such as workers or CLIs that are built but not exportedPublic entries come from package.json#exports, not a src config option. process.env.PKG_VERSION
is always replaced with the package version, or with the
PKG_VERSION environment override. Values in define are serialized before forwarding.
pkg-utils starts from @sanity/tsdown-config, so it inherits source maps, compress-only
minification with preserved names, dependency-subpath resolution, and runtime
circular-dependency warnings. The default '*' build uses the wrapper's neutral platform;
browser and node export conditions create matching platform builds instead. pkg-utils then
owns these differences:
'*' build.tsdoc defaults to true for builds and checks, but is skipped in watch mode.publint runs through pkg check, not tsdown's build hook.reactCompiler: true defaults to the Babel implementation for compatibility. Install
babel-plugin-react-compiler. Set {transform: 'oxc'} and install oxc-transform-react to opt
into Oxc.minify: true; the default still performs compression and
dead-code elimination while preserving names.package.json exports, avoiding a watcher loop. Run a full build
after changing package metadata.Do not create both package.config.ts and tsdown.config.ts expecting them to merge. The latter
is ignored by pkg.
Use tsdown's dependency controls:
export default defineConfig({
deps: {
neverBundle: [/^react(\/|$)/],
alwaysBundle: ['small-runtime-helper'],
},
})
Strings match exactly or as globs; use a regular expression to include package subpaths. Type
inlining follows bundling decisions. Declaration generation is enabled for TypeScript entries
unless dts: false; a package with @typescript/native-preview in devDependencies defaults to
the tsgo generator.
Keep a distribution tsconfig focused on publishable source. Declaration generation does not replace a separate type-check command.
reactCompiler and styledComponents are opt-in.reactCompiler.reactServer. Use tsdown with
@sanity/tsdown-config directly for that dual build.vanillaExtract: true emits and conditionally exports bundle.css.css: {...} uses the optional @tsdown/css peer for plain CSS, CSS modules, preprocessors, or
PostCSS and conditionally exports style.css..css export subpath with a source automatically enables the CSS pipeline.sideEffects so consumer tree-shaking does not remove it.Example standalone stylesheet export:
{
"sideEffects": ["*.css"],
"exports": {
"./ui/styles.css": {"source": "./src/ui/styles.css"}
}
}
package.config.ts; pkg-utils discovers public entries
from package.json#exports. Use bundles only for non-exported artifacts.pkg watch as the final package validation. Run pkg build --strict --check so
exports are reconciled and TSDoc/publint checks execute.--no-clean by default. It can leave stale outputs that make package validation
misleading.dist/analyze-data.md from package.json#files.sideEffects for emitted CSS.babel, extract, rollup,
reactCompilerOptions, or jsxImportSource; use the current top-level options.external is deprecated but still supported with a warning. Migrate it to deps.neverBundle
or deps.alwaysBundle.@sanity/tsdown-configStay with pkg when package exports are the desired source of truth and its option surface covers
the build. Switch to tsdown plus @sanity/tsdown-config when you need:
mergeConfigreactCompiler.reactServerDo not bypass pkg-utils merely to gain Sanity's shared defaults; it already composes the wrapper.