### Loader Options Example

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/loader-system.md

An example demonstrating how to configure loader options, including file extension, module format, TypeScript declaration generation, esbuild settings, and PostCSS configurations for autoprefixer and cssnano.

```typescript
const options: LoaderOptions = {
  ext: 'mjs',
  format: 'esm',
  declaration: true,
  esbuild: {
    minify: true,
    target: 'es2020',
    jsx: 'automatic'
  },
  postcss: {
    autoprefixer: { overrideBrowserslist: ['last 2 versions'] },
    cssnano: { preset: ['default', { discardComments: { removeAll: true } }] }
  }
}
```

--------------------------------

### CLI Output Example

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/cli.md

Example of the output displayed by the Mkdist CLI after a successful build, listing the files written to the distribution directory.

```bash
$ mkdist
- /home/user/project/dist/index.mjs
- /home/user/project/dist/index.d.ts
- /home/user/project/dist/Button.vue
- /home/user/project/dist/styles.css
```

--------------------------------

### Vue Component Example

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/usage-patterns.md

A standard Vue 3 component using `<script setup>` with TypeScript props and emits. It includes scoped CSS for styling.

```vue
<template>
  <button :disabled="disabled" @click="handleClick">
    <slot />
  </button>
</template>

<script setup lang="ts">
export interface Props {
  disabled?: boolean
}

defineProps<Props>()

const emit = defineEmits<{
  click: [event: MouseEvent]
}>()

const handleClick = (e: MouseEvent) => emit('click', e)
</script>

<style scoped>
button {
  padding: 0.5rem 1rem;
  border: none;
  border-radius: 0.25rem;
  cursor: pointer;

  &:disabled {
    opacity: 0.5;
    cursor: not-allowed;
  }
}
</style>
```

--------------------------------

### Install mkdist Globally or Locally

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/cli.md

Install mkdist using npm. You can install it globally for direct command-line access or locally as a development dependency.

```bash
# Global installation
npm install -g mkdist
mkdist

# Local installation
npm install --save-dev mkdist
npx mkdist
```

--------------------------------

### OutputFile Example

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/loader-system.md

Defines the structure of a transformed file produced by a loader. This example shows a typical output file configuration.

```typescript
const output: OutputFile = {
  path: 'module.mjs',
  srcPath: '/project/src/module.ts',
  contents: 'export const value = 42;',
  extension: '.mjs',
  declaration: false
}
```

--------------------------------

### mkdist with Detailed Options

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/mkdist-core.md

Shows a comprehensive example of `mkdist` configuration, including custom root, source, and destination directories, glob patterns, loaders, TypeScript compiler options, and PostCSS configuration.

```typescript
const result = await mkdist({
  rootDir: process.cwd(),
  srcDir: 'src',
  distDir: 'dist',
  pattern: '**/*.{ts,tsx,js,jsx}',
  declaration: true,
  format: 'esm',
  ext: 'mjs',
  cleanDist: true,
  loaders: ['js', 'vue'],
  addRelativeDeclarationExtensions: true,
  typescript: {
    compilerOptions: {
      target: 'ES2020',
      moduleResolution: 'bundler'
    }
  },
  postcss: {
    autoprefixer: { overrideBrowserslist: ['last 2 versions'] },
    cssnano: {}
  }
})
```

--------------------------------

### Sass Partial File Example

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/loaders.md

Illustrates how partial SASS files (starting with '_') are handled by the Sass loader. These files are skipped from being written as standalone CSS files.

```typescript
const input = {
  path: '_variables.scss',
  extension: '.scss',
  srcPath: '/project/src/_variables.scss',
  getContents: async () => '$primary: #3498db;'
}

const outputs = await loadFile(input)
// Outputs: [{ path: '_variables.scss', skip: true }]
```

--------------------------------

### Example: Custom Declaration Processing with Mkdist

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/utilities.md

Demonstrates how to set up a virtual file system, normalize TypeScript compiler options, generate declarations using getDeclarations, and process the results, including error handling.

```typescript
import {
  normalizeCompilerOptions,
  getDeclarations,
  extractDeclarations
} from 'mkdist'

// Setup virtual file system
const vfs = new Map([
  ['/src/utils.ts', 'export const add = (a: number, b: number) => a + b']
])

// Normalize TypeScript options
const compilerOptions = await normalizeCompilerOptions({
  target: 'ES2020',
  strict: true
})

// Generate declarations
const output = await getDeclarations(vfs, {
  typescript: { compilerOptions }
})

// Process results
for (const [path, decl] of Object.entries(output)) {
  if (decl.errors) {
    console.error(`${path}: ${decl.errors.length} errors`)
  } else {
    console.log(`${path}: ${decl.contents.split('\n').length} lines`)
  }
}
```

--------------------------------

### VueBlock Type Example

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/vue-loader-advanced.md

Illustrates the structure of VueBlock objects for different Vue SFC block types, including script setup and style blocks, showing their content and attributes.

```typescript
// <script setup lang="ts">
const block = {
  type: 'scriptSetup',
  content: 'defineProps<{ title: string }>()',
  attrs: { lang: 'ts', setup: true }
}

// <style scoped>
const styleBlock = {
  type: 'style',
  content: '.button { color: blue; }',
  attrs: { scoped: true }
}
```

--------------------------------

### PostCSS Loader Example

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/loaders.md

Demonstrates using the PostCSS loader to process CSS files with default plugins like nested, autoprefixer, and cssnano. Configuration for each plugin is possible.

