v0.22

[sxzz]

• This PR contains AI-generated code, but I have carefully reviewed it myself. Otherwise, my PR may be closed.

Description

v0.22 release. Bundles three breaking changes and one new feature.

Changelog

💥 Breaking Changes

• Drop Node.js < 22.18.0 support. engines.node bumped to >=22.18.0 across all packages. The previous deprecation warning has been removed.
• unrun is now an optional peer dependency (was a hard dependency). It is no longer installed automatically — users on the auto config loader who need unrun (i.e. running on Node without native TypeScript support) must install it manually.
• dts auto-enables when compilerOptions.declaration is true in tsconfig.json (feat(dts)!: auto-enable dts when tsconfig declaration is true #872). Previously, dts was only auto-enabled based on package.json fields (types, typings, or exports with types). Tsdown now also reads the tsconfig as a fallback signal.
• exports.bin auto-detects by default when exports is configured (feat(exports): auto-enable bin detection by default #873). Previously, you had to opt in with bin: true. Now leaving bin unset triggers shebang scanning with soft semantics.

✨ Features

• New tsx config loader. Set --config-loader tsx (or configLoader: 'tsx') to load TypeScript configs via tsx's tsImport API. Like unrun, tsx is an optional peer dependency — install it manually if you want to use it.

Migration Guide

Node.js version

Upgrade to Node.js 22.18.0 or later. Bun and Deno remain supported (experimental).

unrun is no longer bundled

If your environment relies on the unrun config loader (i.e. you're on a Node version without native TypeScript support and use the default auto loader), install it manually:

npm i -D unrun
# or, alternatively, the new tsx loader:
npm i -D tsx

If you use Node.js 22.18.0+ with native TypeScript support, no change is needed — the auto loader will pick native.

dts auto-enabled from tsconfig

If your tsconfig.json has compilerOptions.declaration: true but you do not want tsdown to emit .d.ts files, opt out explicitly:

// tsdown.config.ts
export default defineConfig({
  dts: false,
})

exports.bin auto-detection

Any entry chunk containing a shebang (e.g. #!/usr/bin/env node) now causes tsdown to write a bin field in package.json automatically. The semantics differ slightly from explicit bin: true:

Value	Single shebang	Multiple shebangs	No shebangs
(unset)	Auto-set bin	Warn, skip	Silent
true	Auto-set bin	Throw	Warn
false	No bin	No bin	No bin

To opt out entirely:

export default defineConfig({
  exports: { bin: false },
})

Linked Issues

Includes #872, #873.

Additional context

PR body updated with full changelog and migration notes (was previously empty).

[netlify]

✅ Deploy Preview for tsdown-main ready!

Name	Link
🔨 Latest commit	b001818
🔍 Latest deploy log	https://app.netlify.com/projects/tsdown-main/deploys/69f37b57b0e6050008fa9a0e
😎 Deploy Preview	https://deploy-preview-931--tsdown-main.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[pkg-pr-new]

Open in StackBlitz

tsdown

pnpm add https://pkg.pr.new/tsdown@931 -D

npm i https://pkg.pr.new/tsdown@931 -D

yarn add https://pkg.pr.new/tsdown@931.tgz -D

create-tsdown

pnpm add https://pkg.pr.new/create-tsdown@931 -D

npm i https://pkg.pr.new/create-tsdown@931 -D

yarn add https://pkg.pr.new/create-tsdown@931.tgz -D

@tsdown/css

pnpm add https://pkg.pr.new/@tsdown/css@931 -D

npm i https://pkg.pr.new/@tsdown/css@931 -D

yarn add https://pkg.pr.new/@tsdown/css@931.tgz -D

@tsdown/exe

pnpm add https://pkg.pr.new/@tsdown/exe@931 -D

npm i https://pkg.pr.new/@tsdown/exe@931 -D

yarn add https://pkg.pr.new/@tsdown/exe@931.tgz -D

tsdown-migrate

pnpm add https://pkg.pr.new/tsdown-migrate@931 -D

npm i https://pkg.pr.new/tsdown-migrate@931 -D

yarn add https://pkg.pr.new/tsdown-migrate@931.tgz -D

commit: b001818

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	@​vitejs/​devtools@​0.1.15 ⏵ 0.1.16				+2
	rolldown@​1.0.0-rc.17 ⏵ 1.0.0-rc.18
	tinyexec@​1.1.1 ⏵ 1.1.2
	tsx@​4.21.0
	@​typescript/​native-preview@​7.0.0-dev.20260425.1 ⏵ 7.0.0-dev.20260430.1			+1
	postcss@​8.5.10 ⏵ 8.5.12	+1		+1
	@​sxzz/​eslint-config@​7.8.4 ⏵ 8.0.0				-1
	unplugin-vue@​7.1.1 ⏵ 7.2.0	+1			+5
	pkg-types@​2.3.0 ⏵ 2.3.1
	oxc-minify@​0.127.0 ⏵ 0.128.0
	baseline-browser-mapping@​2.10.22 ⏵ 2.10.24
	@​clack/​prompts@​1.2.0 ⏵ 1.3.0	+1		+1

View full report

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Release v0.22 updates focused on Node.js engine requirements and expanding config-loading capabilities (notably adding tsx), while adjusting related packaging metadata and docs.

Changes:

• Bump Node.js engine requirement across packages to >=22.18.0 and refresh related docs.
• Add tsx as a config loader option and handle tsx/unrun as optional peer dependencies.
• Change default exports.bin behavior to implicitly auto-detect shebang entry chunks, with updated tests/docs.

Reviewed changes

Copilot reviewed 20 out of 22 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/utils/general.ts	Removes an eslint disable comment around typeAssert signature.
src/run.ts	Removes Node.js deprecation warning banner.
src/features/pkg/exports.ts	Updates exports.bin docs + changes default auto-detection behavior and error/warn handling.
src/features/pkg/exports.test.ts	Adds coverage for implicit bin auto-detection cases.
src/config/types.ts	Adds tsx to the configLoader union type.
src/config/options.ts	Infers dts from tsconfig declaration setting when present.
src/config/file.ts	Adds tsx loader implementation and switches optional loaders to importWithError.
src/cli.ts	Updates CLI help text to include tsx.
skills/tsdown/references/option-config-file.md	Documents tsx loader and optional peer dependency installs; updates Node requirement text.
skills/tsdown/references/guide-migrate-from-tsup.md	Updates Node requirement text.
skills/tsdown/references/guide-getting-started.md	Updates Node requirement text.
pnpm-workspace.yaml	Adds tsx catalog entry, moves unrun, and updates build allowlist.
packages/migrate/package.json	Bumps Node engine requirement.
packages/exe/package.json	Bumps Node engine requirement.
packages/css/package.json	Bumps Node engine requirement.
packages/create-tsdown/package.json	Bumps Node engine requirement.
package.json	Bumps Node engine requirement; makes tsx/unrun optional peers and removes unrun from deps.
docs/zh-CN/options/config-file.md	Documents tsx loader and optional peer dependency installs; updates Node requirement text.
docs/zh-CN/guide/getting-started.md	Updates Node requirement text and removes deprecation warning block.
docs/options/config-file.md	Documents tsx loader and optional peer dependency installs; updates Node requirement text.
docs/guide/getting-started.md	Updates Node requirement text and removes deprecation warning block.
snapshots/tsnapi/index.snapshot.d.ts	Updates generated types snapshot for configLoader union.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 21 out of 23 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (1)

src/features/pkg/exports.ts:520

• With the new default behavior (bin unset), this branch throws whenever pkg.name is missing, even if no shebang entry is detected and we would otherwise skip bin generation. That’s a behavior change from if (!bin) return and can break builds for unnamed/private packages. Consider deferring the pkg.name requirement until after a shebang has been detected (or only enforcing it for bin: true / string form), and update the error message accordingly.

  if (bin === true || bin === undefined || typeof bin === 'string') {
    if (!pkg.name)
      throw new Error(
        'Package name is required when using string form for `bin`',
      )

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.