{"id":15858,"library":"theoremts-plugins","title":"Theorem Bundler Plugins","description":"The `theoremts-plugins` package provides essential build-time integration for projects utilizing the Theorem TypeScript contract system. Currently at version 0.3.2, this package offers plugins for popular bundlers like Vite, esbuild, and tsup, enabling the stripping of Theorem contracts during the build process. This crucial functionality ensures zero runtime overhead for contracts in production environments, making it a key differentiator for performance-sensitive applications using Theorem. As a pre-1.0 release, its development cadence is likely tied to the Theorem project itself, implying potential for breaking changes in minor versions without strict semver adherence. Its primary purpose is to optimize the deployment of Theorem-powered applications by removing development-time contract checks, offering a lean production bundle.","status":"active","version":"0.3.2","language":"javascript","source_language":"en","source_url":"https://github.com/theoremts/theorem","tags":["javascript"],"install":[{"cmd":"npm install theoremts-plugins","lang":"bash","label":"npm"},{"cmd":"yarn add theoremts-plugins","lang":"bash","label":"yarn"},{"cmd":"pnpm add theoremts-plugins","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for using the esbuild plugin, handles bundling and minification.","package":"esbuild","optional":false},{"reason":"Required for using the Vite plugin, integrates with Vite's build pipeline.","package":"vite","optional":false}],"imports":[{"note":"Vite configuration files are typically ESM, requiring `import` syntax. Attempting to `require` will result in a runtime error.","wrong":"const theoremVite = require('theoremts-plugins/vite')","symbol":"theoremVite","correct":"import { theoremVite } from 'theoremts-plugins/vite'"},{"note":"Ensure you import the specific named export `theoremEsbuild` for the esbuild plugin, not a generic name.","wrong":"import { esbuildPlugin } from 'theoremts-plugins/esbuild'","symbol":"theoremEsbuild","correct":"import { theoremEsbuild } from 'theoremts-plugins/esbuild'"},{"note":"While tsup configurations can sometimes be CommonJS, the plugin itself is provided as an ESM module and should be imported using `import`.","wrong":"const tsupPlugin = require('theoremts-plugins/tsup')","symbol":"theoremTsup","correct":"import { theoremTsup } from 'theoremts-plugins/tsup'"}],"quickstart":{"code":"import { defineConfig } from 'vite';\nimport { theoremVite } from 'theoremts-plugins/vite';\n\n// This configuration demonstrates how to integrate the theoremVite plugin\n// into a standard Vite project. The plugin will automatically detect\n// and strip Theorem contracts from your code during the build process,\n// ensuring that they do not incur any runtime overhead in production.\nexport default defineConfig({\n  plugins: [\n    // Initialize the theoremVite plugin. It's typically added early\n    // in the plugin array to ensure contracts are stripped before other\n    // transformations that might interfere.\n    theoremVite(),\n    // ... other Vite plugins can go here\n  ],\n  // You might also have other Vite configurations here,\n  // such as build options, server settings, etc.\n  build: {\n    sourcemap: true, // Example build option: useful for debugging production issues\n    minify: 'esbuild' // Example: using esbuild for minification\n  },\n});","lang":"typescript","description":"Illustrates how to integrate the `theoremVite` plugin into a Vite configuration file to strip Theorem contracts at build time."},"warnings":[{"fix":"Review the project's GitHub releases or changelog for specific migration steps before upgrading.","message":"As a pre-1.0 package (current version 0.3.2), `theoremts-plugins` may introduce breaking changes in minor versions. Always consult the changelog when upgrading, even for `0.x.y` releases.","severity":"breaking","affected_versions":">=0.1.0"},{"fix":"Ensure `theoremts` is installed and actively used for defining contracts in your codebase.","message":"This package is a companion to `theoremts`. It assumes you are already using `theoremts` in your project for contract definition. The plugins will not function correctly or provide value without `theoremts` contracts present.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Check your installed versions of `vite` or `esbuild` against the `peerDependencies` listed in `theoremts-plugins`'s `package.json` and adjust as needed.","message":"Incorrect peer dependency versions for bundlers (e.g., Vite, esbuild) can lead to unexpected build failures or plugin misbehavior. This package has strict peer dependency ranges.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Ensure the plugin is called with `theoremVite()` (note the parentheses) when added to the `plugins` array in `vite.config.ts`.","cause":"The `theoremVite` plugin was not correctly initialized or added to the Vite `plugins` array. It must be called as a function.","error":"Error: Plugin \"theoremVite\" is not a valid Rollup plugin. Plugins must be an object with a 'name' property and a 'buildStart' or 'load' method (or other Rollup plugin hooks)."},{"fix":"Ensure your configuration file uses ESM `import` syntax (e.g., `import { theoremVite } from 'theoremts-plugins/vite'`) and that your project is configured for ESM where appropriate (e.g., `\"type\": \"module\"` in `package.json`). Double-check the path for typos.","cause":"Attempting to `require` an ESM-only module in a CommonJS context, or incorrect import path.","error":"ERR_MODULE_NOT_FOUND: Cannot find module 'theoremts-plugins/vite'"},{"fix":"Install `esbuild` as a development dependency: `npm install --save-dev esbuild` or `yarn add -D esbuild`.","cause":"The `esbuild` package, a peer dependency for the `theoremts-plugins/esbuild` module, is missing from your project's `node_modules`.","error":"ESBUILD_PEER_DEPENDENCY_NOT_FOUND: The 'esbuild' peer dependency is required but not installed."}],"ecosystem":"npm"}