agentleFS
TheEdoRanTheEdoRan/next-safe-action/.agents/skills/tsdown/SKILL.md

tsdown

Skill3.1k starsChanged 9 months agoMITView on GitHub

Bundle TypeScript and JavaScript libraries with blazing-fast speed powered by Rolldown. Use when building libraries, generating type declarations, bundling for multiple formats, or migrating from tsup.

  • Installs packages

17 other projects use a version of this, 13 of them edited.

Trending

Quiet since March.about the whole repository

Dec 2025: 1 mentionJan 2026: 0 mentionsFeb 2026: 3 mentionsMar 2026: 5 mentionsApr 2026: 0 mentionsMay 2026: 0 mentionsJun 2026: 0 mentionsJul 2026: 0 mentionsAug 2026: 0 mentionsSep 2026: 0 mentionsOct 2026: 0 mentionsNov 2026: 0 mentions
Dec 2025Jun 2026Nov 2026
Mentions a month of the TheEdoRan/next-safe-action repository that our weekly crawl found. There is no adoption data for this file yet.

Most recently taken up by

Who's talking about TheEdoRan/next-safe-action

The biggest 5 of 50 mentions linking to the repository that our crawl found. Each line is their own headline.

See all 50

Talked about on GitHub (50 times).

On GitHub · 50

45 more on GitHub

The file

We split this skill into the rules it gives an agent

2 rules. 2 are common, 0 are distinctive, and 0 are very specific to this project.

  • 2

    Common

    Most of the 13 edited versions we read keep these.

  • 0

    Distinctive

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Common:

    Use functions for dynamic configuration:

    line 239
  2. Common:

    Use glob patterns to build multiple packages:

    line 255

“Common” is measured: kept by at least 6 in 10 of the 13 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

tsdown - The Elegant Library Bundler

Blazing-fast bundler for TypeScript/JavaScript libraries powered by Rolldown and Oxc.

When to Use

  • Building TypeScript/JavaScript libraries for npm
  • Generating TypeScript declaration files (.d.ts)
  • Bundling for multiple formats (ESM, CJS, IIFE, UMD)
  • Optimizing bundles with tree shaking and minification
  • Migrating from tsup with minimal changes
  • Building React, Vue, Solid, or Svelte component libraries

Quick Start

# Install
pnpm add -D tsdown

# Basic usage
npx tsdown

# With config file
npx tsdown --config tsdown.config.ts

# Watch mode
npx tsdown --watch

# Migrate from tsup
npx tsdown-migrate

Basic Configuration

import { defineConfig } from 'tsdown'

export default defineConfig({
  entry: ['./src/index.ts'],
  format: ['esm', 'cjs'],
  dts: true,
  clean: true,
})

Core References

TopicDescriptionReference
Getting StartedInstallation, first bundle, CLI basicsguide-getting-started
Configuration FileConfig file formats, multiple configs, workspaceoption-config-file
CLI ReferenceAll CLI commands and optionsreference-cli
Migrate from tsupMigration guide and compatibility notesguide-migrate-from-tsup
PluginsRolldown, Rollup, Unplugin supportadvanced-plugins
HooksLifecycle hooks for custom logicadvanced-hooks
Programmatic APIBuild from Node.js scriptsadvanced-programmatic
Rolldown OptionsPass options directly to Rolldownadvanced-rolldown-options
CI EnvironmentCI detection, 'ci-only' / 'local-only' valuesadvanced-ci

Build Options

OptionUsageReference
Entry pointsentry: ['src/*.ts', '!**/*.test.ts']option-entry
Output formatsformat: ['esm', 'cjs', 'iife', 'umd']option-output-format
Output directoryoutDir: 'dist', outExtensionsoption-output-directory
Type declarationsdts: true, dts: { sourcemap, compilerOptions, vue }option-dts
Target environmenttarget: 'es2020', target: 'esnext'option-target
Platformplatform: 'node', platform: 'browser'option-platform
Tree shakingtreeshake: true, custom optionsoption-tree-shaking
Minificationminify: true, minify: 'dce-only'option-minification
Source mapssourcemap: true, 'inline', 'hidden'option-sourcemap
Watch modewatch: true, watch optionsoption-watch-mode
Cleaningclean: true, clean patternsoption-cleaning
Log levellogLevel: 'silent', failOnWarn: 'ci-only'option-log-level

Dependency Handling