```typescript
import { createLoader } from 'mkdist'

const { loadFile } = createLoader({
  loaders: ['postcss'],
  postcss: {
    nested: {},
    autoprefixer: { overrideBrowserslist: ['last 2 versions'] },
    cssnano: { preset: ['default', { discardComments: { removeAll: true } }] }
  }
})

const input = {
  path: 'styles.css',
  extension: '.css',
  srcPath: '/project/src/styles.css',
  getContents: async () => `
.card {
  padding: 1rem;
  
  .title {
    font-weight: bold;
  }
}
  `
}

const outputs = await loadFile(input)
// Outputs: [{ path: 'styles.css', contents: '/* processed CSS */' }]
```

--------------------------------

### Sass Loader Example

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/loaders.md

Shows how to use the Sass loader to compile SASS/SCSS files into CSS. It supports node_modules for imports and skips partial files.

```typescript
import { createLoader } from 'mkdist'

const { loadFile } = createLoader({
  loaders: ['sass', 'postcss']
})

const input = {
  path: 'styles.scss',
  extension: '.scss',
  srcPath: '/project/src/styles.scss',
  getContents: async () => `
$primary: #3498db;

.button {
  background: $primary;
  padding: 0.5rem 1rem;
  
  &:hover {
    opacity: 0.8;
  }
}
  `
}

const outputs = await loadFile(input)
// Outputs: [{ path: 'styles.css', extension: '.css', contents: '/* compiled CSS */' }]
```

--------------------------------

### Programmatic API Build Configuration

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/cli.md

Example of configuring Mkdist programmatically in a TypeScript file, specifying source/distribution directories, declarations, format, loaders, and esbuild options.

```typescript
// build.ts
import { mkdist } from 'mkdist'

await mkdist({
  srcDir: 'src',
  distDir: 'dist',
  declaration: true,
  format: 'esm',
  ext: 'mjs',
  loaders: ['js', 'vue', 'postcss'],
  esbuild: {
    minify: true,
    target: 'es2020'
  }
})
```

--------------------------------

### Using Fallback Vue Loader

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/vue-loader-advanced.md

Demonstrates how to directly use the fallback Vue loader in mkdist when the vue-sfc-transformer is not installed, primarily for style block transformation.

```typescript
import { fallbackVueLoader, createLoader } from 'mkdist'

// Use fallback loader directly
const { loadFile } = createLoader({
  loaders: [fallbackVueLoader, 'js', 'postcss']
})
```

--------------------------------

### mkdist CLI Usage Example

Source: https://github.com/unjs/mkdist/blob/main/README.md

This is the primary command for using mkdist. It shows how to specify the root directory and various options like source and distribution paths, cleaning behavior, file patterns, module format, and TypeScript declaration generation.

```bash
npx mkdist [rootDir] [--src=src] [--dist=dist] [--no-clean] [--pattern=glob [--pattern=more-glob]] [--format=cjs|esm] [-d|--declaration] [--ext=mjs|js|ts]
```

--------------------------------

### DeclarationOutput Type Example

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/declarations.md

Illustrates the structure of `DeclarationOutput`, which maps source file paths to their generated declaration contents and any associated TypeScript errors.

```typescript
const output: DeclarationOutput = {
  '/project/src/utils.ts': {
    contents: 'export declare const add: (a: number, b: number) => number;',
    errors: []
  },
  '/project/src/bad.ts': {
    contents: 'export {}',
    errors: [
      new TypeError('Type error: Expected number, got string')
    ]
  }
}
```

--------------------------------

### Default Block Loader Examples

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/vue-loader-advanced.md

Creates standard block loaders for style and script blocks. `styleLoader` outputs CSS and accepts SCSS, while `scriptLoader` outputs TypeScript. Use these for common transformations.

```typescript
import { defineDefaultBlockLoader } from 'mkdist'

// Style loader that outputs CSS
const styleLoader = defineDefaultBlockLoader({
  type: 'style',
  outputLang: 'css',
  validExtensions: ['.css', '.scss']
})

// Script loader that outputs TypeScript
const scriptLoader = defineDefaultBlockLoader({
  type: 'script',
  outputLang: 'ts'
})
```

--------------------------------

### InputFile

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/types.md

Represents a source file to be processed, including its path, extension, and a method to get its contents.

```APIDOC
## InputFile

### Description
Represents a source file to be processed.

### Type Definition
```typescript
interface InputFile {
  path: string
  extension: string
  srcPath?: string
  getContents: () => Promise<string> | string
}
```

### Fields
- **path** (`string`) - Relative path from source directory
- **extension** (`string`) - File extension with dot (e.g., `".ts"`)
- **srcPath** (`string`) - Absolute path to source file (optional)
- **getContents** (`Function`) - Returns file contents as UTF-8 string

### Used In
`LoadFile` parameter, `VueBlockLoader` parameter
```

--------------------------------

### Vue SFC Loader Example

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/loaders.md

Demonstrates how to use the Vue loader to process a Vue Single File Component. It handles parsing SFC structure, applying block loaders, and generating declaration files.

```typescript
import { createLoader } from 'mkdist'

const { loadFile } = createLoader({
  loaders: ['vue', 'postcss']
})

const input = {
  path: 'Button.vue',
  extension: '.vue',
  srcPath: '/project/src/Button.vue',
  getContents: async () => `
<template>
  <button><slot /></template>
