├── .editorconfig ├── .gitattributes ├── .github ├── FUNDING.yml ├── ISSUE_TEMPLATE │ ├── bug_report.yml │ ├── config.yml │ ├── feature_request.yml │ └── typo.yml ├── PULL_REQUEST_TEMPLATE.md ├── renovate.json5 └── workflows │ ├── release.yml │ └── tests.yml ├── .gitignore ├── .prettierignore ├── .vscode └── settings.json ├── LICENSE ├── README.md ├── docs ├── .vitepress │ ├── components │ │ ├── HomePage.vue │ │ ├── VideoModal.vue │ │ └── overrides │ │ │ └── vp-hero.vue │ ├── config │ │ ├── index.ts │ │ └── theme.ts │ ├── i18n │ │ ├── composable.ts │ │ ├── translate-map.ts │ │ └── utils.ts │ ├── scripts │ │ └── docs-generate.ts │ └── theme │ │ ├── Layout.vue │ │ ├── custom.css │ │ └── index.ts ├── advanced │ ├── hooks.md │ ├── plugins.md │ ├── programmatic-usage.md │ └── rolldown-options.md ├── guide │ ├── faq.md │ ├── getting-started.md │ ├── index.md │ └── migrate-from-tsup.md ├── index.md ├── options │ ├── cleaning.md │ ├── config-file.md │ ├── dependencies.md │ ├── dts.md │ ├── entry.md │ ├── minification.md │ ├── output-directory.md │ ├── output-format.md │ ├── package-exports.md │ ├── platform.md │ ├── shims.md │ ├── silent-mode.md │ ├── sourcemap.md │ ├── target.md │ ├── tree-shaking.md │ ├── unbundle.md │ └── watch-mode.md ├── public │ ├── lightning-down.svg │ ├── og-image.png │ ├── og-image.svg │ └── tsdown.svg ├── recipes │ └── vue-support.md ├── reference │ ├── cli.md │ ├── config-options.md │ ├── exports-options.md │ ├── type-aliases │ │ ├── Format.md │ │ ├── ModuleTypes.md │ │ └── Sourcemap.md │ └── workspace.md ├── vite.config.ts └── zh-CN │ ├── advanced │ ├── hooks.md │ ├── plugins.md │ ├── programmatic-usage.md │ └── rolldown-options.md │ ├── guide │ ├── faq.md │ ├── getting-started.md │ ├── index.md │ └── migrate-from-tsup.md │ ├── index.md │ ├── options │ ├── cleaning.md │ ├── config-file.md │ ├── dependencies.md │ ├── dts.md │ ├── entry.md │ ├── minification.md │ ├── output-directory.md │ ├── output-format.md │ ├── package-exports.md │ ├── platform.md │ ├── shims.md │ ├── silent-mode.md │ ├── sourcemap.md │ ├── target.md │ ├── tree-shaking.md │ ├── unbundle.md │ └── watch-mode.md │ ├── recipes │ └── vue-support.md │ └── reference │ ├── cli.md │ ├── config-options.md │ ├── exports-options.md │ ├── type-aliases │ ├── Format.md │ ├── ModuleTypes.md │ └── Sourcemap.md │ └── workspace.md ├── eslint.config.js ├── esm-shims.js ├── examples └── simple │ ├── package.json │ ├── src │ └── index.ts │ └── tsdown.config.ts ├── jsr.json ├── package.json ├── pnpm-lock.yaml ├── pnpm-workspace.yaml ├── src ├── cli.ts ├── config.ts ├── features │ ├── attw.ts │ ├── clean.ts │ ├── copy.ts │ ├── entry.ts │ ├── exports.test.ts │ ├── exports.ts │ ├── external.ts │ ├── hooks.ts │ ├── lightningcss.ts │ ├── node-protocol.ts │ ├── output.ts │ ├── publint.ts │ ├── report.ts │ ├── shebang.ts │ ├── shims.ts │ ├── shortcuts.ts │ ├── target.test.ts │ ├── target.ts │ ├── tsconfig.ts │ └── watch.ts ├── index.ts ├── migrate.ts ├── options │ ├── config.ts │ ├── index.ts │ └── types.ts ├── plugins.ts ├── run.ts └── utils │ ├── format.ts │ ├── fs.ts │ ├── general.ts │ ├── lightningcss.test.ts │ ├── lightningcss.ts │ ├── logger.ts │ ├── package.ts │ └── types.ts ├── tests ├── __snapshots__ │ ├── basic.snap.md │ ├── bundle-dts.snap.md │ ├── cjs-import.snap.md │ ├── cjs-interop.snap.md │ ├── custom-extension.snap.md │ ├── cwd-option.snap.md │ ├── entry-structure.snap.md │ ├── env-flag.snap.md │ ├── esm-import.snap.md │ ├── fixed-extension.snap.md │ ├── hooks.snap.md │ ├── iife-and-umd.snap.md │ ├── issues │ │ ├── 206.snap.md │ │ ├── 216.snap.md │ │ ├── 221.snap.md │ │ └── 61.snap.md │ ├── loader-option.snap.md │ ├── minify.snap.md │ ├── noExternal.snap.md │ ├── remove-node-protocol │ │ ├── basic.snap.md │ │ └── w-require-polyfill.snap.md │ ├── resolve-dependency-for-dts.snap.md │ ├── resolve-paths-in-tsconfig.snap.md │ ├── shims │ │ ├── cjs-on-neutral-w-o-shims.snap.md │ │ ├── cjs-on-node-w-o-shims.snap.md │ │ └── esm-on-node.snap.md │ ├── target │ │ ├── css-syntax-lowering.snap.md │ │ ├── js-syntax-lowering.snap.md │ │ ├── unnecessary-css-syntax-lowering.snap.md │ │ └── unnecessary-js-syntax-lowering.snap.md │ ├── unbundle │ │ ├── base-dir.snap.md │ │ └── basic.snap.md │ ├── without-hash-and-filename-conflict.snap.md │ └── workspace-option.snap.md ├── fixtures │ └── issue-206 │ │ ├── .gitignore │ │ ├── package.json │ │ ├── packages │ │ ├── my-langs │ │ │ ├── css.mjs │ │ │ ├── html.mjs │ │ │ └── package.json │ │ ├── my-shiki │ │ │ ├── index.d.mts │ │ │ ├── index.mjs │ │ │ └── package.json │ │ ├── pkg1 │ │ │ ├── package.json │ │ │ ├── src │ │ │ │ └── index.ts │ │ │ └── tsconfig.json │ │ └── pkg2 │ │ │ ├── package.json │ │ │ ├── src │ │ │ └── index.ts │ │ │ ├── tsconfig.json │ │ │ └── tsdown.config.mjs │ │ └── pnpm-workspace.yaml ├── index.test.ts ├── issues.test.ts ├── remove-node-protocol.test.ts ├── shims.test.ts ├── target.test.ts ├── unbundle.test.ts └── utils.ts ├── tsconfig.json ├── tsdown.config.ts ├── typedoc.json ├── uno.config.ts └── vitest.config.ts /.editorconfig: -------------------------------------------------------------------------------- 1 | root = true 2 | 3 | [*] 4 | indent_size = 2 5 | end_of_line = lf 6 | insert_final_newline = true 7 | trim_trailing_whitespace = true 8 | -------------------------------------------------------------------------------- /.gitattributes: -------------------------------------------------------------------------------- 1 | * text=auto eol=lf 2 | -------------------------------------------------------------------------------- /.github/FUNDING.yml: -------------------------------------------------------------------------------- 1 | github: sxzz 2 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/bug_report.yml: -------------------------------------------------------------------------------- 1 | name: 🐞 Bug report 2 | description: Report an issue 3 | type: Bug 4 | labels: [pending triage] 5 | body: 6 | - type: markdown 7 | attributes: 8 | value: | 9 | **Before You Start...** 10 | 11 | This form is only for submitting bug reports. If you have a usage question 12 | or are unsure if this is really a bug, make sure to: 13 | - Read the [docs](https://tsdown.dev/) 14 | - Ask on [GitHub Discussions](https://github.com/rolldown/tsdown/discussions) 15 | 16 | Also try to search for your issue - it may have already been answered or even fixed in the development branch. 17 | However, if you find that an old, closed issue still persists in the latest version, 18 | you should open a new issue using the form below instead of commenting on the old issue. 19 | - type: textarea 20 | id: reproduction-link-or-steps 21 | attributes: 22 | label: Reproduction link or steps 23 | description: | 24 | - Use [StackBlitz](https://stackblitz.com/github/rolldown/tsdown-starter-stackblitz) to create a minimal reproduction and share the link. 25 | - Or provide a minimal repository on GitHub that can reproduce the issue. You could use [this template](https://github.com/rolldown/tsdown-starter-stackblitz). 26 | placeholder: Reproduction link or steps 27 | validations: 28 | required: true 29 | - type: textarea 30 | id: expected 31 | attributes: 32 | label: What is expected? 33 | validations: 34 | required: true 35 | - type: textarea 36 | id: actually-happening 37 | attributes: 38 | label: What is actually happening? 39 | validations: 40 | required: true 41 | - type: textarea 42 | id: additional-comments 43 | attributes: 44 | label: Any additional comments? 45 | description: e.g. some background/context of how you ran into this bug. 46 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/config.yml: -------------------------------------------------------------------------------- 1 | contact_links: 2 | - name: ⁉️ Why and How to make a reproduction? 3 | url: https://antfu.me/posts/why-reproductions-are-required 4 | about: Reproduction is very important for maintainer to help on your issues! 5 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/feature_request.yml: -------------------------------------------------------------------------------- 1 | name: 🚀 New feature proposal 2 | description: Propose a new feature 3 | type: Feature 4 | labels: [enhancement] 5 | body: 6 | - type: markdown 7 | attributes: 8 | value: | 9 | Thanks for your interest in the project and taking the time to fill out this feature report! 10 | - type: textarea 11 | id: feature-description 12 | attributes: 13 | label: Clear and concise description of the problem 14 | description: 'As a developer using VueUse I want [goal / wish] so that [benefit]. If you intend to submit a PR for this issue, tell us in the description. Thanks!' 15 | validations: 16 | required: true 17 | - type: textarea 18 | id: suggested-solution 19 | attributes: 20 | label: Suggested solution 21 | description: 'In module [xy] we could provide following implementation...' 22 | validations: 23 | required: true 24 | - type: textarea 25 | id: alternative 26 | attributes: 27 | label: Alternative 28 | description: Clear and concise description of any alternative solutions or features you've considered. 29 | - type: textarea 30 | id: additional-context 31 | attributes: 32 | label: Additional context 33 | description: Any other context or screenshots about the feature request here. 34 | - type: checkboxes 35 | id: checkboxes 36 | attributes: 37 | label: Validations 38 | description: Before submitting the issue, please make sure you do the following 39 | options: 40 | - label: Follow our [Code of Conduct](https://github.com/sxzz/.github/blob/main/CODE_OF_CONDUCT.md) 41 | required: true 42 | - label: Read the [Contributing Guide](https://github.com/sxzz/contribute). 43 | required: true 44 | - label: Check that there isn't already an issue that request the same feature to avoid creating a duplicate. 45 | required: true 46 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/typo.yml: -------------------------------------------------------------------------------- 1 | name: 👀 Typo / Grammar fix 2 | description: You can just go ahead and send a PR! Thank you! 3 | labels: [] 4 | body: 5 | - type: markdown 6 | attributes: 7 | value: | 8 | ## PR Welcome! 9 | 10 | If the typo / grammar issue is trivial and straightforward, you can help by **directly sending a quick pull request**! 11 | If you spot multiple of them, we suggest combining them into a single PR. Thanks! 12 | - type: textarea 13 | id: context 14 | attributes: 15 | label: Additional context 16 | -------------------------------------------------------------------------------- /.github/PULL_REQUEST_TEMPLATE.md: -------------------------------------------------------------------------------- 1 | 13 | 14 | ### Description 15 | 16 | 17 | 18 | ### Linked Issues 19 | 20 | ### Additional context 21 | 22 | 23 | -------------------------------------------------------------------------------- /.github/renovate.json5: -------------------------------------------------------------------------------- 1 | { 2 | extends: ['github>sxzz/renovate-config'], 3 | automerge: true, 4 | } 5 | -------------------------------------------------------------------------------- /.github/workflows/release.yml: -------------------------------------------------------------------------------- 1 | name: Release 2 | 3 | permissions: 4 | contents: write 5 | 6 | on: 7 | push: 8 | tags: 9 | - 'v*' 10 | 11 | jobs: 12 | release: 13 | name: 🚀 Release 14 | runs-on: ubuntu-latest 15 | steps: 16 | - name: Checkout 17 | uses: actions/checkout@v4 18 | with: 19 | fetch-depth: 0 20 | persist-credentials: true 21 | 22 | - name: Set node 23 | uses: actions/setup-node@v4 24 | with: 25 | node-version: lts/* 26 | 27 | - name: Generate changelog 28 | run: npx changelogithub 29 | env: 30 | GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}} 31 | 32 | # publish-jsr: 33 | # name: Publish JSR 34 | # runs-on: ubuntu-latest 35 | 36 | # permissions: 37 | # contents: read 38 | # id-token: write 39 | 40 | # steps: 41 | # - name: Checkout 42 | # uses: actions/checkout@v4 43 | # with: 44 | # persist-credentials: false 45 | 46 | # - name: Install pnpm 47 | # uses: pnpm/action-setup@v4.1.0 48 | 49 | # - name: Set node 50 | # uses: actions/setup-node@v4 51 | # with: 52 | # node-version: lts/* 53 | # cache: pnpm 54 | 55 | # - name: Install dependencies 56 | # run: pnpm install 57 | 58 | # - name: Publish package 59 | # run: npx jsr publish 60 | -------------------------------------------------------------------------------- /.github/workflows/tests.yml: -------------------------------------------------------------------------------- 1 | name: Tests 2 | 3 | on: 4 | push: 5 | branches: [main] 6 | pull_request: 7 | branches: [main] 8 | 9 | permissions: {} 10 | 11 | jobs: 12 | lint: 13 | name: Lint 14 | runs-on: ubuntu-latest 15 | 16 | steps: 17 | - name: Checkout 18 | uses: actions/checkout@v4 19 | with: 20 | persist-credentials: false 21 | 22 | - name: Install pnpm 23 | uses: pnpm/action-setup@v4.1.0 24 | 25 | - name: Setup node 26 | uses: actions/setup-node@v4 27 | with: 28 | node-version: lts/* 29 | cache: pnpm 30 | 31 | - name: Install dependencies 32 | run: pnpm install 33 | 34 | - name: Lint 35 | run: pnpm run lint 36 | 37 | - name: Typecheck 38 | run: pnpm run typecheck 39 | 40 | test: 41 | name: Unit Tests 42 | strategy: 43 | matrix: 44 | os: [ubuntu-latest, windows-latest] 45 | node: [18, 20, 22, 24] 46 | fail-fast: false 47 | runs-on: ${{ matrix.os }} 48 | 49 | steps: 50 | - name: Checkout 51 | uses: actions/checkout@v4 52 | with: 53 | persist-credentials: false 54 | 55 | - name: Install pnpm 56 | uses: pnpm/action-setup@v4.1.0 57 | 58 | - name: Setup node 59 | uses: actions/setup-node@v4 60 | with: 61 | node-version: ${{ matrix.node }} 62 | cache: pnpm 63 | 64 | - name: Install dependencies 65 | run: pnpm install 66 | 67 | - name: Build 68 | run: pnpm run build 69 | 70 | - name: Test 71 | run: pnpm run test 72 | 73 | publish: 74 | name: Publish Prerelease 75 | runs-on: ubuntu-latest 76 | 77 | steps: 78 | - name: Checkout 79 | uses: actions/checkout@v4 80 | with: 81 | persist-credentials: false 82 | 83 | - name: Install pnpm 84 | uses: pnpm/action-setup@v4.1.0 85 | 86 | - name: Setup node 87 | uses: actions/setup-node@v4 88 | with: 89 | cache: pnpm 90 | 91 | - name: Install dependencies 92 | run: pnpm install 93 | 94 | - name: Build 95 | run: pnpm run build 96 | 97 | - name: Publish prerelease 98 | run: pnpx pkg-pr-new publish --pnpm --compact 99 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | node_modules 2 | dist 3 | 4 | *.log 5 | .DS_Store 6 | .eslintcache 7 | tsdown-*.tgz 8 | 9 | temp 10 | 11 | docs/.vitepress/dist 12 | docs/.vitepress/cache 13 | docs/reference/api 14 | -------------------------------------------------------------------------------- /.prettierignore: -------------------------------------------------------------------------------- 1 | tests/__snapshots__ 2 | -------------------------------------------------------------------------------- /.vscode/settings.json: -------------------------------------------------------------------------------- 1 | { 2 | "editor.formatOnSave": true, 3 | "cSpell.words": ["tsdown"], 4 | "files.readonlyInclude": { 5 | "docs/**/config-options.md": true, 6 | "docs/**/workspace.md": true, 7 | "docs/**/type-aliases/*.md": true 8 | }, 9 | "typescript.tsdk": "node_modules/typescript/lib" 10 | } 11 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | The MIT License (MIT) 2 | 3 | Copyright (c) 2025-present VoidZero Inc. & Contributors 4 | Copyright (c) 2024 三咲智子 Kevin Deng (https://github.com/sxzz) 5 | 6 | Permission is hereby granted, free of charge, to any person obtaining a copy 7 | of this software and associated documentation files (the "Software"), to deal 8 | in the Software without restriction, including without limitation the rights 9 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 10 | copies of the Software, and to permit persons to whom the Software is 11 | furnished to do so, subject to the following conditions: 12 | 13 | The above copyright notice and this permission notice shall be included in all 14 | copies or substantial portions of the Software. 15 | 16 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 17 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 18 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 19 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 20 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 21 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 22 | SOFTWARE. 23 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | tsdown
2 | 3 | # tsdown [![npm](https://img.shields.io/npm/v/tsdown.svg)](https://npmjs.com/package/tsdown) [![Unit Test](https://github.com/rolldown/tsdown/actions/workflows/tests.yml/badge.svg)](https://github.com/rolldown/tsdown/actions/workflows/tests.yml) [![JSR](https://jsr.io/badges/@sxzz/tsdown)](https://jsr.io/@sxzz/tsdown) [![tsdown-starter-stackblitz](https://developer.stackblitz.com/img/open_in_stackblitz_small.svg)](https://stackblitz.com/github/rolldown/tsdown-starter-stackblitz) 4 | 5 | ✨ The elegant bundler for libraries powered by [Rolldown](https://github.com/rolldown/rolldown). 6 | 7 | ## Features 8 | 9 | - 🚀 **Blazing fast**: Build and generate declaration files powered by Oxc and Rolldown, incredibly fast! 10 | - ♻️ **Powerful ecosystem**: Support Rollup, Rolldown, unplugin plugins, and some Vite plugins. 11 | - ️🛠️ **Easy to use**: tsdown preconfigures everything you need to get started, so you can focus on writing code. 12 | - 🔄 **Seamless migration**: Compatible with tsup's main options and features, ensuring a smooth transition. 13 | 14 | ## Documentation 15 | 16 | For full documentation, visit [tsdown.dev](https://tsdown.dev). 17 | 18 | ## Install 19 | 20 | ```bash 21 | npm i -D tsdown 22 | ``` 23 | 24 | ## Usage 25 | 26 | ```bash 27 | npx tsdown 28 | ``` 29 | 30 | ## Migrate from tsup 31 | 32 | ```bash 33 | npx tsdown migrate 34 | ``` 35 | 36 | Please make sure to commit your changes before migrating. For more details, see the [Migration Guide](https://tsdown.dev/guide/migrate-from-tsup). 37 | 38 | ## Credits 39 | 40 | This project also partially contains code derived or copied from the following projects: 41 | 42 | - [tsup](https://github.com/egoist/tsup) 43 | - [pkgroll](https://github.com/privatenumber/pkgroll) 44 | 45 | ## Sponsors 46 | 47 |

48 | 49 | 50 | 51 |

52 | 53 | ## Licenses 54 | 55 | This project is licensed under the [MIT License](LICENSE). 56 | -------------------------------------------------------------------------------- /docs/.vitepress/components/HomePage.vue: -------------------------------------------------------------------------------- 1 | 15 | 16 | 44 | 45 | 61 | -------------------------------------------------------------------------------- /docs/.vitepress/config/index.ts: -------------------------------------------------------------------------------- 1 | import { fileURLToPath } from 'node:url' 2 | import { defineConfig } from 'vitepress' 3 | import { groupIconMdPlugin } from 'vitepress-plugin-group-icons' 4 | import { getLocaleConfig } from './theme' 5 | 6 | // https://vitepress.dev/reference/site-config 7 | export default defineConfig({ 8 | locales: { 9 | root: getLocaleConfig('en'), 10 | 'zh-CN': getLocaleConfig('zh-CN'), 11 | }, 12 | 13 | lastUpdated: true, 14 | cleanUrls: true, 15 | themeConfig: { 16 | search: { 17 | provider: 'local', 18 | options: { 19 | locales: { 20 | 'zh-CN': { 21 | translations: { 22 | button: { 23 | buttonText: '搜索文档', 24 | buttonAriaLabel: '搜索文档', 25 | }, 26 | modal: { 27 | noResultsText: '无法找到相关结果', 28 | resetButtonTitle: '清除查询条件', 29 | footer: { 30 | selectText: '选择', 31 | navigateText: '切换', 32 | closeText: '关闭', 33 | }, 34 | }, 35 | }, 36 | }, 37 | }, 38 | }, 39 | }, 40 | }, 41 | 42 | markdown: { 43 | config(md) { 44 | md.use(groupIconMdPlugin) 45 | }, 46 | }, 47 | 48 | vite: { 49 | resolve: { 50 | alias: [ 51 | { 52 | find: /^.*\/VPHero\.vue$/, 53 | replacement: fileURLToPath( 54 | new URL('../components/overrides/vp-hero.vue', import.meta.url), 55 | ), 56 | }, 57 | ], 58 | }, 59 | }, 60 | }) 61 | -------------------------------------------------------------------------------- /docs/.vitepress/i18n/composable.ts: -------------------------------------------------------------------------------- 1 | import { useData } from 'vitepress' 2 | import { t } from './utils' 3 | 4 | export function useTranslate(lang?: string) { 5 | const { lang: vpLang } = useData() 6 | return (key: string) => t(key, lang || vpLang.value) 7 | } 8 | -------------------------------------------------------------------------------- /docs/.vitepress/i18n/translate-map.ts: -------------------------------------------------------------------------------- 1 | export const zhCN = { 2 | // nav 3 | Home: '首页', 4 | Guide: '指南', 5 | 'API Reference': 'API 参考', 6 | 7 | // sidebar 8 | Introduction: '介绍', 9 | 'Getting Started': '快速上手', 10 | 'Migrate from tsup': ' 从 tsup 迁移', 11 | 12 | Options: '选项', 13 | Entry: '入口文件', 14 | Cleaning: '清理', 15 | Dependencies: '依赖', 16 | 'Config File': '配置文件', 17 | Minification: '压缩', 18 | 'Output Directory': '输出目录', 19 | 'Output Format': '输出格式', 20 | Platform: '运行平台（Platform）', 21 | 'Silent Mode': '静默模式', 22 | 'Source Maps': '源映射（Source Maps）', 23 | Target: '构建目标（Target）', 24 | 'Tree-shaking': '除屑优化（Tree-shaking）', 25 | 'Watch Mode': '监听模式', 26 | Shims: '兼容代码（Shims）', 27 | 'Declaration Files (dts)': '声明文件（dts）', 28 | 'Package Exports': '包导出（Package Exports）', 29 | Unbundle: '非打包模式（Unbundle）', 30 | 31 | Recipes: '实践指南', 32 | 'Vue Support': 'Vue 支持', 33 | 34 | Advanced: '高级功能', 35 | 'Rolldown Options': 'Rolldown 选项', 36 | Plugins: '插件', 37 | Hooks: '钩子（Hooks）', 38 | 'Programmatic Usage': '编程使用', 39 | FAQ: '常见问题', 40 | 41 | 'Config Options': '配置选项', 42 | 'Command Line Interface': '命令行接口', 43 | 44 | 'The Elegant Bundler for Libraries': '优雅的库打包器', 45 | 46 | English: '简体中文', 47 | en: 'zh-CN', 48 | } 49 | 50 | export const translateMap: Record> = { 51 | 'zh-CN': zhCN, 52 | } 53 | -------------------------------------------------------------------------------- /docs/.vitepress/i18n/utils.ts: -------------------------------------------------------------------------------- 1 | import { translateMap } from './translate-map' 2 | 3 | export function t(key: string, lang: string) { 4 | return translateMap[lang]?.[key] || key 5 | } 6 | 7 | export function createTranslate(lang: string) { 8 | return (key: string) => t(key, lang) 9 | } 10 | -------------------------------------------------------------------------------- /docs/.vitepress/theme/Layout.vue: -------------------------------------------------------------------------------- 1 | 5 | 6 | 13 | -------------------------------------------------------------------------------- /docs/.vitepress/theme/custom.css: -------------------------------------------------------------------------------- 1 | :root { 2 | --vp-c-brand-1: #ff7e17; 3 | --vp-c-brand-2: #ff8700; 4 | --vp-c-brand-3: #e37800; 5 | --vp-code-color: #333; 6 | --vp-button-brand-bg: #ff7e17; 7 | 8 | /* Hero Background Image */ 9 | --vp-home-hero-image-background-image: linear-gradient( 10 | -45deg, 11 | rgba(255, 149, 0, 0.4) 40%, 12 | rgba(48, 115, 122, 0.2) 50% 13 | ); 14 | --vp-home-hero-image-filter: blur(44px); 15 | 16 | --vp-home-hero-name-color: transparent; 17 | --vp-home-hero-name-background: -webkit-linear-gradient( 18 | 90deg, 19 | #ff7e17, 20 | rgb(84, 218, 233) 21 | ); 22 | } 23 | 24 | .dark { 25 | --vp-code-color: #fff; 26 | } 27 | -------------------------------------------------------------------------------- /docs/.vitepress/theme/index.ts: -------------------------------------------------------------------------------- 1 | import DefaultTheme from 'vitepress/theme' 2 | import Layout from './Layout.vue' 3 | 4 | import './custom.css' 5 | import 'virtual:group-icons.css' 6 | import 'uno.css' 7 | 8 | export default { 9 | ...DefaultTheme, 10 | Layout, 11 | } 12 | -------------------------------------------------------------------------------- /docs/advanced/hooks.md: -------------------------------------------------------------------------------- 1 | # Hooks 2 | 3 | Inspired by [unbuild](https://github.com/unjs/unbuild), `tsdown` supports a flexible hooks system that allows you to extend and customize the build process. While we recommend using the [plugin system](./plugins.md) for most build-related extensions, hooks provide a convenient way to inject Rolldown plugins or perform additional tasks at specific stages of the build lifecycle. 4 | 5 | ## Usage 6 | 7 | You can define hooks in your configuration file in two ways: 8 | 9 | ### Passing an Object 10 | 11 | Define your hooks as an object, where each key is a hook name and the value is a function: 12 | 13 | ```ts [tsdown.config.ts] 14 | import { defineConfig } from 'tsdown' 15 | 16 | export default defineConfig({ 17 | hooks: { 18 | 'build:done': async () => { 19 | await doSomething() 20 | }, 21 | }, 22 | }) 23 | ``` 24 | 25 | ### Passing a Function 26 | 27 | Alternatively, you can pass a function that receives the hooks object, allowing you to register hooks programmatically: 28 | 29 | ```ts [tsdown.config.ts] 30 | import { defineConfig } from 'tsdown' 31 | 32 | export default defineConfig({ 33 | hooks(hooks) { 34 | hooks.hook('build:prepare', () => { 35 | console.log('Hello World') 36 | }) 37 | }, 38 | }) 39 | ``` 40 | 41 | For more details on how to use the hooks, refer to the [hookable](https://github.com/unjs/hookable) documentation. 42 | 43 | ## Available Hooks 44 | 45 | For detailed type definitions, see [`src/features/hooks.ts`](https://github.com/rolldown/tsdown/blob/main/src/features/hooks.ts). 46 | 47 | ### `build:prepare` 48 | 49 | Invoked before each tsdown build starts. Use this hook to perform setup or preparation tasks. 50 | 51 | ### `build:before` 52 | 53 | Invoked before each Rolldown build. For dual-format builds, this hook is called for each format. Useful for configuring or modifying the build context before bundling. 54 | 55 | ### `build:done` 56 | 57 | Invoked after each tsdown build completes. Use this hook for cleanup or post-processing tasks. 58 | -------------------------------------------------------------------------------- /docs/advanced/plugins.md: -------------------------------------------------------------------------------- 1 | # Plugins 2 | 3 | `tsdown` uses [Rolldown](https://rolldown.rs) as its core engine, which means it seamlessly supports Rolldown plugins. Plugins are a powerful way to extend and customize the bundling process, enabling features like code transformation, asset handling, and more. 4 | 5 | ## Supported Plugin Ecosystems 6 | 7 | ### Rolldown Plugins 8 | 9 | Since `tsdown` is built on Rolldown, it supports all Rolldown plugins. You can use any plugin designed for Rolldown to enhance your build process. 10 | 11 | ### Unplugin 12 | 13 | [Unplugin](https://unplugin.unjs.io/) is a modern plugin framework that supports multiple bundlers, including Rolldown. Most Unplugin plugins (commonly named with the `unplugin-` prefix) work seamlessly with `tsdown`. 14 | 15 | ### Rollup Plugins 16 | 17 | Rolldown is highly compatible with Rollup's plugin API, so `tsdown` can use most Rollup plugins without modification. This gives you access to a wide range of existing plugins in the Rollup ecosystem. 18 | 19 | > [!NOTE] Type Compatibility 20 | > Rollup plugins may sometimes cause TypeScript type errors because the Rollup and Rolldown plugin APIs are not 100% compatible. If you encounter type errors when using Rollup plugins, you can safely ignore them by using `// @ts-expect-error` or casting the plugin as `any`: 21 | > 22 | > ```ts 23 | > import SomeRollupPlugin from 'some-rollup-plugin' 24 | > export default defineConfig({ 25 | > plugins: [SomeRollupPlugin() as any], 26 | > }) 27 | > ``` 28 | 29 | ### Vite Plugins 30 | 31 | Vite plugins may work with `tsdown` if they do not rely on Vite-specific internal APIs or behaviors. However, plugins that depend heavily on Vite's internals may not be compatible. We plan to improve support for Vite plugins in the future. 32 | 33 | > [!NOTE] Type Compatibility 34 | > Similarly, Vite plugins may also cause type errors due to API differences. You can use `// @ts-expect-error` or `as any` to suppress these errors if needed. 35 | 36 | ## How to Use Plugins 37 | 38 | To use plugins in `tsdown`, you need to add them to the `plugins` array in your configuration file. Plugins **cannot** be added via the CLI. 39 | 40 | Here’s an example of how to use a plugin: 41 | 42 | ```ts [tsdown.config.ts] 43 | import SomePlugin from 'some-plugin' 44 | import { defineConfig } from 'tsdown' 45 | 46 | export default defineConfig({ 47 | plugins: [SomePlugin()], 48 | }) 49 | ``` 50 | 51 | For specific plugin usage, refer to the plugin's own documentation. 52 | 53 | ## Writing Your Own Plugins 54 | 55 | If you want to create a custom plugin for `tsdown`, you can follow Rolldown's plugin development guide. Rolldown's plugin API is highly flexible and similar to Rollup's, making it easy to get started. 56 | 57 | Refer to the [Rolldown Plugin Development Guide](https://rolldown.rs/guide/plugin-development) for detailed instructions on writing your own plugins. 58 | 59 | > [!TIP] 60 | > Plugins are a great way to extend `tsdown`'s functionality. Whether you're using existing plugins or creating your own, they allow you to tailor the bundling process to your project's specific needs. 61 | -------------------------------------------------------------------------------- /docs/advanced/programmatic-usage.md: -------------------------------------------------------------------------------- 1 | # Programmatic Usage 2 | 3 | You can use `tsdown` directly from your JavaScript or TypeScript code. This is useful for custom build scripts, integrations, or advanced automation. 4 | 5 | ## Example 6 | 7 | ```ts 8 | import { build } from 'tsdown' 9 | 10 | await build({ 11 | entry: ['src/index.ts'], 12 | format: ['esm', 'cjs'], 13 | outDir: 'dist', 14 | dts: true, 15 | // ...any other options 16 | }) 17 | ``` 18 | 19 | All CLI options are available as properties in the options object. See [Config Options](../reference/config-options.md) for the full list. 20 | -------------------------------------------------------------------------------- /docs/advanced/rolldown-options.md: -------------------------------------------------------------------------------- 1 | # Customizing Rolldown Options 2 | 3 | `tsdown` uses [Rolldown](https://rolldown.rs) as its core bundling engine. This allows you to easily pass or override options directly to Rolldown, giving you fine-grained control over the bundling process. 4 | 5 | For a full list of available Rolldown options, refer to the [Rolldown Config Options](https://rolldown.rs/reference/config-options) documentation. 6 | 7 | ## Overriding `inputOptions` 8 | 9 | You can override the `inputOptions` generated by `tsdown` to customize how Rolldown processes your input files. There are two ways to do this: 10 | 11 | ### Using an Object 12 | 13 | You can directly pass an object to override specific `inputOptions`: 14 | 15 | ```ts [tsdown.config.ts] 16 | import { defineConfig } from 'tsdown' 17 | 18 | export default defineConfig({ 19 | inputOptions: { 20 | cwd: './custom-directory', 21 | }, 22 | }) 23 | ``` 24 | 25 | In this example, the `cwd` (current working directory) option is set to `./custom-directory`. 26 | 27 | ### Using a Function 28 | 29 | Alternatively, you can use a function to dynamically modify the `inputOptions`. The function receives the generated `inputOptions` and the current `format` as arguments: 30 | 31 | ```ts [tsdown.config.ts] 32 | import { defineConfig } from 'tsdown' 33 | 34 | export default defineConfig({ 35 | inputOptions(inputOptions, format) { 36 | inputOptions.cwd = './custom-directory' 37 | return inputOptions 38 | }, 39 | }) 40 | ``` 41 | 42 | This approach is useful when you need to customize options based on the output format or other dynamic conditions. 43 | 44 | ## Overriding `outputOptions` 45 | 46 | The `outputOptions` can be customized in the same way as `inputOptions`. For example: 47 | 48 | ### Using an Object 49 | 50 | You can directly pass an object to override specific `outputOptions`: 51 | 52 | ```ts [tsdown.config.ts] 53 | import { defineConfig } from 'tsdown' 54 | 55 | export default defineConfig({ 56 | outputOptions: { 57 | comments: 'preserve-legal', 58 | }, 59 | }) 60 | ``` 61 | 62 | In this example, the `comments: 'preserve-legal'` option ensures that legal comments (e.g., license headers) are preserved in the output files. 63 | 64 | ### Using a Function 65 | 66 | You can also use a function to dynamically modify the `outputOptions`. The function receives the generated `outputOptions` and the current `format` as arguments: 67 | 68 | ```ts [tsdown.config.ts] 69 | import { defineConfig } from 'tsdown' 70 | 71 | export default defineConfig({ 72 | outputOptions(outputOptions, format) { 73 | if (format === 'esm') { 74 | outputOptions.comments = 'preserve-legal' 75 | } 76 | return outputOptions 77 | }, 78 | }) 79 | ``` 80 | 81 | This ensures that legal comments are preserved only for the `esm` format. 82 | 83 | ## When to Use Custom Options 84 | 85 | While `tsdown` exposes many common options directly, there may be cases where certain Rolldown options are not exposed. In such cases, you can use the `inputOptions` and `outputOptions` overrides to directly set these options in Rolldown. 86 | 87 | > [!TIP] 88 | > Using `inputOptions` and `outputOptions` gives you full access to Rolldown's powerful configuration system, allowing you to customize your build process beyond what `tsdown` exposes directly. 89 | -------------------------------------------------------------------------------- /docs/guide/faq.md: -------------------------------------------------------------------------------- 1 | # Frequently Asked Questions 2 | 3 | 8 | 9 | ## Will tsdown support stub mode (similar to unbuild)? {#stub-mode} 10 | 11 | Currently, `tsdown` does **not** support stub mode, and there are no immediate plans to add it. In today's ecosystem, we believe that a simple stub mode offers limited practical value for most library development workflows. Instead, we recommend using [watch mode](../options/watch-mode.md) for a fast and efficient development experience. For a more detailed explanation of this decision, please see [this GitHub comment](https://github.com/rolldown/tsdown/pull/164#issuecomment-2849720617). 12 | 13 | While stub mode is not supported at this time, we may revisit this decision in the future if the ecosystem evolves and the need becomes more compelling. 14 | -------------------------------------------------------------------------------- /docs/guide/index.md: -------------------------------------------------------------------------------- 1 | # Introduction 2 | 3 | **tsdown** is _The Elegant Library Bundler_. Designed with simplicity and speed in mind, it provides a seamless and efficient way to bundle your TypeScript and JavaScript libraries. Whether you're building a small utility or a complex library, `tsdown` empowers you to focus on your code while it handles the bundling process with elegance. 4 | 5 | ## Why tsdown? 6 | 7 | `tsdown` is built on top of [Rolldown](https://rolldown.rs), a cutting-edge bundler written in Rust. While Rolldown is a powerful and general-purpose tool, `tsdown` takes it a step further by providing a **complete out-of-the-box solution** for library authors. 8 | 9 | ### Key Differences Between tsdown and Rolldown 10 | 11 | - **Simplified Configuration**: `tsdown` minimizes the need for complex configurations by offering sensible defaults tailored for library development. It provides a streamlined experience, so you can focus on your code rather than the bundling process. 12 | - **Library-Specific Features**: Unlike Rolldown, which is designed as a general-purpose bundler, `tsdown` is optimized specifically for building libraries. It includes features like automatic TypeScript declaration generation and multiple output formats. 13 | - **Future-Ready**: As an **official project of Rolldown**, `tsdown` is deeply integrated into its ecosystem and will continue to evolve alongside it. By leveraging Rolldown's latest advancements, `tsdown` aims to explore new possibilities for library development. Furthermore, `tsdown` is positioned to become the **foundation for [Rolldown Vite](https://github.com/vitejs/rolldown-vite)'s Library Mode**, ensuring a cohesive and robust experience for library authors in the long term. 14 | 15 | ## Plugin Ecosystem 16 | 17 | `tsdown` supports the entire Rolldown plugin ecosystem, making it easy to extend and customize your build process. Additionally, it is compatible with most Rollup plugins, giving you access to a vast library of existing tools. 18 | 19 | For more details, refer to the [Plugins](../advanced/plugins.md) documentation. 20 | 21 | ## What Can It Bundle? 22 | 23 | `tsdown` is designed to handle all the essentials for modern library development: 24 | 25 | - **TypeScript and JavaScript**: Seamlessly bundle `.ts` and `.js` files with support for modern syntax and features. 26 | - **TypeScript Declarations**: Automatically generate declaration files (`.d.ts`) for your library. 27 | - **Multiple Output Formats**: Generate `esm`, `cjs`, and `iife` bundles to ensure compatibility across different environments. 28 | - **Assets**: Include and process non-code assets like `.json` or `.wasm` files. 29 | 30 | With its built-in support for [tree shaking](../options/tree-shaking.md), [minification](../options/minification.md), and [source maps](../options/sourcemap.md), `tsdown` ensures your library is optimized for production. 31 | 32 | ## Fast and Elegant 33 | 34 | `tsdown` is built to be **fast**. Leveraging Rolldown's Rust-based performance, it delivers blazing-fast builds even for large projects. At the same time, it is **elegant**—offering a clean and intuitive configuration system that minimizes boilerplate and maximizes productivity. 35 | 36 | ## Getting Started 37 | 38 | Ready to dive in? Check out the [Getting Started](./getting-started.md) guide to set up your first project with `tsdown`. 39 | 40 | Want to use tsdown from your own scripts? See [Programmatic Usage](../advanced/programmatic-usage.md). 41 | 42 | ## Credits 43 | 44 | `tsdown` is made possible by the open-source community and the many innovative tools in the JavaScript and TypeScript ecosystem. We extend our gratitude to all contributors and maintainers whose work has laid the foundation for this project. 45 | 46 | ### Prior Arts 47 | 48 | - **Rollup**: Provided the original inspiration for modern JavaScript bundling and a robust plugin system. 49 | - **esbuild**: Demonstrated the power of fast, native bundling and influenced the pursuit of performance in build tools. 50 | - **tsup**: Inspired the out-of-the-box developer experience and many CLI options, as well as some implementation details. 51 | - **unbuild**: Inspired the flexible hooks system now available in tsdown. 52 | - **Rolldown**: Serves as the high-performance, Rust-based core engine that powers tsdown and enables many of its advanced features. 53 | -------------------------------------------------------------------------------- /docs/guide/migrate-from-tsup.md: -------------------------------------------------------------------------------- 1 | # Migrate from tsup 2 | 3 | [tsup](https://tsup.egoist.dev/) is a powerful and widely-used bundler that shares many similarities with `tsdown`. While `tsup` is built on top of [esbuild](https://esbuild.github.io/), `tsdown` leverages the power of [Rolldown](https://rolldown.rs/) to deliver a **faster** and more **powerful** bundling experience. 4 | 5 | ## Migration Guide 6 | 7 | If you're currently using `tsup` and want to migrate to `tsdown`, the process is straightforward thanks to the dedicated `migrate` command: 8 | 9 | ```bash 10 | npx tsdown migrate 11 | ``` 12 | 13 | > [!WARNING] 14 | > Please save your changes before migration. The migration process may modify your configuration files, so it's important to ensure all your changes are committed or backed up beforehand. 15 | 16 | ### Migration Options 17 | 18 | The `migrate` command supports the following options to customize the migration process: 19 | 20 | - `--cwd ` (or `-c`): Specify the working directory for the migration. 21 | - `--dry-run` (or `-d`): Perform a dry run to preview the migration without making any changes. 22 | 23 | With these options, you can easily tailor the migration process to fit your specific project setup. 24 | 25 | ## Differences from tsup 26 | 27 | While `tsdown` aims to be highly compatible with `tsup`, there are some differences to be aware of: 28 | 29 | ### Default Values 30 | 31 | - **`format`**: Defaults to `esm`. 32 | - **`clean`**: Enabled by default and will clean the `outDir` before each build. 33 | - **`dts`**: Automatically enabled if your `package.json` contains a `typings` or `types` field. 34 | - **`target`**: By default, reads from the `engines.node` field in your `package.json` if available. 35 | 36 | ### Feature Gaps 37 | 38 | Some features available in `tsup` are not yet implemented in `tsdown`. If you find an option missing that you need, please [open an issue](https://github.com/rolldown/tsdown/issues) to let us know your requirements. 39 | 40 | Please review your configuration after migration to ensure it matches your expectations. 41 | 42 | ## Acknowledgements 43 | 44 | `tsdown` would not have been possible without the inspiration and contributions of the open-source community. We would like to express our heartfelt gratitude to the following: 45 | 46 | - **[tsup](https://tsup.egoist.dev/)**: `tsdown` was heavily inspired by `tsup`, and even incorporates parts of its codebase. The simplicity and efficiency of `tsup` served as a guiding light during the development of `tsdown`. 47 | - **[@egoist](https://github.com/egoist)**: The creator of `tsup`, whose work has significantly influenced the JavaScript and TypeScript tooling ecosystem. Thank you for your dedication and contributions to the community. 48 | -------------------------------------------------------------------------------- /docs/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | # https://vitepress.dev/reference/default-theme-home-page 3 | layout: home 4 | 5 | hero: 6 | name: 'tsdown' 7 | text: 'The Elegant
Library Bundler' 8 | tagline: Powered by Rolldown 9 | image: 10 | src: /tsdown.svg 11 | alt: tsdown 12 | actions: 13 | - text: What is tsdown? 14 | openVideoModal: true 15 | - theme: brand 16 | text: Get Started 17 | link: /guide/ 18 | - theme: alt 19 | text: API Reference 20 | link: /reference/config-options.md 21 | 22 | features: 23 | - icon: 🚀 24 | title: Blazing fast 25 | details: | 26 | Build and generate declaration files powered by Oxc and Rolldown, incredibly fast! 27 | 28 | - icon: ♻️ 29 | title: Powerful ecosystem 30 | details: Support Rollup, Rolldown, unplugin plugins, and some Vite plugins. 31 | 32 | - icon: ️🛠️ 33 | title: Easy to use 34 | details: | 35 | tsdown preconfigures everything you need to get started, so you can focus on writing code. 36 | 37 | - icon: 🔄 38 | title: Seamless migration 39 | details: | 40 | Compatible with tsup's main options and features, ensuring a smooth transition. 41 | --- 42 | -------------------------------------------------------------------------------- /docs/options/cleaning.md: -------------------------------------------------------------------------------- 1 | # Cleaning 2 | 3 | By default, `tsdown` will **clean the output directory** (`outDir`) before each build. This ensures that any files from previous builds are removed, preventing outdated or unused files from remaining in your output. 4 | 5 | If you want to disable this behavior and keep existing files in the output directory, you can use the `--no-clean` option: 6 | 7 | ```bash 8 | tsdown --no-clean 9 | ``` 10 | 11 | > [!NOTE] 12 | > By default, all files in the output directory will be removed before the build process begins. Make sure this behavior aligns with your project requirements to avoid accidentally deleting important files. 13 | -------------------------------------------------------------------------------- /docs/options/config-file.md: -------------------------------------------------------------------------------- 1 | # Config File 2 | 3 | By default, `tsdown` will search for a configuration file by looking in the current working directory and traversing upward through parent directories until it finds one. It supports the following file names: 4 | 5 | - `tsdown.config.ts` 6 | - `tsdown.config.mts` 7 | - `tsdown.config.cts` 8 | - `tsdown.config.js` 9 | - `tsdown.config.mjs` 10 | - `tsdown.config.cjs` 11 | - `tsdown.config.json` 12 | - `tsdown.config` 13 | 14 | Additionally, you can define your configuration directly in the `tsdown` field of your `package.json` file. 15 | 16 | ## Writing a Config File 17 | 18 | The configuration file allows you to define and customize your build settings in a centralized and reusable way. Below is a simple example of a `tsdown` configuration file: 19 | 20 | ```ts [tsdown.config.ts] 21 | import { defineConfig } from 'tsdown/config' 22 | 23 | export default defineConfig({ 24 | entry: 'src/index.ts', 25 | }) 26 | ``` 27 | 28 | ### Building Multiple Outputs 29 | 30 | `tsdown` also supports returning an **array of configurations** from the config file. This allows you to build multiple outputs with different settings in a single run. For example: 31 | 32 | ```ts [tsdown.config.ts] 33 | import { defineConfig } from 'tsdown/config' 34 | 35 | export default [ 36 | defineConfig({ 37 | entry: 'src/entry1.ts', 38 | platform: 'node', 39 | }), 40 | defineConfig({ 41 | entry: 'src/entry2.ts', 42 | platform: 'browser', 43 | }), 44 | ] 45 | ``` 46 | 47 | ## Specifying a Custom Config File 48 | 49 | If your configuration file is located elsewhere or has a different name, you can specify its path using the `--config` (or `-c`) option: 50 | 51 | ```bash 52 | tsdown --config ./path/to/config 53 | ``` 54 | 55 | ## Disabling the Config File {#disable-config-file} 56 | 57 | To disable loading a configuration file entirely, use the `--no-config` option: 58 | 59 | ```bash 60 | tsdown --no-config 61 | ``` 62 | 63 | This is useful if you want to rely solely on command-line options or default settings. 64 | 65 | ## Extending Vite or Vitest Config (Experimental) 66 | 67 | `tsdown` provides an **experimental** feature to extend your existing Vite or Vitest configuration files. This allows you to reuse specific configuration options, such as `resolve` and `plugins`, while ignoring others that are not relevant to `tsdown`. 68 | 69 | To enable this feature, use the `--from-vite` option: 70 | 71 | ```bash 72 | tsdown --from-vite # Load vite.config.* 73 | tsdown --from-vite vitest # Load vitest.config.* 74 | ``` 75 | 76 | > [!WARNING] 77 | > This feature is **experimental** and may not support all Vite or Vitest configuration options. Only specific options, such as `resolve` and `plugins`, are reused. Use with caution and test thoroughly in your project. 78 | 79 | > [!TIP] 80 | > Extending Vite or Vitest configurations can save time and effort if your project already uses these tools, allowing you to build upon your existing setup without duplicating configuration. 81 | 82 | ## Reference 83 | 84 | For a full list of available configuration options, refer to the [Config Options Reference](../reference/config-options.md). This includes detailed explanations of all supported fields and their usage. 85 | -------------------------------------------------------------------------------- /docs/options/dependencies.md: -------------------------------------------------------------------------------- 1 | # Dependencies 2 | 3 | When bundling with `tsdown`, dependencies are handled intelligently to ensure your library remains lightweight and easy to consume. Here’s how `tsdown` processes different types of dependencies and how you can customize this behavior. 4 | 5 | ## Default Behavior 6 | 7 | ### `dependencies` and `peerDependencies` 8 | 9 | By default, `tsdown` **does not bundle dependencies** listed in your `package.json` under `dependencies` and `peerDependencies`: 10 | 11 | - **`dependencies`**: These are treated as external and will not be included in the bundle. Instead, they will be installed automatically by npm (or other package managers) when your library is installed. 12 | - **`peerDependencies`**: These are also treated as external. Users of your library are expected to install these dependencies manually, although some package managers may handle this automatically. 13 | 14 | ### `devDependencies` and Phantom Dependencies 15 | 16 | - **`devDependencies`**: Dependencies listed under `devDependencies` in your `package.json` will **only be bundled if they are actually imported or required by your source code**. 17 | - **Phantom Dependencies**: Dependencies that exist in your `node_modules` folder but are not explicitly listed in your `package.json` will **only be bundled if they are actually used in your code**. 18 | 19 | In other words, only the `devDependencies` and phantom dependencies that are actually referenced in your project will be included in the bundle. 20 | 21 | ## Customizing Dependency Handling 22 | 23 | `tsdown` provides two options to override the default behavior: 24 | 25 | ### `external` 26 | 27 | The `external` option allows you to explicitly mark certain dependencies as external, ensuring they are not bundled into your library. For example: 28 | 29 | ```ts [tsdown.config.ts] 30 | import { defineConfig } from 'tsdown' 31 | 32 | export default defineConfig({ 33 | external: ['lodash', /^@my-scope\//], 34 | }) 35 | ``` 36 | 37 | In this example, `lodash` and all packages under the `@my-scope` namespace will be treated as external. 38 | 39 | ### `noExternal` 40 | 41 | The `noExternal` option allows you to force certain dependencies to be bundled, even if they are listed in `dependencies` or `peerDependencies`. For example: 42 | 43 | ```ts [tsdown.config.ts] 44 | import { defineConfig } from 'tsdown' 45 | 46 | export default defineConfig({ 47 | noExternal: ['some-package'], 48 | }) 49 | ``` 50 | 51 | Here, `some-package` will be bundled into your library. 52 | 53 | ## Handling Dependencies in Declaration Files 54 | 55 | For declaration files, `tsdown` **does not bundle any dependencies by default**. This ensures that your `.d.ts` files remain clean and focused on your library's types. 56 | 57 | ### Customizing Type Resolution 58 | 59 | You can use the `dts.resolve` option to explicitly include type definitions for certain dependencies: 60 | 61 | ```ts [tsdown.config.ts] 62 | import { defineConfig } from 'tsdown' 63 | 64 | export default defineConfig({ 65 | dts: { 66 | resolve: ['lodash', /^@types\//], 67 | }, 68 | }) 69 | ``` 70 | 71 | In this example, type definitions for `lodash` and all packages under the `@types` namespace will be bundled into the `.d.ts` files. 72 | 73 | ## Summary 74 | 75 | - **Default Behavior**: 76 | - `dependencies` and `peerDependencies` are treated as external and not bundled. 77 | - `devDependencies` and phantom dependencies are only bundled if they are actually used in your code. 78 | - **Customization**: 79 | - Use `external` to mark specific dependencies as external. 80 | - Use `noExternal` to force specific dependencies to be bundled. 81 | - **Declaration Files**: 82 | - Dependencies are not bundled by default. 83 | - Use `dts.resolve` to include specific dependency types in `.d.ts` files. 84 | 85 | By understanding and customizing dependency handling, you can ensure your library is optimized for both size and usability. 86 | -------------------------------------------------------------------------------- /docs/options/dts.md: -------------------------------------------------------------------------------- 1 | # Declaration Files (dts) 2 | 3 | Declaration files (`.d.ts`) are an essential part of TypeScript libraries, providing type definitions that allow consumers of your library to benefit from TypeScript's type checking and IntelliSense. 4 | 5 | `tsdown` makes it easy to generate and bundle declaration files for your library, ensuring a seamless developer experience for your users. 6 | 7 | > [!NOTE] 8 | > You must install `typescript` in your project for declaration file generation to work properly. 9 | 10 | ## How dts Works in tsdown 11 | 12 | `tsdown` uses [rolldown-plugin-dts](https://github.com/sxzz/rolldown-plugin-dts) internally to generate and bundle `.d.ts` files. This plugin is specifically designed to handle declaration file generation efficiently and integrates seamlessly with `tsdown`. 13 | 14 | If you encounter any issues related to `.d.ts` generation, please report them directly to the [rolldown-plugin-dts repository](https://github.com/sxzz/rolldown-plugin-dts/issues). 15 | 16 | ## Enabling dts Generation 17 | 18 | If your `package.json` contains a `types` or `typings` field, declaration file generation will be **enabled by default** in `tsdown`. 19 | 20 | You can also explicitly enable `.d.ts` generation using the `--dts` option in the CLI or by setting `dts: true` in your configuration file. 21 | 22 | ### CLI 23 | 24 | ```bash 25 | tsdown --dts 26 | ``` 27 | 28 | ### Config File 29 | 30 | ```ts [tsdown.config.ts] 31 | import { defineConfig } from 'tsdown' 32 | 33 | export default defineConfig({ 34 | dts: true, 35 | }) 36 | ``` 37 | 38 | ## Declaration Map 39 | 40 | Declaration maps allow `.d.ts` files to be mapped back to their original `.ts` sources, which is especially useful in monorepo setups for improved navigation and debugging. Learn more in the [TypeScript documentation](https://www.typescriptlang.org/tsconfig/#declarationMap). 41 | 42 | You can enable declaration maps in either of the following ways (no need to set both): 43 | 44 | ### Enable in `tsconfig.json` 45 | 46 | Enable the `declarationMap` option under `compilerOptions`: 47 | 48 | ```json [tsconfig.json] 49 | { 50 | "compilerOptions": { 51 | "declarationMap": true 52 | } 53 | } 54 | ``` 55 | 56 | ### Enable in tsdown Config 57 | 58 | Set the `dts.sourcemap` option to `true` in your tsdown config file: 59 | 60 | ```ts [tsdown.config.ts] 61 | import { defineConfig } from 'tsdown' 62 | 63 | export default defineConfig({ 64 | dts: { 65 | sourcemap: true, 66 | }, 67 | }) 68 | ``` 69 | 70 | ## Performance Considerations 71 | 72 | The performance of `.d.ts` generation depends on your `tsconfig.json` configuration: 73 | 74 | ### With `isolatedDeclarations` 75 | 76 | If your `tsconfig.json` has the `isolatedDeclarations` option enabled, `tsdown` will use **oxc-transform** for `.d.ts` generation. This method is **extremely fast** and highly recommended for optimal performance. 77 | 78 | ```json [tsconfig.json] 79 | { 80 | "compilerOptions": { 81 | "isolatedDeclarations": true 82 | } 83 | } 84 | ``` 85 | 86 | ### Without `isolatedDeclarations` 87 | 88 | If `isolatedDeclarations` is not enabled, `tsdown` will fall back to using the TypeScript compiler for `.d.ts` generation. While this approach is reliable, it is relatively slower compared to `oxc-transform`. 89 | 90 | > [!TIP] 91 | > If speed is critical for your workflow, consider enabling `isolatedDeclarations` in your `tsconfig.json`. 92 | 93 | ## Build Process for dts 94 | 95 | - **For ESM Output**: Both `.js` and `.d.ts` files are generated in the **same build process**. If you encounter compatibility issues, please report them. 96 | - **For CJS Output**: A **separate build process** is used exclusively for `.d.ts` generation to ensure compatibility. 97 | 98 | ## Advanced Options 99 | 100 | `rolldown-plugin-dts` provides several advanced options to customize `.d.ts` generation. For a detailed explanation of these options, refer to the [plugin's documentation](https://github.com/sxzz/rolldown-plugin-dts#options). 101 | -------------------------------------------------------------------------------- /docs/options/entry.md: -------------------------------------------------------------------------------- 1 | # Entry 2 | 3 | The `entry` option specifies the entry files for your project. These files serve as the starting points for the bundling process. You can define entry files either via the CLI or in the configuration file. 4 | 5 | ## Using the CLI 6 | 7 | You can specify entry files directly as command arguments when using the CLI. For example: 8 | 9 | ```bash 10 | tsdown src/entry1.ts src/entry2.ts 11 | ``` 12 | 13 | This command will bundle `src/entry1.ts` and `src/entry2.ts` as separate entry points. 14 | 15 | ## Using the Config File 16 | 17 | In the configuration file, the `entry` option allows you to define entry files in various formats: 18 | 19 | ### Single Entry File 20 | 21 | Specify a single entry file as a string: 22 | 23 | ```ts [tsdown.config.ts] 24 | import { defineConfig } from 'tsdown' 25 | 26 | export default defineConfig({ 27 | entry: 'src/index.ts', 28 | }) 29 | ``` 30 | 31 | ### Multiple Entry Files 32 | 33 | Define multiple entry files as an array of strings: 34 | 35 | ```ts [tsdown.config.ts] 36 | import { defineConfig } from 'tsdown' 37 | 38 | export default defineConfig({ 39 | entry: ['src/entry1.ts', 'src/entry2.ts'], 40 | }) 41 | ``` 42 | 43 | ### Entry Files with Aliases 44 | 45 | Use an object to define entry files with aliases. The keys represent alias names, and the values represent file paths: 46 | 47 | ```ts [tsdown.config.ts] 48 | import { defineConfig } from 'tsdown' 49 | 50 | export default defineConfig({ 51 | entry: { 52 | main: 'src/index.ts', 53 | utils: 'src/utils.ts', 54 | }, 55 | }) 56 | ``` 57 | 58 | This configuration will create two bundles: one for `src/index.ts` (output as `dist/main.js`) and one for `src/utils.ts` (output as `dist/utils.js`). 59 | 60 | ## Using Glob Patterns 61 | 62 | The `entry` option supports [glob patterns](https://code.visualstudio.com/docs/editor/glob-patterns), enabling you to match multiple files dynamically. For example: 63 | 64 | ```ts [tsdown.config.ts] 65 | import { defineConfig } from 'tsdown' 66 | 67 | export default defineConfig({ 68 | entry: 'src/**/*.ts', 69 | }) 70 | ``` 71 | 72 | This configuration will include all `.ts` files in the `src` directory and its subdirectories as entry points. 73 | 74 | > [!WARNING] 75 | > The `entry` option is treated as a glob pattern by default. This means: 76 | > 77 | > - On **Windows**, you must use forward slashes (`/`) instead of backslashes (`\`) in file paths. 78 | > - You cannot specify files that do not exist in the file system. 79 | > 80 | > If you need to bypass these limitations, you can use `inputOptions.input` directly in the configuration file for more precise control. 81 | -------------------------------------------------------------------------------- /docs/options/minification.md: -------------------------------------------------------------------------------- 1 | # Minification 2 | 3 | Minification is the process of compressing your code to reduce its size and improve performance by removing unnecessary characters, such as whitespace, comments, and unused code. 4 | 5 | You can enable minification in `tsdown` using the `--minify` option: 6 | 7 | ```bash 8 | tsdown --minify 9 | ``` 10 | 11 | > [!NOTE] 12 | > The minification feature is based on [Oxc](https://oxc.rs/docs/contribute/minifier), which is currently in alpha and can still have bugs. We recommend thoroughly testing your output in production environments. 13 | 14 | ### Example 15 | 16 | Given the following input code: 17 | 18 | ```ts [src/index.ts] 19 | const x = 1 20 | 21 | function hello(x: number) { 22 | console.log('Hello World') 23 | console.log(x) 24 | } 25 | 26 | hello(x) 27 | ``` 28 | 29 | Here are the two possible outputs, depending on whether minification is enabled: 30 | 31 | ::: code-group 32 | 33 | ```js [dist/index.mjs (without --minify)] 34 | //#region src/index.ts 35 | const x = 1 36 | function hello(x$1) { 37 | console.log('Hello World') 38 | console.log(x$1) 39 | } 40 | hello(x) 41 | 42 | //#endregion 43 | ``` 44 | 45 | 46 | ```js [dist/index.mjs (with --minify)] 47 | const e=1;function t(e){console.log(`Hello World`),console.log(e)}t(e); 48 | ``` 49 | 50 | ::: 51 | -------------------------------------------------------------------------------- /docs/options/output-directory.md: -------------------------------------------------------------------------------- 1 | # Output Directory 2 | 3 | By default, `tsdown` bundles your code into the `dist` directory located in the current working folder. 4 | 5 | If you want to customize the output directory, you can use the `--out-dir` (or `-d`) option: 6 | 7 | ```bash 8 | tsdown -d ./custom-output 9 | ``` 10 | 11 | ### Example 12 | 13 | ```bash 14 | # Default behavior: outputs to ./dist 15 | tsdown 16 | 17 | # Custom output directory: outputs to ./build 18 | tsdown -d ./build 19 | ``` 20 | 21 | > [!NOTE] 22 | > The specified output directory will be created if it does not already exist. Ensure the directory path aligns with your project structure to avoid overwriting unintended files. 23 | -------------------------------------------------------------------------------- /docs/options/output-format.md: -------------------------------------------------------------------------------- 1 | # Output Format 2 | 3 | By default, `tsdown` generates JavaScript code in the [ESM](https://nodejs.org/api/esm.html) (ECMAScript Module) format. However, you can specify the desired output format using the `--format` option: 4 | 5 | ```bash 6 | tsdown --format esm # default 7 | ``` 8 | 9 | ### Available Formats 10 | 11 | - [`esm`](https://nodejs.org/api/esm.html): ECMAScript Module format, ideal for modern JavaScript environments, including browsers and Node.js. 12 | - [`cjs`](https://nodejs.org/api/modules.html): CommonJS format, commonly used in Node.js projects. 13 | - [`iife`](https://developer.mozilla.org/en-US/docs/Glossary/IIFE): Immediately Invoked Function Expression, suitable for embedding in `