Subchapter 8.24
references/option-platform.mdMarkdown5 KBView on GitHub
Platform determines the runtime environment and affects module resolution, built-in handling, and optimizations.
| Platform | Runtime | Built-ins | Use Case |
|---|---|---|---|
node | Node.js (default) | Resolved automatically | Server-side, CLIs, tooling |
browser | Web browsers | Warning if used | Front-end applications |
neutral | Platform-agnostic | No assumptions | Universal libraries |
tsdown --platform node # Default
tsdown --platform browser
tsdown --platform neutralexport default defineConfig({
entry: ['src/index.ts'],
platform: 'browser',
})Default platform for server-side and tooling.
export default defineConfig({
entry: ['src/index.ts'],
platform: 'node',
})Characteristics:
['main', 'module']For web applications running in browsers.
export default defineConfig({
entry: ['src/index.ts'],
platform: 'browser',
format: ['esm'],
})Characteristics:
['browser', 'module', 'main']Platform-agnostic for universal libraries.
export default defineConfig({
entry: ['src/index.ts'],
platform: 'neutral',
format: ['esm'],
})Characteristics:
exports field only[]CJS format always uses node platform and cannot be changed.
export default defineConfig({
entry: ['src/index.ts'],
format: ['cjs'],
platform: 'browser', // Ignored for CJS
})See rolldown PR #4693 (opens in a new tab) for details.
Different platforms check different package.json fields:
| Platform | mainFields | Priority |
|---|---|---|
node | ['main', 'module'] | main → module |
browser | ['browser', 'module', 'main'] | browser → module → main |
neutral | [] | Only exports field |
When using neutral, packages without exports field may fail to resolve:
Help: The "main" field here was ignored. Main fields must be configured
explicitly when using the "neutral" platform.Solution: Configure mainFields explicitly:
export default defineConfig({
platform: 'neutral',
inputOptions: {
resolve: {
mainFields: ['module', 'main'],
},
},
})export default defineConfig({
entry: ['src/cli.ts'],
format: ['esm'],
platform: 'node',
shims: true,
})export default defineConfig({
entry: ['src/index.ts'],
format: ['iife'],
platform: 'browser',
globalName: 'MyLib',
minify: true,
})export default defineConfig({
entry: ['src/index.ts'],
format: ['esm'],
platform: 'neutral',
inputOptions: {
resolve: {
mainFields: ['module', 'main'],
},
},
})export default defineConfig({
entry: ['src/index.tsx'],
format: ['esm', 'cjs'],
platform: 'browser',
deps: {
neverBundle: ['react', 'react-dom'],
},
})export default defineConfig([
{
entry: ['src/index.ts'],
format: ['esm', 'cjs'],
platform: 'node',
},
{
entry: ['src/browser.ts'],
format: ['esm'],
platform: 'browser',
},
])When using Node.js APIs in browser builds:
Warning: Module "fs" has been externalized for browser compatibilitySolutions:
When packages don’t resolve with neutral:
export default defineConfig({
platform: 'neutral',
inputOptions: {
resolve: {
mainFields: ['module', 'browser', 'main'],
conditions: ['import', 'require'],
},
},
})node for server-side and CLIs (default)browser for front-end applicationsneutral for universal libraries