<script setup lang="ts">
export interface Props {
  disabled?: boolean
}
</script>
<style scoped>
button {
  padding: 0.5rem 1rem;
}
</style>
  `
}

const outputs = await loadFile(input)
// Outputs declaration and processed Vue file
```

--------------------------------

### Build Monorepo Package

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/usage-patterns.md

Configure mkdist for building a package within a monorepo. This setup uses 'rootDir' to resolve paths relative to the package directory and generates declaration files.

```typescript
// packages/utils/build.ts
import { mkdist } from 'mkdist'

await mkdist({
  rootDir: import.meta.dirname,
  srcDir: 'src',
  distDir: 'dist',
  declaration: true
})
```

--------------------------------

### Build React Library with JSX

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/usage-patterns.md

Configure mkdist to build a React library, enabling automatic JSX runtime transformation. This setup generates ES modules with type definitions.

```typescript
// build.ts
import { mkdist } from 'mkdist'

await mkdist({
  srcDir: 'src',
  distDir: 'dist',
  declaration: true,
  format: 'esm',
  esbuild: {
    jsx: 'automatic',
    target: 'es2020'
  }
})
```

--------------------------------

### InputFile Interface

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/types.md

Represents a source file to be processed, including its path, extension, optional source path, and a method to get its contents.

```typescript
interface InputFile {
  path: string
  extension: string
  srcPath?: string
  getContents: () => Promise<string> | string
}
```

--------------------------------

### Implement a Custom Vue Loader

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/README.md

Define a custom loader function for Vue projects. This example shows how to create a loader that handles a '.custom' file extension.

```typescript
const customLoader: Loader = async (input, { loadFile }) => {
  if (input.extension === '.custom') {
    // Transform and return
  }
}

await mkdist({ loaders: [customLoader, 'js'] })
```

--------------------------------

### Custom Vue Block Loader Implementation

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/vue-loader-advanced.md

Example of a custom Vue block loader that handles a specific block type ('custom'). It demonstrates transforming block content using other loaders and adding output files.

```typescript
import type { VueBlockLoader } from 'mkdist'

const customBlockLoader: VueBlockLoader = async (
  block,
  { loadFile, rawInput, addOutput, options }
) => {
  // Only handle custom block type
  if (block.type !== 'custom') return

  // Transform block content through loaders
  const lang = block.attrs.lang || 'js'
  const files = await loadFile({
    getContents: () => block.content,
    path: `${rawInput.path}.${lang}`,
    srcPath: `${rawInput.srcPath}.${lang}`,
    extension: `.${lang}`
  })

  if (!files?.length) return

  // Use transformed content
  const mainFile = files[0]
  const otherFiles = files.slice(1)

  addOutput(...otherFiles)

  return {
    ...block,
    content: mainFile.contents || ''
  }
}
```

--------------------------------

### Configure jsLoader for TypeScript and Declarations

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/loaders.md

Use `createLoader` to configure the 'js' loader for specific formats, extensions, and features like TypeScript declaration file generation. This example sets up esbuild options for minification and target.

```typescript
import { createLoader } from 'mkdist'

const { loadFile } = createLoader({
  format: 'esm',
  ext: 'mjs',
  declaration: true,
  esbuild: {
    minify: true,
    target: 'es2020',
    jsx: 'automatic'
  }
})
```

--------------------------------

### Build Vue Component Library

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/usage-patterns.md

Configure mkdist to build Vue Single File Components (SFCs) along with associated styles and TypeScript definitions. This setup supports ESM output and specifies loaders for Vue, Sass, and PostCSS.

```typescript
// build.ts
import { mkdist } from 'mkdist'

await mkdist({
  srcDir: 'src',
  distDir: 'dist',
  loaders: ['vue', 'sass', 'postcss'],
  declaration: true,
  format: 'esm',
  ext: 'mjs',
  esbuild: {
    target: 'es2020',
    jsx: 'preserve'
  }
})
```

--------------------------------

### Custom Vue Loader Example

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/vue-loader-advanced.md

Defines a custom Vue loader that handles SASS for style blocks and processes script blocks by loading them as separate files. Use this to integrate custom preprocessors or complex script transformations.

```typescript
import { defineVueLoader, defineDefaultBlockLoader } from 'mkdist'
import type { VueBlockLoader } from 'mkdist'

// Custom style block loader that handles SASS
const customStyleLoader = defineDefaultBlockLoader({
  type: 'style',
  outputLang: 'css'
})

// Custom loader for script blocks
const customScriptLoader: VueBlockLoader = async (
  block,
  { loadFile, rawInput, addOutput }
) => {
  if (block.type !== 'script') return

  const lang = block.attrs.lang || 'js'
  const extension = `.${lang}`

  const files = await loadFile({
    getContents: () => block.content,
    path: `${rawInput.path}${extension}`,
    srcPath: `${rawInput.srcPath}${extension}`,
    extension
  })

  const scriptFile = files?.find(f => f.extension === `.${lang}`)
  if (!scriptFile) return

  addOutput(...files.filter(f => f !== scriptFile))

  return {
    type: 'script',
    attrs: block.attrs,
    content: scriptFile.contents || ''
  }
}

const loader = defineVueLoader({
  blockLoaders: {
    style: customStyleLoader,
    script: customScriptLoader
  }
})
```

--------------------------------

### Running npm Build Scripts

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/cli.md

Demonstrates how to execute the defined npm build scripts from the command line.

```bash
npm run build
npm run build:prod
```

--------------------------------

### Basic CLI Build

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/README.md

