Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Bundler Troubleshooting

Common Issues

1. Missing or Red Underlines in Editor

Solidity imports show red underlines or no auto-completion.

  • Add "plugins": [{ "name": "@tevm/ts-plugin" }] to tsconfig.json.
  • In VS Code / Cursor, switch to the workspace TypeScript version: Command Palette → "TypeScript: Select TypeScript Version" → "Use Workspace Version".
  • For Vim/Neovim/other editors, ensure they use the workspace TS version.

2. Type-check Errors with Next.js

Build works but Next.js typechecking fails on .sol imports.

Option 1 - disable typechecking in next.config.mjs:

export default {
  typescript: {
    ignoreBuildErrors: true,
  },
}

Option 2 - use the Codegen Approach (recommended for Next.js).

3. "File Not Found" Errors

Bundler can't resolve imports.

  • Check libs and remappings.

  • For Foundry projects, set foundryProject: true in tevm.config.json.

  • For npm packages, verify install and import path.

  • Add explicit remappings:

    {
  "remappings": {
    "@customlib/": "node_modules/@customlib/",
    "local/": "./contracts/"
  }
}

4. Cache Stale Issues

Solidity changes don't take effect.

  • Delete .tevm/ and rebuild.
  • Add .tevm to .gitignore.

5. No Bytecode Available

Deployment fails with missing bytecode.

  • Use the .s.sol extension for deployable contracts. Regular .sol produces ABI only.

6. Deployment Errors

Even with bytecode, deployment fails.

  • Pass constructor args via .deploy(...):

    const deployed = await client.deployContract(MyToken.deploy('TokenName', 'TKN', 18))

7. Test Runner Issues

.sol imports fail in tests.

  • Most runners (Vitest) work once the plugin is configured.
  • Use the bundler matching your test environment (esbuild for Vitest, etc.).

Codegen Approach

npx tevm gen

Generates .ts files next to each .sol. Recommended when bundler hooks are impractical (e.g., Next.js with strict typechecking).

Additional Resources

Further Reading