@sanity/pkg-utils
Use 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.
Install and run
@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.
Treat exports as the build manifest
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.
Configure with package.config.ts
pkg 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)distto override the output directory inferred from authored export targets (commonlydist)clean(true),sourcemap(true), andminify(falsefor full minification)runtime('*'),deps,dts,define, and extra RolldownpluginsreactCompiler,styledComponents,vanillaExtract,css, andbundleAnalyzertsdoc(true)bundlesfor entry points such as workers or CLIs that are built but not exported
Public 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.
Understand the composed defaults
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:
- The authored exports map decides entries, formats, and browser/node build variants.
- JS targets are derived from the package browserslist (Sanity's browserslist config by default),
split for browser and Node builds and combined for the
'*'build. tsdocdefaults totruefor builds and checks, but is skipped in watch mode.publintruns throughpkg check, not tsdown's build hook.- Per-file tsdown reports are disabled in favor of pkg-utils output.
reactCompiler: truedefaults to the Babel implementation for compatibility. Installbabel-plugin-react-compiler. Set{transform: 'oxc'}and installoxc-transform-reactto opt into Oxc.- Full minification happens only with
minify: true; the default still performs compression and dead-code elimination while preserving names. - Watch mode does not rewrite
package.jsonexports, 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.
Dependencies and declarations
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.
React and CSS
reactCompilerandstyledComponentsare opt-in.- pkg-utils does not support
reactCompiler.reactServer. Use tsdown with@sanity/tsdown-configdirectly for that dual build. vanillaExtract: trueemits and conditionally exportsbundle.css.css: {...}uses the optional@tsdown/csspeer for plain CSS, CSS modules, preprocessors, or PostCSS and conditionally exportsstyle.css.- A
.cssexport subpath with asourceautomatically enables the CSS pipeline. - Add emitted CSS to
sideEffectsso consumer tree-shaking does not remove it.
Example standalone stylesheet export:
{
"sideEffects": ["*.css"],
"exports": {
"./ui/styles.css": {"source": "./src/ui/styles.css"}
}
}
Common pitfalls
- Do not hand-author source entries only in
package.config.ts; pkg-utils discovers public entries frompackage.json#exports. Usebundlesonly for non-exported artifacts. - Do not run
pkg watchas the final package validation. Runpkg build --strict --checkso exports are reconciled and TSDoc/publint checks execute. - Do not use
--no-cleanby default. It can leave stale outputs that make package validation misleading. - Do not fully minify libraries by default. The inherited compression already removes dead code, and preserved names aid debugging.
- Do not publish bundle-analyzer output. Exclude
dist/analyze-data.mdfrompackage.json#files. - Do not forget
sideEffectsfor emitted CSS. - Do not assume declaration bundling type-checks source. Run the repository's type-check command.
- Do not use removed pre-v12 options such as
babel,extract,rollup,reactCompilerOptions, orjsxImportSource; use the current top-level options. externalis deprecated but still supported with a warning. Migrate it todeps.neverBundleordeps.alwaysBundle.
When to use direct @sanity/tsdown-config
Stay 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:
- arbitrary stock tsdown options through
mergeConfig - multiple tsdown configs or programmatic build control
reactCompiler.reactServer- a build whose entries or outputs do not fit pkg-utils' exports-driven model
Do not bypass pkg-utils merely to gain Sanity's shared defaults; it already composes the wrapper.