FeatureUsageReference
External depsexternal: ['react', /^@myorg\//]option-dependencies
Inline depsnoExternal: ['dep-to-bundle']option-dependencies
Auto externalAutomatic peer/dependency externalizationoption-dependencies

Output Enhancement

FeatureUsageReference
Shimsshims: true - Add ESM/CJS compatibilityoption-shims
CJS defaultcjsDefault: true (default) / falseoption-cjs-default
Package exportsexports: true - Auto-generate exports fieldoption-package-exports
CSS handling[experimental] Still in developmentoption-css
Unbundle modeunbundle: true - Preserve directory structureoption-unbundle
Package validationpublint: true, attw: true - Validate packageoption-lint

Framework & Runtime Support

FrameworkGuideReference
ReactJSX transform, Fast Refreshrecipe-react
VueSFC support, JSXrecipe-vue
WASMWebAssembly modules via rolldown-plugin-wasmrecipe-wasm

Common Patterns

Basic Library Bundle

export default defineConfig({
  entry: ['src/index.ts'],
  format: ['esm', 'cjs'],
  dts: true,
  clean: true,
})

Multiple Entry Points

export default defineConfig({
  entry: {
    index: 'src/index.ts',
    utils: 'src/utils.ts',
    cli: 'src/cli.ts',
  },
  format: ['esm', 'cjs'],
  dts: true,
})

Browser Library (IIFE/UMD)

export default defineConfig({
  entry: ['src/index.ts'],
  format: ['iife'],
  globalName: 'MyLib',
  platform: 'browser',
  minify: true,
})

React Component Library

export default defineConfig({
  entry: ['src/index.tsx'],
  format: ['esm', 'cjs'],
  dts: true,
  external: ['react', 'react-dom'],
  plugins: [
    // React Fast Refresh support
  ],
})

Preserve Directory Structure

export default defineConfig({
  entry: ['src/**/*.ts', '!**/*.test.ts'],
  unbundle: true, // Preserve file structure
  format: ['esm'],
  dts: true,
})

CI-Aware Configuration

export default defineConfig({
  entry: ['src/index.ts'],
  format: ['esm', 'cjs'],
  dts: true,
  failOnWarn: 'ci-only',
  publint: 'ci-only',
  attw: 'ci-only',
})

WASM Support

import { wasm } from 'rolldown-plugin-wasm'
import { defineConfig } from 'tsdown'

export default defineConfig({
  entry: ['src/index.ts'],
  plugins: [wasm()],
})

Advanced with Hooks

export default defineConfig({
  entry: ['src/index.ts'],
  format: ['esm', 'cjs'],
  dts: true,
  hooks: {
    'build:before': async (context) => {
      console.log('Building...')
    },
    'build:done': async (context) => {
      console.log('Build complete!')
    },
  },
})

Configuration Features

Multiple Configs

Export an array for multiple build configurations:

export default defineConfig([
  {
    entry: ['src/index.ts'],
    format: ['esm', 'cjs'],
    dts: true,
  },
  {
    entry: ['src/cli.ts'],
    format: ['esm'],
    platform: 'node',
  },
])

Conditional Config

Use functions for dynamic configuration:

export default defineConfig((options) => {
  const isDev = options.watch
  return {
    entry: ['src/index.ts'],
    format: ['esm', 'cjs'],
    minify: !isDev,
    sourcemap: isDev,
  }
})

Workspace/Monorepo

Use glob patterns to build multiple packages:

export default defineConfig({
  workspace: 'packages/*',
  entry: ['src/index.ts'],
  format: ['esm', 'cjs'],
  dts: true,
})

CLI Quick Reference

# Basic commands
tsdown                          # Build once
tsdown --watch                  # Watch mode
tsdown --config custom.ts       # Custom config
npx tsdown-migrate              # Migrate from tsup

# Output options
tsdown --format esm,cjs        # Multiple formats
tsdown --outDir lib            # Custom output directory
tsdown --minify                # Enable minification
tsdown --dts                   # Generate declarations

# Entry options
tsdown src/index.ts            # Single entry
tsdown src/*.ts                # Glob patterns
tsdown src/a.ts src/b.ts       # Multiple entries

# Development
tsdown --watch                 # Watch mode
tsdown --sourcemap             # Generate source maps
tsdown --clean                 # Clean output directory

Best Practices

  1. Always generate type declarations for TypeScript libraries:
    { dts: true }
  2. Externalize dependencies to avoid bundling unnecessary code:
    { external: [/^react/, /^@myorg\//] }
  3. Use tree shaking for optimal bundle size:
    { treeshake: true }
  4. Enable minification for production builds:
    { minify: true }
  5. Add shims for better ESM/CJS compatibility:
    { shims: true }  // Adds __dirname, __filename, etc.
  6. Auto-generate package.json exports:
    { exports: true }  // Creates proper exports field
  7. Use watch mode during development:
    tsdown --watch
  8. Preserve structure for utilities with many files:
    { unbundle: true }  // Keep directory structure
  9. Validate packages in CI before publishing:
    { publint: 'ci-only', attw: 'ci-only' }

Resources

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.