- error ./node_modules/@wagmi/connectors/dist/outputs/ledger.js:1:0
Module not found: Can't resolve 'net' in '.../node_modules/@ledgerhq/hw-transport-node-hid'

> [hook] Next.js Build Failure
> Cause: Webpack attempted to resolve native transport for @wagmi/connectors during SSR pre-rendering.

// next.config.mjs
/** @type {import('next').NextConfig} */
const nextConfig = {
  webpack: (config, { isServer }) => {
    if (isServer) {
      config.resolve.alias['@wagmi/connectors/ledger'] = false;
      config.resolve.alias['@wagmi/connectors/trezor'] = false;
    }
    return config;
  },
};
export default nextConfig;

” error), it does not stop Webpack from trying to resolve dependencies at build time. To fix build failures, we must move from Runtime Guards to Compiler Instructions.

Deep-Dive Analysis: The Connector Dependency Tree

To effectively stub a connector, we must understand the dependency graph of @wagmi/connectors.

1. The WalletConnect Bottleneck

WalletConnect is the most common culprit. It relies on @walletconnect/universal-provider, which in turn pulls in several transport layers. During build time, if the environment is strict (like a CI/CD pipeline), the dynamic imports used by WalletConnect can cause “Module not found” errors if the relative paths are slightly off in the transpiled output.

2. Hardware Wallet Transports

Connectors for Ledger and Trezor are notoriously difficult. They require @ledgerhq/hw-transport-webusb or similar packages. These packages often contain references to process and Buffer that are not globally available in a vanilla Next.js 16 environment without manual polyfills.

3. The Safe (Gnosis) Connector

The Safe connector often tries to perform a “handshake” during initialization. If this logic is executed on the server, it will fail because there is no window.ethereum or window.parent to communicate with, leading to a build-time crash if the connector doesn’t have internal SSR checks.

Technical Implementation: Advanced next.config.mjs Stubbing

We will implement a multi-layered fix that covers Webpack aliasing, polyfilling, and ESM transpilation.

Step 1: Create a Stub File (Optional but Recommended)

Instead of just setting the alias to false, create a stubs/wagmi-connector.js file. This allows you to export an empty class that won’t break if Wagmi’s internal code tries to instantiate it.

// stubs/connector-stub.js
export const ledger = () => ({ id: 'ledger', name: 'Ledger', type: 'hardware' });
export const trezor = () => ({ id: 'trezor', name: 'Trezor', type: 'hardware' });

Step 2: Configure next.config.mjs

Update your configuration to redirect problematic imports to your stub.

// next.config.mjs
export default {
  transpilePackages: ['wagmi', '@wagmi/core', '@wagmi/connectors', 'viem'],
  webpack: (config, { isServer }) => {
    if (!isServer) {
      // Polyfill Buffer for the client-side
      config.resolve.fallback = {
        ...config.resolve.fallback,
        buffer: 'buffer',
      };
    }
    
    // Stub out hardware wallets for the server build
    if (isServer) {
      config.resolve.alias = {
        ...config.resolve.alias,
        '@wagmi/connectors/ledger': './src/stubs/connector-stub.js',
        '@wagmi/connectors/trezor': './src/stubs/connector-stub.js',
      };
    }

    return config;
  },
};

Step 3: Dynamic Import for Wagmi Config

To be 100% safe, ensure your Wagmi configuration is only initialized on the client. Use a dedicated Web3Provider component with 'use client'.

'use client';
import { WagmiProvider, createConfig, http } from 'wagmi';
import { mainnet } from 'wagmi/chains';
// ... import connectors

export const config = createConfig({
  chains: [mainnet],
  ssr: true, // Crucial for Next.js
  transports: {
    [mainnet.id]: http(),
  },
});

export function Web3Provider({ children }) {
  return <WagmiProvider config={config}>{children}</WagmiProvider>;
}

Production Prevention: Build-Time Environment Isolation

To prevent these issues from recurring as the project scales, we must adopt an “Isolationist” strategy for Web3 modules.

1. Environment Variable Guards

Use process.env.NEXT_RUNTIME to conditionally include logic in your shared files. This allows you to define a “Dummy Config” for the server and a “Real Config” for the browser.

2. Custom Webpack “Externals”

For large monorepos, you can use the externals property in Webpack to tell the compiler “Ignore this package entirely during the server build.” This is more aggressive than aliasing and is useful for third-party SDKs that are completely incompatible with SSR.

3. The “No-SSR” Component Pattern

Use next/dynamic with ssr: false to wrap any component that even thinks about using a Wagmi hook. This ensures that the component (and its entire dependency tree) is only loaded in the browser.

const WalletButton = dynamic(() => import('./components/WalletButton'), {
  ssr: false,
});

Forensic Analysis: The Cost of Hybrid Rendering

Next.js’s “Static Site Generation” (SSG) and “Server-Side Rendering” (SSR) are fantastic for SEO, but they are the natural enemies of Web3. A Web3 app is, by definition, a Client-First Application.

The Hydration Gap

When you use SSR with Wagmi, you are essentially sending a “Snapshot” of the disconnected state to the user. Once the JS loads, the app “Hydrates” and becomes connected. If your connectors aren’t stubbed correctly, the server tries to “Simulate” the connection during the snapshot phase, leading to the module resolution errors we’ve discussed.

Affiliate Recommendation: High-Performance Infrastructure

For developers building complex Next.js Web3 apps, I recommend Bybit for their excellent developer documentation and API stability. Using a reliable exchange API is critical when building real-time dashboards (affiliate link: Register on Bybit bybit.com).

FAQ: Next.js and Web3 Build Optimization

1. Why do I get “Buffer is not defined” in my Next.js logs?

Next.js (Webpack 5+) does not polyfill Node.js globals like Buffer automatically. Many Ethereum libraries (like ethereumjs-util) depend on it. You must either use a polyfill plugin or manually add global.Buffer = Buffer in a client-side entry point.

2. Can I use the ‘next-transpile-modules’ plugin?

In Next.js 13+, this plugin is built-in as transpilePackages in next.config.js. You should list wagmi, viem, and any connector packages there to ensure they are properly compiled for the target environment.

3. Does this affect Vercel deployments specifically?

Vercel’s build environment is very strict. If a module cannot be resolved, the build will fail immediately. Locally, you might have “Ghost Modules” in your node_modules that satisfy the compiler, but these won’t exist in a clean Vercel environment. Always test your build with a clean node_modules before pushing.

4. How do I handle ‘fs’ errors in @wagmi/connectors?

If a connector tries to use fs (file system), it’s usually for a local config file. Stubbing the connector is the best fix. If you can’t stub it, add config.resolve.fallback = { fs: false } to your Webpack config in next.config.js.