Bundler Plugins

Tevm bundler plugins enable direct Solidity imports in TypeScript/JavaScript, compiling them into type-safe Tevm Contract instances at build time.

Available Plugins

Bundler	Plugin Import Path	Repository
Vite	`tevm/bundler/vite-plugin`	@tevm/vite-plugin
Webpack	`tevm/bundler/webpack-plugin`	@tevm/webpack-plugin
Rollup	`tevm/bundler/rollup-plugin`	@tevm/rollup-plugin
ESBuild	`tevm/bundler/esbuild-plugin`	@tevm/esbuild-plugin
Bun	`tevm/bundler/bun-plugin`	@tevm/bun-plugin
Rspack	`tevm/bundler/rspack-plugin`	@tevm/rspack-plugin

All plugins share a configuration interface.

Prerequisites & Key Points

Optional: npx tevm gen works without any bundler integration.
TypeScript: Add @tevm/ts-plugin to tsconfig.json for editor support (NatSpec hovers, go-to-definition).
.s.sol for bytecode: regular .sol produces ABI only; .s.sol includes deployable bytecode.
Cache: artifacts go in .tevm/ — add it to .gitignore.
Foundry/remappings: configure in tevm.config.json.
Next.js: type-checker conflicts; use codegen or disable next.config typechecks.

Plugin Configuration

type PluginOptions = {
  solc?: '0.8.19' | '0.8.20' | /* other supported solc versions */
}

Global settings (Foundry, libs, remappings) live in tevm.config.json.

Bundler-Specific Setup

vite.config.ts

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { vitePluginTevm } from 'tevm/bundler/vite-plugin'
 
export default defineConfig({
  plugins: [react(), vitePluginTevm({ solc: '0.8.20' })],
})

For Bun, register the plugin in bunfig.toml:

preload = ["./plugins.ts"]
 
[test]
preload = ["./plugins.ts"]

TypeScript Plugin

{
  "compilerOptions": {
    "plugins": [{ "name": "@tevm/ts-plugin" }]
  }
}

In VSCode, switch to the workspace TypeScript version.

How the Bundler Works

All Tevm bundler plugins share a unified core (@tevm/base-bundler):

Import detection & resolution: scans .sol imports, merges tsconfig paths, foundry remappings, and tevm.config.json.
Compilation: runs solc on the dependency graph; .s.sol includes bytecode, .sol is ABI-only.
Code generation: emits a TS module exporting a Tevm Contract (with .read, .write, abi, optional bytecode).
Caching: stores results in .tevm/.
LSP: @tevm/ts-plugin references bundler outputs for IDE features.

Configuration with tevm.config.json

{
  "foundryProject": true,
  "libs": ["./lib", "./node_modules"],
  "remappings": {
    "foo": "vendored/foo"
  },
  "debug": false,
  "cacheDir": ".tevm",
  "jsonAsConst": ["**/*.abi.json"]
}

Option	Type	Description
`foundryProject`	`boolean \| string`	Enable Foundry (`true`) or path to `foundry.toml`
`libs`	`string[]`	Library paths for Solidity imports
`remappings`	`Record<string, string>`	Custom import remappings
`debug`	`boolean`	Extra debug logs and files in `.tevm`
`cacheDir`	`string`	Artifact location (default: `.tevm`)
`jsonAsConst`	`string \| string[]`	Glob patterns for `as const` JSON imports

Codegen Approach

npx tevm gen

Generates .ts files next to each .sol. Use this when a bundler hook is impractical (e.g., Next.js with strict typechecking).

Troubleshooting

Red underlines on .sol imports: ensure @tevm/ts-plugin is in tsconfig and you're using the workspace TS version.
Next.js type errors: disable typechecking or use codegen.
File not found: check libs/remappings; set foundryProject: true for Foundry projects.
Stale cache: delete .tevm/.