{"id":15888,"library":"unplugin-typesugar","title":"Unplugin TypeSugar Bundler Integrations","description":"unplugin-typesugar provides essential bundler integrations for `typesugar`, a TypeScript macro expansion library. It enables compile-time macro processing across various build tools, including Vite, Webpack, esbuild, and Rollup. Leveraging the `unplugin` ecosystem, it ensures broad compatibility and simplifies integration into existing JavaScript and TypeScript projects. The current stable version is 0.1.1, marked as an initial release candidate and first stable patch, indicating active, early-stage development with frequent updates addressing stability and feature enhancements. A key differentiator is its ability to expand TypeScript macros before the code enters the bundler's optimization pipeline, ensuring that macro-transformed code is fully optimized. It requires TypeScript 5.0 or newer as a peer dependency, aligning with modern TypeScript tooling practices.","status":"active","version":"0.1.1","language":"javascript","source_language":"en","source_url":"https://github.com/typesugar/typesugar","tags":["javascript","typescript","macros","vite","webpack","esbuild","rollup","bundler","plugin"],"install":[{"cmd":"npm install unplugin-typesugar","lang":"bash","label":"npm"},{"cmd":"yarn add unplugin-typesugar","lang":"bash","label":"yarn"},{"cmd":"pnpm add unplugin-typesugar","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required peer dependency for TypeScript macro expansion and program creation.","package":"typescript","optional":false}],"imports":[{"note":"Use named import for Vite, Rollup, and esbuild. These are typically ESM-only.","wrong":"const typesugar = require(\"unplugin-typesugar/vite\");","symbol":"typesugar","correct":"import typesugar from \"unplugin-typesugar/vite\";"},{"note":"Webpack configuration files often run in CommonJS contexts and require accessing the .default export.","wrong":"import typesugar from \"unplugin-typesugar/webpack\";","symbol":"typesugar","correct":"const typesugar = require(\"unplugin-typesugar/webpack\").default;"},{"note":"Import types explicitly using 'import type' for clarity and tree-shaking benefits.","symbol":"TypesugarPluginOptions","correct":"import type { TypesugarPluginOptions } from 'unplugin-typesugar';"}],"quickstart":{"code":"import typesugar from \"unplugin-typesugar/vite\";\nimport { defineConfig } from 'vite';\n\nexport default defineConfig({\n  plugins: [\n    typesugar({\n      verbose: true,\n      include: /src\\/.*\\.tsx?$/,\n      exclude: /\\.test\\.ts$/,\n      diskCache: true, // Enable disk cache for faster rebuilds\n      strict: true // Typecheck expanded output at build end\n    }),\n  ],\n});","lang":"typescript","description":"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."},"warnings":[{"fix":"Review release notes carefully for any breaking changes when upgrading. Consider pinning to exact patch versions for critical applications.","message":"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.","severity":"gotcha","affected_versions":"<1.0.0"},{"fix":"Ensure your project's `typescript` peer dependency is satisfied by upgrading to `typescript@>=5.0.0` in your `package.json`.","message":"This plugin requires TypeScript version 5.0.0 or higher due to its reliance on newer TypeScript compiler APIs for macro transformation.","severity":"breaking","affected_versions":">=0.1.1"},{"fix":"Upgrade `unplugin-typesugar` to version 0.1.1 or newer to resolve this critical build issue.","message":"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.","severity":"breaking","affected_versions":"<0.1.1"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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';`).","cause":"The specific bundler integration path is incorrect, or the `unplugin-typesugar` package is not correctly installed.","error":"Plugin 'unplugin-typesugar' failed to load. Cannot find module 'unplugin-typesugar/vite' (or /webpack, /esbuild, /rollup)"},{"fix":"For Webpack, use `const typesugar = require('unplugin-typesugar/webpack').default;` to correctly import the plugin.","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.","error":"TypeError: Cannot read properties of undefined (reading 'default') in Webpack configuration"},{"fix":"Upgrade your project's `typescript` dependency to `typescript@>=5.0.0` to ensure compatibility with the plugin's internal TypeScript program creation.","cause":"The installed TypeScript version is incompatible with `unplugin-typesugar`, which requires TypeScript 5.0 or newer.","error":"Property 'getDiagnostics' does not exist on type 'Program' (or similar TypeScript API errors during build)"}],"ecosystem":"npm"}