Perform a basic build using the mkdist command-line interface. This command specifies the source and distribution directories and enables declaration file generation.

```bash
mkdist --src src --dist dist --declaration
```

--------------------------------

### Custom Source and Distribution Directories

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/cli.md

Specifies custom source and distribution directories for the build process. Code from 'lib/' will be built into 'output/'.

```bash
mkdist --src lib --dist output
# lib/ → output/
```

--------------------------------

### Basic mkdist Usage

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/mkdist-core.md

Demonstrates a basic usage of the `mkdist` function to transform files from a source directory to a destination directory, including declaration generation.

```typescript
import { mkdist } from 'mkdist'

const result = await mkdist({
  rootDir: '/home/user/project',
  srcDir: 'src',
  distDir: 'dist',
  declaration: true,
  format: 'esm'
})

console.log(`Wrote ${result.writtenFiles.length} files`)
if (result.errors.length > 0) {
  console.error('Declaration errors:', result.errors)
}
```

--------------------------------

### Production Build Configuration

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/cli.md

Creates a production-ready build with ES modules, type declarations, minification, and a specific target, while preserving the dist directory.

```bash
mkdist \
  --format esm \
  --ext mjs \
  --declaration \
  --minify \
  --target es2020 \
  --no-clean
# ES modules, declarations, minified, target ES2020, preserve dist
```

--------------------------------

### CLI Build with Vue and Styles

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/README.md

Use the mkdist CLI to build projects that include Vue components and styles. This command enables the 'vue', 'sass', and 'postcss' loaders and generates declaration files.

```bash
mkdist --loaders vue,sass,postcss --declaration
```

--------------------------------

### Running Programmatic Build Script

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/cli.md

Shows how to execute a TypeScript build script using `jiti` or `node` with the `--loader` flag.

```bash
npx jiti build.ts
# or
node --loader jiti build.ts
```

--------------------------------

### React Component Example

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/usage-patterns.md

A simple React functional component with TypeScript props, including default values and type checking. It uses JSX with the automatic runtime.

```typescript
// src/Button.tsx
import type { ReactNode } from 'react'

interface ButtonProps {
  children?: ReactNode
  onClick?: () => void
  variant?: 'primary' | 'secondary'
}

export const Button = ({
  children,
  onClick,
  variant = 'primary'
}: ButtonProps) => {
  return (
    <button className={`btn btn-${variant}`} onClick={onClick}>
      {children}
    </button>
  )
}
```

--------------------------------

### Use Built-in Loaders in mkdist

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/loaders.md

Specify loader names in the `loaders` array when configuring mkdist. This example shows using 'js', 'vue', and 'postcss' loaders.

```typescript
import { mkdist } from 'mkdist'

// Use loader names
await mkdist({
  loaders: ['js', 'vue', 'postcss']
})
```

--------------------------------

### Create Loader Context

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/loader-system.md

Initializes the loader system with specified options and a chain of loaders. Use this to set up the file transformation pipeline.

```typescript
import { createLoader } from 'mkdist'

const { loadFile } = createLoader({
  format: 'esm',
  declaration: true,
  loaders: ['js', 'postcss']
})

const input = {
  path: 'index.ts',
  extension: '.ts',
  srcPath: '/project/src/index.ts',
  getContents: () => import('fs').then(fs => 
    fs.promises.readFile('/project/src/index.ts', 'utf-8')
  )
}

const outputs = await loadFile(input)
```

--------------------------------

### Basic Library Build with mkdist

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/README.md

Use this snippet to perform a basic build for a TypeScript library. It configures the source and distribution directories, enables declaration file generation, and sets the output format to ES modules.

```typescript
import {
  mkdist
} from 'mkdist'

await mkdist({
  srcDir: 'src',
  distDir: 'dist',
  declaration: true,
  format: 'esm'
})
```

--------------------------------

### Hook into Declaration Generation in Mkdist

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/utilities.md

Illustrates how to hook into the declaration generation process in Mkdist to handle errors or perform custom actions. This example shows processing declaration errors.

```typescript
import { mkdist } from 'mkdist'

const result = await mkdist({
  declaration: true,
  typescript: {
    compilerOptions: {
      strict: true
    }
  }
})

// Process results
for (const { filename, errors } of result.errors) {
  console.error(`${filename}: Declaration errors`)
  errors.forEach(e => console.error(e.message))
}
```

--------------------------------

### Relative Declaration Extension Handling Example

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/declarations.md

Illustrates how mkdist modifies relative import paths in declaration files when `addRelativeDeclarationExtensions` is enabled. This ensures correct module resolution in the generated types.

```typescript
// With addRelativeDeclarationExtensions: true
// Input: import { utils } from './utils'
// Output: import { utils } from './utils.js'

// With directory import
// Input: import { config } from './config'
// Output: import { config } from './config/index.js'
```

--------------------------------

### Resolve Custom Set of Loaders

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/loaders.md

Provide an array of loader names or custom functions to `resolveLoaders` to get a specific set of resolved loaders. Invalid entries are logged as warnings and excluded.

```typescript
// Custom set
const loaders2 = resolveLoaders(['js', 'postcss'])
// Returns: [jsLoader, postcssLoader]
```

```typescript
const custom = async (input, ctx) => {
  if (input.extension === '.custom') {
    return [{ path: input.path, contents: 'export {}' }]
  }
}
const loaders3 = resolveLoaders([custom, 'js'])
// Returns: [custom, jsLoader]
```

