Skip to main content
Version: 1.1.1

Browser Setup

The CCIP SDK works in browser environments with proper bundler configuration. What you need depends on which chains you use and which bundler you have.

What You Need​

The SDK itself requires only the buffer polyfill — and only when using Solana, TON, or Sui chains. Wallet libraries (MetaMask SDK, WalletConnect, RainbowKit) may require additional polyfills.

PolyfillWhen required
bufferSolana, TON, or Sui chains (not needed for EVM-only or Aptos-only)
cryptoMetaMask SDK, some wallet libraries
streamMetaMask SDK
processMetaMask SDK, WalletConnect
utilSolana Wallet Adapter

Additionally, Webpack and Next.js need a resolve.alias for @noble/hashes to fix a version conflict between SDK dependencies. The ethers dependency tree includes an older @noble/hashes version that lacks sub-paths (./blake2.js, ./sha2.js) required by @mysten/sui. Without the alias, you'll get ERR_PACKAGE_PATH_NOT_EXPORTED. Add version overrides to your package.json:

JSON
{
  "overrides": {
    "@noble/hashes": "^1.8.0"
  }
}

This is safe — @noble/[email protected] is backward-compatible with ethers' needs. Vite does not need this fix.

Vite​

Install the polyfill plugin:

Bash
npm install vite-plugin-node-polyfills
note

Vite always needs the buffer polyfill, even for EVM-only projects. Vite's dev server pre-bundles all SDK dependencies eagerly (including Solana/TON code), so the polyfill must be resolvable. Production builds tree-shake correctly.

TypeScript
// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { nodePolyfills } from 'vite-plugin-node-polyfills'

export default defineConfig({
  plugins: [
    react(),
    nodePolyfills({
      include: ['buffer'],
      globals: { Buffer: true },
    }),
  ],
})

Webpack​

EVM-only consumers do not need the buffer polyfill on Webpack — non-EVM code is tree-shaken in production and never executed in development.

All Webpack configs need the @noble/hashes alias (see above).

JavaScript
// webpack.config.js
const path = require('path')

module.exports = {
  resolve: {
    alias: {
      '@noble/hashes': path.dirname(require.resolve('@noble/hashes')),
    },
  },
}

Next.js​

Requires Next.js >= 13.4.5 (supports moduleResolution: "bundler"). For older versions, see the legacy workaround below.

Like Webpack, EVM-only consumers do not need the buffer polyfill. All configs need the @noble/hashes alias.

JavaScript
// next.config.js
const path = require('path')

/** @type {import('next').NextConfig} */
const nextConfig = {
  webpack: (config, { isServer }) => {
    if (!isServer) {
      config.resolve.alias = {
        ...config.resolve.alias,
        '@noble/hashes': path.dirname(require.resolve('@noble/hashes')),
      }
    }
    return config
  },
}

module.exports = nextConfig

Next.js 12 – 13.4.4​

These versions force moduleResolution: "node", which cannot resolve the SDK's type declarations. Add paths to your tsconfig.json:

JSON
{
  "compilerOptions": {
    "paths": {
      "@chainlink/ccip-sdk": [
        "./node_modules/@chainlink/ccip-sdk/src/index.ts"
      ],
      "@chainlink/ccip-sdk/viem": [
        "./node_modules/@chainlink/ccip-sdk/src/viem.ts"
      ]
    }
  }
}

Remix​

Remix uses esbuild. Add the buffer shim to your client entry:

Bash
npm install buffer
TypeScript
// app/entry.client.tsx
import { Buffer } from 'buffer'
globalThis.Buffer = Buffer

// ... rest of entry.client.tsx

Tree-Shaking​

The SDK supports tree-shaking — only the chains you import are bundled:

TypeScript
// Only EVMChain code is bundled
import { EVMChain } from '@chainlink/ccip-sdk'

// All chains — largest bundle, use only if needed
import { allSupportedChains } from '@chainlink/ccip-sdk/all'
ImportMinifiedGzipped
EVM only740 KB~180 KB
Solana only1.2 MB~290 KB
Aptos only700 KB~170 KB
Sui only756 KB~185 KB
TON only760 KB~185 KB
EVM + Solana1.4 MB~340 KB
All chains2.0 MB~480 KB

Don't place @chainlink/ccip-sdk in manualChunks — this disables tree-shaking:

TypeScript
// vite.config.ts
export default defineConfig({
  build: {
    rollupOptions: {
      output: {
        manualChunks: {
          'vendor-react': ['react', 'react-dom'],
          // DON'T add @chainlink/ccip-sdk here
        },
      },
    },
  },
})

To verify tree-shaking is working, check your bundle size:

Bash
# Vite
npx vite-bundle-visualizer

# Webpack
npx webpack-bundle-analyzer dist/stats.json

EVM-only bundles should be ~740 KB minified. If you see >1 MB, tree-shaking may not be working — verify you're using ES module imports (not require()) and not importing allSupportedChains.

Troubleshooting​

"ERR_PACKAGE_PATH_NOT_EXPORTED"​

The ethers dependency tree includes an older @noble/hashes that conflicts with other SDK dependencies requiring v1.8.0+. Add the package.json overrides and resolve.alias shown in What You Need and your bundler section above.

"Buffer is not defined"​

Using Solana, TON, or Sui chains without the Buffer polyfill, or the polyfill isn't loading before SDK code. Follow the configuration for your bundler above.

"process is not defined"​

Wallet libraries (MetaMask SDK, WalletConnect) require process. Use the "With Wallet Libraries" tab in your bundler section above.

Bundle size larger than expected​

Verify you're importing specific chains (EVMChain), not allSupportedChains. Run a bundle analyzer (see Tree-Shaking). On Webpack/Next.js, the @noble/hashes alias fix must be applied before tree-shaking can work.

Vite dev server errors with EVM-only code​

Vite pre-bundles all SDK dependencies in dev mode, including Solana/TON libraries that need Buffer. Add the Buffer polyfill even for EVM-only development — production builds tree-shake correctly.

"Cannot find module 'buffer'"​

Install it: npm install buffer