mkdist

mkdist is a lightweight file-to-file transformer designed to process files while preserving their original structure. Unlike traditional bundlers, it avoids losing modern syntax or original file organization.

Key features include:

• Asset Preservation: Copies all assets automatically.
• Vue Support: Handles Vue Single File Components (.vue).
• High Performance: Uses esbuild for fast, minimal transformations.
• Type Generation: Generates .d.ts declaration files for .ts, .js, and .vue files.
• PostCSS Integration: Built-in support for postcss with autoprefixer, cssnano, and postcss-nested enabled by default.

When using unbuild to configure the mkdist build process, you can use the externals option to specify which dependencies should be treated as external and not bundled into the output. This is useful for preventing the inclusion of large or environment-specific packages like sass in your distribution.

import { defineBuildConfig } from "unbuild";

export default defineBuildConfig({
  externals: ["sass"]
});

To use the standard UNJS linting configuration in your project, import eslint-config-unjs and export it as the default configuration in your eslint.config.mjs file. The configuration function accepts an options object that allows you to define global ignores, custom ESLint rules, and specific overrides for Markdown linting.

import unjs from "eslint-config-unjs";

export default unjs({
  ignores: ["**/dist/**"],
  rules: {
    "@typescript-eslint/no-empty-object-type": 0,
  },
  markdown: {
    rules: {
      // markdown rule overrides
    },
  },
});

You can customize how specific blocks (like <script>, <style>, or custom blocks) are handled by using defineVueLoader. This allows you to intercept blocks and transform their content or extract them into separate files.

DefineVueLoaderOptions accepts a blockLoaders object where keys are the block types (e.g., 'style', 'script', 'template') and values are VueBlockLoader functions.

import { defineVueLoader, type DefineVueLoaderOptions } from 'mkdist/loaders/vue';

const options: DefineVueLoaderOptions = {
  blockLoaders: {
    style: async (block, context) => {
      // 'block' contains { type, content, attrs }
      // 'context' provides access to loadFile and addOutput
      return block; // Return modified block or undefined to skip
    }
  }
};

const myLoader = defineVueLoader(options);

The mkdist function returns a Promise that resolves to an object containing the results of the operation:

• writtenFiles: An array of absolute paths to the files successfully written to the distDir.
• errors: An array of error objects. Each object contains:
  • filename: The absolute path of the file that encountered an error.
  • errors: An array of TypeError objects associated with that file.

const { writtenFiles, errors } = await mkdist({
  srcDir: 'src',
  distDir: 'dist'
});

if (errors.length > 0) {
  console.error('Errors occurred:', errors);
}

console.log('Files written:', writtenFiles);

The mkdist function is the primary entry point for transforming source files (like TypeScript or Vue) into a distribution directory (like ESM/CJS). It scans a source directory based on a pattern, applies loaders to transform files, resolves relative import paths to ensure compatibility with the output format, and writes the results to a distribution directory.

By default, mkdist will clean the distDir before writing new files unless cleanDist: false is specified.

import { mkdist } from 'mkdist';

await mkdist({
  srcDir: 'src',
  distDir: 'dist',
  pattern: '**/*.ts'
});

The vueLoader is the primary entry point for processing .vue files. It attempts to use vue-sfc-transformer/mkdist for advanced transformations (like TypeScript support). If that package is not installed, it automatically falls back to fallbackVueLoader.

import { vueLoader } from 'mkdist/loaders/vue';

// Use vueLoader within your mkdist configuration
// It accepts (input: InputFile, context: LoaderContext)

The loaders object provides access to built-in loaders for specific file types. It includes js, sass, and postcss. The vue loader is loaded dynamically: it attempts to use vue-sfc-transformer/mkdist if available, otherwise it falls back to a default vueLoader.

Available loader names (LoaderName):

• js
• vue
• sass
• postcss

import { loaders } from 'mkdist/loaders';

// Access a specific loader
const jsLoader = loaders.js;
const vueLoader = await loaders.vue;
const sassLoader = loaders.sass;
const postcssLoader = loaders.postcss;