--------------------------------

### Selective File Processing with Patterns

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/usage-patterns.md

Demonstrates how to use the 'pattern' option in Mkdist to build only specific file types, directories, or to exclude certain files from the build process.

```typescript
// build.ts
import { mkdist } from 'mkdist'

// Only TypeScript files
await mkdist({
  pattern: '**/*.ts',
  declaration: true
})

// Vue components only
await mkdist({
  pattern: '**/*.vue',
  loaders: ['vue', 'postcss']
})

// Exclude test files
await mkdist({
  pattern: ['**', '!**/*.spec.ts', '!**/__tests__/**']
})

// Specific directories
await mkdist({
  pattern: ['src/core/**', 'src/utils/**']
})
```

--------------------------------

### Including Pre-built Vendor Files

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/usage-patterns.md

Integrates pre-built vendor files into the build process without transformation by using a custom loader that marks files for raw copying.

```typescript
import { mkdist } from 'mkdist'
import type { Loader } from 'mkdist'

// Skip transformation for vendor files
const vendorLoader: Loader = async (input) => {
  if (!input.path.startsWith('vendor/')) return

  // Raw copy without transformation
  return [{
    path: input.path,
    srcPath: input.srcPath,
    raw: true
  }]
}

await mkdist({
  loaders: [vendorLoader, 'js', 'vue']
})
```

--------------------------------

### CLI Production Build

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/README.md

Execute a production build using the mkdist CLI, enabling minification, declaration file generation, and targeting ES2020. This is suitable for optimizing output for modern environments.

```bash
mkdist --minify --declaration --target es2020
```

--------------------------------

### Custom Loader Implementation in Mkdist

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/utilities.md

Shows how to create a custom loader to transform a custom file format (e.g., '.custom') into JavaScript. The loader defines how to process the input and what the output should be.

```typescript
import type { Loader } from 'mkdist'

const customLoader: Loader = async (input, { options }) => {
  if (input.extension !== '.custom') return

  const content = await input.getContents()
  
  // Transform content
  const transformed = transformCustomFormat(content)

  return [{
    path: input.path,
    contents: transformed,
    extension: '.js'
  }]
}

// Use in mkdist
await mkdist({
  loaders: [customLoader, 'js', 'vue']
})
```

--------------------------------

### Chaining Loaders in Mkdist

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/utilities.md

Demonstrates how to create a custom loader that chains other loaders. This allows processing a file through multiple transformations, such as converting a custom component format to TypeScript.

```typescript
import type { Loader } from 'mkdist'

const chainLoader: Loader = async (input, { loadFile }) => {
  if (!input.path.endsWith('.component')) return

  // Process through other loaders
  const tsFile = {
    ...input,
    extension: '.ts',
    getContents: async () => {
      const content = await input.getContents()
      return transformToTypeScript(content)
    }
  }

  return loadFile(tsFile)
}
```

--------------------------------

### Configure Loaders for Transformation

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/configuration.md

Specify loaders to apply during transformation. Loaders are applied sequentially, and the first matching loader handles the file. This example shows default loaders, only JS, Vue and styles, and a custom loader.

```typescript
await mkdist()
```

```typescript
await mkdist({ loaders: ['js'] })
```

```typescript
await mkdist({ loaders: ['vue', 'sass', 'postcss'] })
```

```typescript
const customLoader = async (input, ctx) => {
  if (input.extension === '.custom') {
    return [{ path: input.path, contents: 'export {}' }]
  }
}

await mkdist({ loaders: [customLoader, 'js', 'vue'] })
```

--------------------------------

### Basic Build with Watch Mode

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/usage-patterns.md

Sets up a basic build process for TypeScript projects, including declaration file generation and an optional watch mode for continuous development.

```typescript
// build.ts
import { mkdist } from 'mkdist'
import { watch } from 'node:fs'

async function build() {
  const result = await mkdist({
    srcDir: 'src',
    distDir: 'dist',
    declaration: true,
    cleanDist: false  // Don't clean, just update
  })

  console.log(`Built ${result.writtenFiles.length} files`)
  if (result.errors.length > 0) {
    console.error(`${result.errors.length} declaration errors`)
  }
}

if (process.argv.includes('--watch')) {
  console.log('Watching src/ for changes...')
  
  watch('src', { recursive: true }, async () => {
    try {
      await build()
    } catch (error) {
      console.error('Build failed:', error)
    }
  })
} else {
  await build()
}
```

```json
{
  "scripts": {
    "build": "jiti build.ts",
    "dev": "jiti build.ts --watch"
  }
}
```

--------------------------------

### MkdistOptions

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/types.md

Configuration object for the `mkdist()` function. It extends `LoaderOptions` and provides specific settings for the build process.

```APIDOC
## MkdistOptions

### Description
Configuration object for the `mkdist()` function. Extends `LoaderOptions`.

### Type Definition
```typescript
interface MkdistOptions extends LoaderOptions {
  rootDir?: string
  srcDir?: string
  pattern?: string | string[]
  globOptions?: GlobOptions
  distDir?: string
  cleanDist?: boolean
  loaders?: (LoaderName | Loader)[]
  addRelativeDeclarationExtensions?: boolean
  typescript?: {
    compilerOptions?: TSConfig["compilerOptions"]
  }
}
```

### Used By
`mkdist()`
```

--------------------------------

### Generate TypeScript Declarations for Vue SFCs

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/declarations.md

