stack/packages/mosaic/framework/skills/tsdown/references/advanced-hooks.md

Lifecycle Hooks

Extend the build process with lifecycle hooks.

Overview

Hooks provide a way to inject custom logic at specific stages of the build lifecycle. Inspired by unbuild.

Recommendation: Use plugins for most extensions. Use hooks for simple custom tasks or Rolldown plugin injection.

Usage Patterns

Object Syntax

export default defineConfig({
  entry: ['src/index.ts'],
  hooks: {
    'build:prepare': async (context) => {
      console.log('Build starting...');
    },
    'build:done': async (context) => {
      console.log('Build complete!');
    },
  },
});

Function Syntax

export default defineConfig({
  entry: ['src/index.ts'],
  hooks(hooks) {
    hooks.hook('build:prepare', () => {
      console.log('Preparing build...');
    });

    hooks.hook('build:before', (context) => {
      console.log(`Building format: ${context.format}`);
    });
  },
});

Available Hooks

build:prepare

Called before the build process starts.

When: Once per build session

Context:

{
  options: ResolvedConfig,
  hooks: Hookable
}

Use cases:

• Setup tasks
• Validation
• Environment preparation

Example:

hooks: {
  'build:prepare': async (context) => {
    console.log('Starting build for:', context.options.entry)
    await cleanOldFiles()
  },
}

build:before

Called before each Rolldown build.

When: Once per format (ESM, CJS, etc.)

Context:

{
  options: ResolvedConfig,
  buildOptions: BuildOptions,
  hooks: Hookable
}

Use cases:

• Modify build options per format
• Inject plugins dynamically
• Format-specific setup

Example:

hooks: {
  'build:before': async (context) => {
    console.log(`Building ${context.buildOptions.format} format...`)

    // Add format-specific plugin
    if (context.buildOptions.format === 'iife') {
      context.buildOptions.plugins.push(browserPlugin())
    }
  },
}

build:done

Called after the build completes.

When: Once per build session

Context:

{
  options: ResolvedConfig,
  chunks: RolldownChunk[],
  hooks: Hookable
}

Use cases:

• Post-processing
• Asset copying
• Notifications
• Deployment

Example:

hooks: {
  'build:done': async (context) => {
    console.log(`Built ${context.chunks.length} chunks`)

    // Copy additional files
    await copyAssets()

    // Send notification
    notifyBuildComplete()
  },
}

Common Patterns

Build Notifications

export default defineConfig({
  hooks: {
    'build:prepare': () => {
      console.log('🚀 Starting build...');
    },
    'build:done': (context) => {
      const size = context.chunks.reduce((sum, c) => sum + c.code.length, 0);
      console.log(`✅ Build complete! Total size: ${size} bytes`);
    },
  },
});

Conditional Plugin Injection

export default defineConfig({
  hooks(hooks) {
    hooks.hook('build:before', (context) => {
      // Add minification only for production
      if (process.env.NODE_ENV === 'production') {
        context.buildOptions.plugins.push(minifyPlugin());
      }
    });
  },
});

Custom File Copy

import { copyFile } from 'fs/promises';

export default defineConfig({
  hooks: {
    'build:done': async (context) => {
      // Copy README to dist
      await copyFile('README.md', `${context.options.outDir}/README.md`);
    },
  },
});

Build Metrics

export default defineConfig({
  hooks: {
    'build:prepare': (context) => {
      context.startTime = Date.now();
    },
    'build:done': (context) => {
      const duration = Date.now() - context.startTime;
      console.log(`Build took ${duration}ms`);

      // Log chunk sizes
      context.chunks.forEach((chunk) => {
        console.log(`${chunk.fileName}: ${chunk.code.length} bytes`);
      });
    },
  },
});

Format-Specific Logic

export default defineConfig({
  format: ['esm', 'cjs', 'iife'],
  hooks: {
    'build:before': (context) => {
      const format = context.buildOptions.format;

      if (format === 'iife') {
        // Browser-specific setup
        context.buildOptions.globalName = 'MyLib';
      } else if (format === 'cjs') {
        // Node-specific setup
        context.buildOptions.platform = 'node';
      }
    },
  },
});

Deployment Hook

export default defineConfig({
  hooks: {
    'build:done': async (context) => {
      if (process.env.DEPLOY === 'true') {
        console.log('Deploying to CDN...');
        await deployToCDN(context.options.outDir);
      }
    },
  },
});

Advanced Usage

Multiple Hooks

export default defineConfig({
  hooks(hooks) {
    // Register multiple hooks
    hooks.hook('build:prepare', setupEnvironment);
    hooks.hook('build:prepare', validateConfig);

    hooks.hook('build:before', injectPlugins);
    hooks.hook('build:before', logFormat);

    hooks.hook('build:done', generateManifest);
    hooks.hook('build:done', notifyComplete);
  },
});

Async Hooks

export default defineConfig({
  hooks: {
    'build:prepare': async (context) => {
      await fetchRemoteConfig();
      await initializeDatabase();
    },
    'build:done': async (context) => {
      await uploadToS3(context.chunks);
      await invalidateCDN();
    },
  },
});

Error Handling

export default defineConfig({
  hooks: {
    'build:done': async (context) => {
      try {
        await riskyOperation();
      } catch (error) {
        console.error('Hook failed:', error);
        // Don't throw - allow build to complete
      }
    },
  },
});

Hookable API

tsdown uses hookable for hooks. Additional methods:

export default defineConfig({
  hooks(hooks) {
    // Register hook
    hooks.hook('build:done', handler);

    // Register hook once
    hooks.hookOnce('build:prepare', handler);

    // Remove hook
    hooks.removeHook('build:done', handler);

    // Clear all hooks for event
    hooks.removeHooks('build:done');

    // Call hooks manually
    await hooks.callHook('build:done', context);
  },
});

Tips

1. Use plugins for most extensions
2. Hooks for simple tasks like notifications or file copying
3. Async hooks supported for I/O operations
4. Don't throw errors unless you want to fail the build
5. Context is mutable in build:before for advanced use cases
6. Multiple hooks allowed for the same event

Troubleshooting

Hook Not Called

• Verify hook name is correct
• Check hook is registered in config
• Ensure async hooks are awaited

Build Fails in Hook

• Add try/catch for error handling
• Don't throw unless intentional
• Log errors for debugging

Context Undefined

• Check which hook you're using
• Verify context properties available for that hook

Related

• Plugins - Plugin system
• Rolldown Options - Build options
• Watch Mode - Development workflow