Theorem Bundler Plugins

0.3.2 · active · verified Tue Apr 21

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.

Common errors

```
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).
```
cause The `theoremVite` plugin was not correctly initialized or added to the Vite `plugins` array. It must be called as a function.

fix Ensure the plugin is called with `theoremVite()` (note the parentheses) when added to the `plugins` array in `vite.config.ts`.
```
ERR_MODULE_NOT_FOUND: Cannot find module 'theoremts-plugins/vite'
```
cause Attempting to `require` an ESM-only module in a CommonJS context, or incorrect import path.

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.
```
ESBUILD_PEER_DEPENDENCY_NOT_FOUND: The 'esbuild' peer dependency is required but not installed.
```
cause The `esbuild` package, a peer dependency for the `theoremts-plugins/esbuild` module, is missing from your project's `node_modules`.

fix Install `esbuild` as a development dependency: `npm install --save-dev esbuild` or `yarn add -D esbuild`.

Warnings

breaking 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.
Fix: Review the project's GitHub releases or changelog for specific migration steps before upgrading.
gotcha 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.
Fix: Ensure `theoremts` is installed and actively used for defining contracts in your codebase.
gotcha 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.
Fix: Check your installed versions of `vite` or `esbuild` against the `peerDependencies` listed in `theoremts-plugins`'s `package.json` and adjust as needed.

Install

npm install theoremts-plugins npm
yarn add theoremts-plugins yarn
pnpm add theoremts-plugins pnpm

Imports

theoremVite
wrong:
```
const theoremVite = require('theoremts-plugins/vite')
```
correct:
```
import { theoremVite } from 'theoremts-plugins/vite'
```
Vite configuration files are typically ESM, requiring `import` syntax. Attempting to `require` will result in a runtime error.
theoremEsbuild
wrong:
```
import { esbuildPlugin } from 'theoremts-plugins/esbuild'
```
correct:
```
import { theoremEsbuild } from 'theoremts-plugins/esbuild'
```
Ensure you import the specific named export `theoremEsbuild` for the esbuild plugin, not a generic name.
theoremTsup
wrong:
```
const tsupPlugin = require('theoremts-plugins/tsup')
```
correct:
```
import { theoremTsup } from 'theoremts-plugins/tsup'
```
While tsup configurations can sometimes be CommonJS, the plugin itself is provided as an ESM module and should be imported using `import`.

Quickstart

Illustrates how to integrate the `theoremVite` plugin into a Vite configuration file to strip Theorem contracts at build time.

import { defineConfig } from 'vite';
import { theoremVite } from 'theoremts-plugins/vite';

// This configuration demonstrates how to integrate the theoremVite plugin
// into a standard Vite project. The plugin will automatically detect
// and strip Theorem contracts from your code during the build process,
// ensuring that they do not incur any runtime overhead in production.
export default defineConfig({
  plugins: [
    // Initialize the theoremVite plugin. It's typically added early
    // in the plugin array to ensure contracts are stripped before other
    // transformations that might interfere.
    theoremVite(),
    // ... other Vite plugins can go here
  ],
  // You might also have other Vite configurations here,
  // such as build options, server settings, etc.
  build: {
    sourcemap: true, // Example build option: useful for debugging production issues
    minify: 'esbuild' // Example: using esbuild for minification
  },
});

view raw JSON →