This function generates TypeScript declarations from Vue Single File Components. It requires a virtual file system map of SFCs and optional build options. Ensure `vue-tsc` is installed for this functionality.

```typescript
import { getVueDeclarations } from 'mkdist'

const vfs = new Map([
  ['/src/Button.vue.ts', 'export interface Props { disabled?: boolean }'],
  ['/src/Button.vue.js', 'export default {}']
])

const result = await getVueDeclarations(vfs, {
  typescript: {
    compilerOptions: { strict: true }
  }
})

console.log(result)
// {
//   '/src/Button.vue': {
//     contents: 'export interface Props { disabled?: boolean }',
//     errors: []
//   }
// }
```

--------------------------------

### Configure esbuild for JavaScript/TypeScript Transformation

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/configuration.md

Pass options to esbuild for JavaScript/TypeScript transformation, controlling target, minification, JSX handling, and source maps. Examples include modern ES2020 target, React JSX, Vue JSX, and inline source maps.

```typescript
await mkdist({
  esbuild: {
    target: 'es2020',
    minify: true
  }
})
```

```typescript
await mkdist({
  esbuild: {
    jsx: 'automatic',
    jsxFactory: 'React.createElement',
    jsxFragment: 'React.Fragment'
  }
})
```

```typescript
await mkdist({
  esbuild: {
    jsx: 'transform',
    jsxFactory: 'h',
    jsxFragment: 'Fragment'
  }
})
```

```typescript
await mkdist({
  esbuild: {
    sourcemap: 'inline'
  }
})
```

--------------------------------

### Set Source Directory

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/cli.md

Use the --src option to specify a custom directory for input files. This overrides the default 'src' directory.

```bash
mkdist --src source
mkdist --src lib
```

--------------------------------

### getVueDeclarations

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/declarations.md

Generates TypeScript declarations for Vue Single File Components. It maps Vue files to their source TypeScript files, checks for vue-tsc installation, uses the appropriate emission function based on the vue-tsc version, maps declarations back to original Vue paths, and augments output with compiler diagnostics.

```APIDOC
## Function: getVueDeclarations

Generates TypeScript declarations for Vue Single File Components.

### Signature

```typescript
async function getVueDeclarations(
  vfs: Map<string, string>,
  opts?: MkdistOptions
): Promise<DeclarationOutput>
```

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| vfs | `Map<string, string>` | Virtual file system containing compiled Vue SFC files |
| opts | `MkdistOptions` | Build options including TypeScript configuration |

### Return Type

`Promise<DeclarationOutput>` — Map of Vue file paths to generated declarations.

### Behavior

1. Maps Vue files (`.vue`) to their source TypeScript files (`.vue.ts`)
2. Checks if `vue-tsc` is installed; warns and returns early if not
3. Detects `vue-tsc` version and uses appropriate emission function:
   - **v1.8.27**: Uses `emitVueTscV1` with vue-tsc v1 API
   - **v2.0.x**: Uses `emitVueTscV2` with Volar TypeScript integration
   - **Latest**: Uses `emitVueTscLatest` with newest Volar API
4. Maps generated declarations back from TypeScript source paths to original Vue paths
5. Augments output with compiler diagnostics

### Example

```typescript
import { getVueDeclarations } from 'mkdist'

const vfs = new Map([
  ['/src/Button.vue.ts', 'export interface Props { disabled?: boolean }'],
  ['/src/Button.vue.js', 'export default {}']
])

const result = await getVueDeclarations(vfs, {
  typescript: {
    compilerOptions: { strict: true }
  }
})

console.log(result)
// {
//   '/src/Button.vue': {
//     contents: 'export interface Props { disabled?: boolean }',
//     errors: []
//   }
// }
```
```

--------------------------------

### Configure Production Build

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/configuration.md

Optimize Mkdist for production builds. This configuration sets the module format to ESM, generates type declarations, enables minification and targets a specific ECMAScript version via esbuild, and includes CSS minification via PostCSS.

```typescript
await mkdist({
  format: 'esm',
  ext: 'mjs',
  declaration: true,
  esbuild: {
    minify: true,
    target: 'es2020'
  },
  postcss: {
    cssnano: {}
  }
})
```

--------------------------------

### Configure Incremental/Development Build

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/configuration.md

Set up Mkdist for incremental development builds. This configuration disables cleaning the distribution directory to preserve existing files and enables source maps for easier debugging.

```typescript
await mkdist({
  cleanDist: false,
  esbuild: {
    sourcemap: true
  }
})
```

--------------------------------

### Basic mkdist Command Syntax

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/cli.md

The fundamental command structure for mkdist. It accepts an optional root directory and various options to control the transformation process.

```bash
mkdist [rootDir] [options]
```

--------------------------------

### Production Build with Optimization

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/usage-patterns.md

Use this snippet for a large library build with optimizations like minification and tree shaking. It configures esbuild and postcss for production.

```typescript
// build.ts
import { mkdist } from 'mkdist'

// Large library build with optimization
await mkdist({
  srcDir: 'src',
  distDir: 'dist',
  declaration: true,
  format: 'esm',
  ext: 'mjs',
  esbuild: {
    minify: true,
    target: 'es2020',
    treeShaking: true,
    legalComments: 'none'
  },
  postcss: {
    cssnano: {
      preset: ['default', {
        discardComments: { removeAll: true }
      }]
    }
  }
})

console.log('Production build complete')
```

--------------------------------

### Enable Minification

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/cli.md

