You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Rename flat dependency options to a nested `deps` config namespace:
- `external` → `deps.neverBundle`
- `noExternal` → `deps.alwaysBundle`
- `inlineOnly` → `deps.onlyAllowBundle`
- `skipNodeModulesBundle` → `deps.skipNodeModulesBundle`
Old options are deprecated but still work with warnings.
CLI flag `--external` renamed to `--deps.never-bundle`.
|[`inlineOnly`](../options/dependencies.md#strict-inline-control-with-inlineonly)| Whitelist of dependencies allowed to be bundled. Any unlisted dependency that ends up in the bundle causes an error. Useful for catching accidental inlining in large projects. |
39
-
|[`external`](../options/dependencies.md#external)| Explicitly mark additional packages as external (never bundled). |
40
-
|[`noExternal`](../options/dependencies.md#noexternal)| Force specific packages to be bundled, even if they're in `dependencies`. |
41
-
|[`skipNodeModulesBundle`](../options/dependencies.md#skipping-node-modules-bundling)| Skip resolving and bundling everything from `node_modules`. |
|[`deps.onlyAllowBundle`](../options/dependencies.md#deps-onlyallowbundle)| Whitelist of dependencies allowed to be bundled. Any unlisted dependency that ends up in the bundle causes an error. Useful for catching accidental inlining in large projects. |
39
+
|[`deps.neverBundle`](../options/dependencies.md#deps-neverbundle)| Explicitly mark additional packages as external (never bundled). |
40
+
|[`deps.alwaysBundle`](../options/dependencies.md#deps-alwaysbundle)| Force specific packages to be bundled, even if they're in `dependencies`. |
41
+
|[`deps.skipNodeModulesBundle`](../options/dependencies.md#deps-skipnodemodulebundle)| Skip resolving and bundling everything from `node_modules`. |
42
42
43
43
See [Dependencies](../options/dependencies.md) for details.
Copy file name to clipboardExpand all lines: docs/options/dependencies.md
+63-27Lines changed: 63 additions & 27 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,6 @@
1
1
# Dependencies
2
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.
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
4
5
5
## Default Behavior
6
6
@@ -18,71 +18,96 @@ By default, `tsdown` **does not bundle dependencies** listed in your `package.js
18
18
19
19
In other words, only the `devDependencies` and phantom dependencies that are actually referenced in your project will be included in the bundle.
20
20
21
-
## Skipping Node Modules Bundling
21
+
## The `deps` Option
22
22
23
-
If you want to **skip resolving and bundling all dependencies from `node_modules`**, you can enable the `skipNodeModulesBundle` option in your configuration:
23
+
All dependency-related options are configured under the `deps` field:
24
24
25
-
```ts
25
+
```ts [tsdown.config.ts]
26
+
import { defineConfig } from'tsdown'
27
+
28
+
exportdefaultdefineConfig({
29
+
deps: {
30
+
neverBundle: ['lodash',/^@my-scope\//],
31
+
alwaysBundle: ['some-package'],
32
+
onlyAllowBundle: ['cac', 'bumpp'],
33
+
skipNodeModulesBundle: true,
34
+
},
35
+
})
36
+
```
37
+
38
+
### `deps.skipNodeModulesBundle`
39
+
40
+
If you want to **skip resolving and bundling all dependencies from `node_modules`**, you can enable `skipNodeModulesBundle`:
41
+
42
+
```ts [tsdown.config.ts]
26
43
import { defineConfig } from'tsdown'
27
44
28
45
exportdefaultdefineConfig({
29
-
skipNodeModulesBundle: true,
46
+
deps: {
47
+
skipNodeModulesBundle: true,
48
+
},
30
49
})
31
50
```
32
51
33
52
This will prevent `tsdown` from parsing and bundling any dependencies from `node_modules`, regardless of how they are referenced in your code.
34
53
35
-
## Strict Inline Control with `inlineOnly`
54
+
::: warning
55
+
`skipNodeModulesBundle` cannot be used together with `alwaysBundle`. These options are mutually exclusive.
56
+
:::
57
+
58
+
### `deps.onlyAllowBundle`
36
59
37
-
The `inlineOnly` option acts as a whitelist for dependencies that are allowed to be bundled from `node_modules`. If any dependency not in the list is found in the bundle, tsdown will throw an error. This is useful for preventing unexpected dependencies from being silently inlined into your output, especially in large projects.
60
+
The `onlyAllowBundle` option acts as a whitelist for dependencies that are allowed to be bundled from `node_modules`. If any dependency not in the list is found in the bundle, tsdown will throw an error. This is useful for preventing unexpected dependencies from being silently inlined into your output, especially in large projects.
38
61
39
62
```ts [tsdown.config.ts]
40
63
import { defineConfig } from'tsdown'
41
64
42
65
exportdefaultdefineConfig({
43
-
inlineOnly: ['cac', 'bumpp'],
66
+
deps: {
67
+
onlyAllowBundle: ['cac', 'bumpp'],
68
+
},
44
69
})
45
70
```
46
71
47
72
In this example, only `cac` and `bumpp` are allowed to be bundled. If any other `node_modules` dependency is imported, tsdown will throw an error with a message indicating which dependency was unexpectedly bundled and which files imported it.
48
73
49
-
### Behavior
74
+
####Behavior
50
75
51
-
-**`inlineOnly` is an array** (e.g., `['cac', /^my-/]`): Only dependencies matching the list are allowed to be bundled. An error is thrown for any others. Unused patterns in the list will also be reported.
52
-
-**`inlineOnly` is `false`**: All warnings and checks about bundled dependencies are suppressed.
53
-
-**`inlineOnly` is not set** (default): A warning is shown if any `node_modules` dependencies are bundled, suggesting you add the `inlineOnly` option or set it to `false` to suppress warnings.
76
+
-**`onlyAllowBundle` is an array** (e.g., `['cac', /^my-/]`): Only dependencies matching the list are allowed to be bundled. An error is thrown for any others. Unused patterns in the list will also be reported.
77
+
-**`onlyAllowBundle` is `false`**: All warnings and checks about bundled dependencies are suppressed.
78
+
-**`onlyAllowBundle` is not set** (default): A warning is shown if any `node_modules` dependencies are bundled, suggesting you add the `onlyAllowBundle` option or set it to `false` to suppress warnings.
54
79
55
80
::: tip
56
-
Make sure to include all required sub-dependencies in the `inlineOnly` list as well, not just the top-level packages you directly import.
81
+
Make sure to include all required sub-dependencies in the `onlyAllowBundle` list as well, not just the top-level packages you directly import.
57
82
:::
58
83
59
-
## Customizing Dependency Handling
60
-
61
-
`tsdown` provides two options to override the default behavior:
62
-
63
-
### `external`
84
+
### `deps.neverBundle`
64
85
65
-
The `external` option allows you to explicitly mark certain dependencies as external, ensuring they are not bundled into your library. For example:
86
+
The `neverBundle` option allows you to explicitly mark certain dependencies as external, ensuring they are not bundled into your library. For example:
66
87
67
88
```ts [tsdown.config.ts]
68
89
import { defineConfig } from'tsdown'
69
90
70
91
exportdefaultdefineConfig({
71
-
external: ['lodash',/^@my-scope\//],
92
+
deps: {
93
+
neverBundle: ['lodash',/^@my-scope\//],
94
+
},
72
95
})
73
96
```
74
97
75
98
In this example, `lodash` and all packages under the `@my-scope` namespace will be treated as external.
76
99
77
-
### `noExternal`
100
+
### `deps.alwaysBundle`
78
101
79
-
The `noExternal` option allows you to force certain dependencies to be bundled, even if they are listed in `dependencies` or `peerDependencies`. For example:
102
+
The `alwaysBundle` option allows you to force certain dependencies to be bundled, even if they are listed in `dependencies` or `peerDependencies`. For example:
0 commit comments