feat: Complete fleet — 94 skills across 10+ domains
Pulled ALL skills from 15 source repositories: - anthropics/skills: 16 (docs, design, MCP, testing) - obra/superpowers: 14 (TDD, debugging, agents, planning) - coreyhaines31/marketingskills: 25 (marketing, CRO, SEO, growth) - better-auth/skills: 5 (auth patterns) - vercel-labs/agent-skills: 5 (React, design, Vercel) - antfu/skills: 16 (Vue, Vite, Vitest, pnpm, Turborepo) - Plus 13 individual skills from various repos Mosaic Stack is not limited to coding — the Orchestrator and subagents serve coding, business, design, marketing, writing, logistics, analysis, and more. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Jason Woltje
254
skills/tsdown/references/option-platform.md
Normal file
254
skills/tsdown/references/option-platform.md
Normal file
@@ -0,0 +1,254 @@
|
||||
# Platform
|
||||
|
||||
Target runtime environment for bundled code.
|
||||
|
||||
## Overview
|
||||
|
||||
Platform determines the runtime environment and affects module resolution, built-in handling, and optimizations.
|
||||
|
||||
## Available Platforms
|
||||
|
||||
| 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 |
|
||||
|
||||
## Usage
|
||||
|
||||
### CLI
|
||||
|
||||
```bash
|
||||
tsdown --platform node # Default
|
||||
tsdown --platform browser
|
||||
tsdown --platform neutral
|
||||
```
|
||||
|
||||
### Config File
|
||||
|
||||
```ts
|
||||
export default defineConfig({
|
||||
entry: ['src/index.ts'],
|
||||
platform: 'browser',
|
||||
})
|
||||
```
|
||||
|
||||
## Platform Details
|
||||
|
||||
### Node Platform
|
||||
|
||||
**Default platform** for server-side and tooling.
|
||||
|
||||
```ts
|
||||
export default defineConfig({
|
||||
entry: ['src/index.ts'],
|
||||
platform: 'node',
|
||||
})
|
||||
```
|
||||
|
||||
**Characteristics:**
|
||||
- Node.js built-ins (fs, path, etc.) resolved automatically
|
||||
- Optimized for Node.js runtime
|
||||
- Compatible with Deno and Bun
|
||||
- Default mainFields: `['main', 'module']`
|
||||
|
||||
### Browser Platform
|
||||
|
||||
For web applications running in browsers.
|
||||
|
||||
```ts
|
||||
export default defineConfig({
|
||||
entry: ['src/index.ts'],
|
||||
platform: 'browser',
|
||||
format: ['esm'],
|
||||
})
|
||||
```
|
||||
|
||||
**Characteristics:**
|
||||
- Warnings if Node.js built-ins are used
|
||||
- May require polyfills for Node APIs
|
||||
- Optimized for browser environments
|
||||
- Default mainFields: `['browser', 'module', 'main']`
|
||||
|
||||
### Neutral Platform
|
||||
|
||||
Platform-agnostic for universal libraries.
|
||||
|
||||
```ts
|
||||
export default defineConfig({
|
||||
entry: ['src/index.ts'],
|
||||
platform: 'neutral',
|
||||
format: ['esm'],
|
||||
})
|
||||
```
|
||||
|
||||
**Characteristics:**
|
||||
- No runtime assumptions
|
||||
- No automatic built-in resolution
|
||||
- Relies on `exports` field only
|
||||
- Default mainFields: `[]`
|
||||
- Full control over runtime behavior
|
||||
|
||||
## CJS Format Limitation
|
||||
|
||||
**CJS format always uses `node` platform** and cannot be changed.
|
||||
|
||||
```ts
|
||||
export default defineConfig({
|
||||
entry: ['src/index.ts'],
|
||||
format: ['cjs'],
|
||||
platform: 'browser', // Ignored for CJS
|
||||
})
|
||||
```
|
||||
|
||||
See [rolldown PR #4693](https://github.com/rolldown/rolldown/pull/4693#issuecomment-2912229545) for details.
|
||||
|
||||
## Module Resolution
|
||||
|
||||
### Main Fields
|
||||
|
||||
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 |
|
||||
|
||||
### Neutral Platform Resolution
|
||||
|
||||
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:
|
||||
|
||||
```ts
|
||||
export default defineConfig({
|
||||
platform: 'neutral',
|
||||
inputOptions: {
|
||||
resolve: {
|
||||
mainFields: ['module', 'main'],
|
||||
},
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Node.js CLI Tool
|
||||
|
||||
```ts
|
||||
export default defineConfig({
|
||||
entry: ['src/cli.ts'],
|
||||
format: ['esm'],
|
||||
platform: 'node',
|
||||
shims: true,
|
||||
})
|
||||
```
|
||||
|
||||
### Browser Library (IIFE)
|
||||
|
||||
```ts
|
||||
export default defineConfig({
|
||||
entry: ['src/index.ts'],
|
||||
format: ['iife'],
|
||||
platform: 'browser',
|
||||
globalName: 'MyLib',
|
||||
minify: true,
|
||||
})
|
||||
```
|
||||
|
||||
### Universal Library
|
||||
|
||||
```ts
|
||||
export default defineConfig({
|
||||
entry: ['src/index.ts'],
|
||||
format: ['esm'],
|
||||
platform: 'neutral',
|
||||
inputOptions: {
|
||||
resolve: {
|
||||
mainFields: ['module', 'main'],
|
||||
},
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
### React Component Library
|
||||
|
||||
```ts
|
||||
export default defineConfig({
|
||||
entry: ['src/index.tsx'],
|
||||
format: ['esm', 'cjs'],
|
||||
platform: 'browser',
|
||||
external: ['react', 'react-dom'],
|
||||
})
|
||||
```
|
||||
|
||||
### Node.js + Browser Builds
|
||||
|
||||
```ts
|
||||
export default defineConfig([
|
||||
{
|
||||
entry: ['src/index.ts'],
|
||||
format: ['esm', 'cjs'],
|
||||
platform: 'node',
|
||||
},
|
||||
{
|
||||
entry: ['src/browser.ts'],
|
||||
format: ['esm'],
|
||||
platform: 'browser',
|
||||
},
|
||||
])
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Node Built-in Warnings (Browser)
|
||||
|
||||
When using Node.js APIs in browser builds:
|
||||
|
||||
```
|
||||
Warning: Module "fs" has been externalized for browser compatibility
|
||||
```
|
||||
|
||||
**Solutions:**
|
||||
1. Use platform: 'node' if not browser-only
|
||||
2. Add polyfills for Node APIs
|
||||
3. Avoid Node.js built-ins in browser code
|
||||
4. Use platform: 'neutral' with careful dependency management
|
||||
|
||||
### Module Resolution Issues (Neutral)
|
||||
|
||||
When packages don't resolve with `neutral`:
|
||||
|
||||
```ts
|
||||
export default defineConfig({
|
||||
platform: 'neutral',
|
||||
inputOptions: {
|
||||
resolve: {
|
||||
mainFields: ['module', 'browser', 'main'],
|
||||
conditions: ['import', 'require'],
|
||||
},
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
## Tips
|
||||
|
||||
1. **Use `node`** for server-side and CLIs (default)
|
||||
2. **Use `browser`** for front-end applications
|
||||
3. **Use `neutral`** for universal libraries
|
||||
4. **Configure mainFields** when using neutral platform
|
||||
5. **CJS is always node** - use ESM for other platforms
|
||||
6. **Test in target environment** to verify compatibility
|
||||
|
||||
## Related Options
|
||||
|
||||
- [Output Format](option-output-format.md) - Module formats
|
||||
- [Target](option-target.md) - JavaScript version
|
||||
- [Shims](option-shims.md) - ESM/CJS compatibility
|
||||
- [Dependencies](option-dependencies.md) - External packages
|
||||
Reference in New Issue
Block a user