Use the --minify flag to enable minification of the output JavaScript and CSS files. This reduces file size for production deployments.

```bash
mkdist --minify
```

--------------------------------

### npm Scripts for Building

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/cli.md

Defines various build scripts in `package.json` for different build configurations, including default, CommonJS, ESM, declarations, and production builds.

```json
{
  "scripts": {
    "build": "mkdist",
    "build:cjs": "mkdist --format cjs",
    "build:esm": "mkdist --format esm --ext mjs",
    "build:declarations": "mkdist --declaration",
    "build:prod": "mkdist --minify --declaration --target es2020"
  }
}
```

--------------------------------

### Basic Usage

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/cli.md

Transforms TypeScript source files to JavaScript using default settings. Outputs to 'dist/' in ESM format.

```bash
mkdist
# Uses defaults: src/ → dist/, ESM format
```

--------------------------------

### MkdistOptions Interface

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/mkdist-core.md

Defines the configuration options for the mkdist function, including directory settings, file patterns, loaders, and TypeScript configurations.

```APIDOC
## Interface: MkdistOptions

Configuration for the `mkdist` function. Extends `LoaderOptions` with project-level settings.

### Properties

| Property | Type | Required | Default | Description |
|----------|------|----------|---------|-------------|
| `rootDir` | `string` | No | `"."` | Root directory for all relative path resolution. Resolved relative to current working directory. |
| `srcDir` | `string` | No | `"src"` | Source directory containing input files. Resolved relative to `rootDir`. |
| `distDir` | `string` | No | `"dist"` | Output directory for transformed files. Resolved relative to `rootDir`. |
| `cleanDist` | `boolean` | No | `true` | Whether to remove and recreate `distDir` before processing files. |
| `pattern` | `string | string[]` | No | `"**"` | Glob pattern(s) to match input files in `srcDir`. |
| `globOptions` | `GlobOptions` | No | `undefined` | Options passed to glob pattern matcher (tinyglobby). |
| `loaders` | `(LoaderName | Loader)[]` | No | `["js", "vue", "sass", "postcss"]` | List of loaders to apply. Can be loader names or custom Loader functions. |
| `addRelativeDeclarationExtensions` | `boolean` | No | `false` | Whether to add file extensions to relative import paths in generated `.d.ts` files. |
| `typescript` | `{ compilerOptions?: TSConfig["compilerOptions"] }` | No | `{}` | TypeScript compiler options for `.d.ts` generation. |
| `ext` | `"js" | "mjs" | "cjs" | "ts" | "mts" | "cts"` | No | — | Output file extension (from `LoaderOptions`). |
| `format` | `"cjs" | "esm"` | No | — | Output module format (from `LoaderOptions`). |
| `declaration` | `boolean` | No | — | Generate TypeScript declaration files (from `LoaderOptions`). |
| `esbuild` | `CommonOptions` | No | — | esbuild configuration options (from `LoaderOptions`). |
| `postcss` | `false | PostcssLoaderConfig` | No | — | PostCSS configuration (from `LoaderOptions`). |

### TypeScript Configuration Defaults

When `typescript.compilerOptions` is provided, they are merged with these defaults:

```typescript
{
  noEmit: false,
  allowJs: true,
  declaration: true,
  skipLibCheck: true,
  strictNullChecks: true,
  emitDeclarationOnly: true,
  allowImportingTsExtensions: true,
  allowNonTsExtensions: true
}
```

### Example

```typescript
const result = await mkdist({
  rootDir: process.cwd(),
  srcDir: 'src',
  distDir: 'dist',
  pattern: '**/*.{ts,tsx,js,jsx}',
  declaration: true,
  format: 'esm',
  ext: 'mjs',
  cleanDist: true,
  loaders: ['js', 'vue'],
  addRelativeDeclarationExtensions: true,
  typescript: {
    compilerOptions: {
      target: 'ES2020',
      moduleResolution: 'bundler'
    }
  },
  postcss: {
    autoprefixer: { overrideBrowserslist: ['last 2 versions'] },
    cssnano: {}
  }
})
```
```

--------------------------------

### Override Output File Extension

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/cli.md

Use the --ext option to specify a custom file extension for the output files. This can be useful for compatibility or specific build requirements.

```bash
mkdist --ext mjs        # .mjs files
mkdist --ext cjs        # .cjs files
mkdist --ext .js        # .js files
```

--------------------------------

### Build Script with Error Handling

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/usage-patterns.md

This snippet demonstrates a build script with comprehensive error handling. It checks for declaration errors and logs them, exiting with a non-zero code on failure.

```typescript
// build.ts
import { mkdist } from 'mkdist'

async function build() {
  try {
    const result = await mkdist({
      srcDir: 'src',
      distDir: 'dist',
      declaration: true
    })

    console.log(`✓ Built ${result.writtenFiles.length} files`)

    if (result.errors.length > 0) {
      console.error(`
⚠ Declaration errors (${result.errors.length}):`)
      for (const { filename, errors } of result.errors) {
        console.error(`
  ${filename}:`)
        for (const error of errors) {
          console.error(`    ${error.message}`)
        }
      }
      process.exit(1)
    }
  } catch (error) {
    console.error('Build failed:', error)
    process.exit(1)
  }
}

await build()
```

--------------------------------

### Minified Production Build Configuration

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/usage-patterns.md

Configures Mkdist for production builds with minification, sourcemaps, and target specification. It uses environment variables to toggle production-specific settings.

