Unplugin TypeSugar Bundler Integrations

Common errors

• Plugin 'unplugin-typesugar' failed to load. Cannot find module 'unplugin-typesugar/vite' (or /webpack, /esbuild, /rollup)

  cause The specific bundler integration path is incorrect, or the `unplugin-typesugar` package is not correctly installed.
  fix Verify that `unplugin-typesugar` is installed (`npm install unplugin-typesugar` or `pnpm add unplugin-typesugar`) and that the import path matches your bundler (e.g., `import typesugar from 'unplugin-typesugar/vite';`).

• TypeError: Cannot read properties of undefined (reading 'default') in Webpack configuration

  cause Attempting to use an ESM import statement (`import typesugar from '...'`) or incorrectly accessing the CommonJS module's export in a Webpack configuration file, which typically runs in a CommonJS environment.
  fix For Webpack, use `const typesugar = require('unplugin-typesugar/webpack').default;` to correctly import the plugin.

• Property 'getDiagnostics' does not exist on type 'Program' (or similar TypeScript API errors during build)

  cause The installed TypeScript version is incompatible with `unplugin-typesugar`, which requires TypeScript 5.0 or newer.
  fix Upgrade your project's `typescript` dependency to `typescript@>=5.0.0` to ensure compatibility with the plugin's internal TypeScript program creation.

Warnings

• gotcha unplugin-typesugar is in its early development stages (current version 0.1.1). APIs may undergo rapid changes in minor or patch releases prior to reaching a stable 1.0 version.
  Fix: Review release notes carefully for any breaking changes when upgrading. Consider pinning to exact patch versions for critical applications.
• breaking This plugin requires TypeScript version 5.0.0 or higher due to its reliance on newer TypeScript compiler APIs for macro transformation.
  Fix: Ensure your project's `typescript` peer dependency is satisfied by upgrading to `typescript@>=5.0.0` in your `package.json`.
• breaking Initial release candidates (prior to 0.1.1) experienced a build crash with a 'start < 0' error. This was resolved in version 0.1.1.
  Fix: Upgrade `unplugin-typesugar` to version 0.1.1 or newer to resolve this critical build issue.

Install

• npm install unplugin-typesugar npm
• yarn add unplugin-typesugar yarn
• pnpm add unplugin-typesugar pnpm

Imports

• typesugar
  wrong:

  const typesugar = require("unplugin-typesugar/vite");

  correct:

  import typesugar from "unplugin-typesugar/vite";

  Use named import for Vite, Rollup, and esbuild. These are typically ESM-only.
• typesugar
  wrong:

  import typesugar from "unplugin-typesugar/webpack";

  correct:

  const typesugar = require("unplugin-typesugar/webpack").default;

  Webpack configuration files often run in CommonJS contexts and require accessing the .default export.
• TypesugarPluginOptions

  import type { TypesugarPluginOptions } from 'unplugin-typesugar';

  Import types explicitly using 'import type' for clarity and tree-shaking benefits.

Quickstart

Demonstrates how to integrate unplugin-typesugar into a Vite project with common configuration options, including verbose logging, file pattern matching, disk caching, and strict type-checking of expanded output.

import typesugar from "unplugin-typesugar/vite";
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [
    typesugar({
      verbose: true,
      include: /src\/.*\.tsx?$/,
      exclude: /\.test\.ts$/,
      diskCache: true, // Enable disk cache for faster rebuilds
      strict: true // Typecheck expanded output at build end
    }),
  ],
});