```typescript
// build.ts
import { mkdist } from 'mkdist'

const isProd = process.env.NODE_ENV === 'production'

await mkdist({
  srcDir: 'src',
  distDir: 'dist',
  declaration: true,
  format: 'esm',
  ext: 'mjs',
  esbuild: {
    minify: isProd,
    sourcemap: !isProd,
    target: 'es2020'
  },
  postcss: isProd ? {} : { cssnano: false }
})
```

```json
{
  "scripts": {
    "build:dev": "jiti build.ts",
    "build:prod": "NODE_ENV=production jiti build.ts"
  }
}
```

--------------------------------

### Dual-Package Build (CommonJS + ESM)

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/README.md

This snippet demonstrates how to configure mkdist for dual-package support, generating both CommonJS and ES module outputs. It specifies different distribution directories and file extensions for each format, while enabling declaration file generation for both.

```typescript
await Promise.all([
  mkdist({
    distDir: 'dist/cjs',
    format: 'cjs',
    ext: 'cjs',
    declaration: true
  }),
  mkdist({
    distDir: 'dist/esm',
    format: 'esm',
    ext: 'mjs',
    declaration: true
  })
])
```

--------------------------------

### Build Basic TypeScript Library

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/usage-patterns.md

Use this snippet to transform TypeScript source files into ES modules with generated type definitions. Ensure your project has 'src' and 'dist' directories configured.

```typescript
// build.ts
import { mkdist } from 'mkdist'

await mkdist({
  srcDir: 'src',
  distDir: 'dist',
  declaration: true,
  format: 'esm'
})
```

--------------------------------

### LoaderOptions

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/types.md

Configuration options for loaders, including file extensions, module formats, and esbuild/postcss settings.

```APIDOC
## LoaderOptions

### Description
Configuration for loaders.

### Type Definition
```typescript
interface LoaderOptions {
  ext?: "js" | "mjs" | "cjs" | "ts" | "mts" | "cts"
  format?: "cjs" | "esm"
  declaration?: boolean
  esbuild?: CommonOptions
  postcss ?:
    | false
    | {
        nested?: false | PostcssNestedOptions
        autoprefixer?: false | AutoprefixerOptions
        cssnano?: false | CssnanoOptions
        plugins?: PostcssPlugin[]
        processOptions?: Omit<PostcssProcessOptions, "from">
      }
}
```

### Fields
- **ext** (`string`) - Output file extension (optional)
- **format** (`"cjs" | "esm"`) - Module format (optional)
- **declaration** (`boolean`) - Generate `.d.ts` files (optional)
- **esbuild** (`Object`) - esbuild transform options (optional)
- **postcss** (`Object`) - PostCSS plugin configuration (optional)

### Used In
`MkdistOptions`, `LoaderContext.options`
```

--------------------------------

### Build Library with ES Modules and Types

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/configuration.md

Configure Mkdist to build a library using ES modules and generate TypeScript declaration files. Specifies source and distribution directories, module format, file extension, and TypeScript compiler options.

```typescript
await mkdist({
  srcDir: 'src',
  distDir: 'dist',
  format: 'esm',
  ext: 'mjs',
  declaration: true,
  typescript: {
    compilerOptions: {
      strict: true,
      skipLibCheck: true
    }
  }
})
```

--------------------------------

### Set Module Output Format

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/cli.md

Use the --format option to specify the module system for the output files. Supported formats are 'cjs' (CommonJS) and 'esm' (ES modules).

```bash
mkdist --format cjs      # Output CommonJS
mkdist --format esm      # Output ES modules
```

--------------------------------

### Configure Source Directory for mkdist

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/configuration.md

Define the source directory containing input files. mkdist scans this directory for files matching the specified glob pattern. Defaults to 'src'.

```typescript
await mkdist({ srcDir: 'src' })

// Alternative structure
await mkdist({ srcDir: 'lib' })

// Multiple entry points (use with custom loaders)
await mkdist({ srcDir: 'packages/core/src' })
```

--------------------------------

### Build with Output Validation

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/usage-patterns.md

This build script includes output validation to ensure declarations exist and are not empty, and verifies the entry point. It logs warnings for empty declarations and throws an error if the entry point is missing.

```typescript
// build.ts
import { mkdist } from 'mkdist'
import fs from 'node:fs/promises'
import path from 'node:path'

async function build() {
  const result = await mkdist({
    srcDir: 'src',
    distDir: 'dist',
    declaration: true
  })

  // Validate declarations exist
  for (const file of result.writtenFiles) {
    if (file.endsWith('.d.ts')) {
      const content = await fs.readFile(file, 'utf-8')
      if (!content.includes('export')) {
        console.warn(`Empty declaration: ${file}`)
      }
    }
  }

  // Verify entry point
  const entryPoint = path.join('dist', 'index.mjs')
  if (!result.writtenFiles.includes(entryPoint)) {
    throw new Error(`Entry point ${entryPoint} not found`)
  }

  console.log('✓ All validation checks passed')
  return result
}

await build()
```

--------------------------------

### package.json for Basic TypeScript Library

Source: https://github.com/unjs/mkdist/blob/main/_autodocs/usage-patterns.md

Configure your package.json to specify the main module export and type definitions for your library. The 'build' script uses 'jiti' to execute the build script.

```json
{
  "name": "my-lib",
  "type": "module",
  "exports": "./dist/index.mjs",
  "types": "./dist/index.d.ts",
  "scripts": {
    "build": "jiti build.ts"
  }
}
```