.. and press ENTER to ask a question on web5, how to write code and more.

Skip to main content


This guide will walk you through the process of setting up the Web5 SDK in a Next.js project. You can integrate Web5 into an existing project or start a new one.

If the suggested steps here don't work, please open an issue or post your questions in the #web5 channel on TBD Discord.

Create your project

To start a new Next.js project, use the following commands in your terminal:

npx create-next-app@latest my-project
cd my-project

Install the Web5 SDK via NPM

npm install @web5/api

Add the Web5 import to your Next app

Then, add the plugin to your app:

import { Web5 } from "@web5/api";

Encountering Errors?

If you encounter errors related to node:crypto, follow the steps below to resolve them.


Example Error: Node:crypto not handled by plugin Module build failed: UnhandledSchemeError: Reading from "node:crypto" is not handled by plugins (Unhandled scheme). Webpack supports "data:" and "file:" URIs by default. You may need an additional plugin to handle "node:" URIs. Import trace for requested module: node:crypto ./node_modules/@web5/crypto/dist/esm/crypto-primitives/pbkdf2.js ./node_modules/@web5/crypto/dist/esm/crypto-primitives/index.js ./node_modules/@web5/crypto/dist/esm/index.js ./node_modules/@web5/agent/dist/esm/app-data-store.js ./node_modules/@web5/agent/dist/esm/index.js ./node_modules/@web5/api/dist/esm/did-api.js ./node_modules/@web5/api/dist/esm/index.js ./src/context/web5.tsx

This error occurs when browser polyfills for stream and crypto modules are missing in Webpack. Follow these steps to add the necessary polyfills and plugins to your Next.js configuration.

Install Required Modules

First, install stream-browserify, crypto-browserify, and process:

npm install stream-browserify crypto-browserify process

Update Next.js Webpack Configuration

Modify your next.config.js to include the necessary Webpack plugins:

const webpack = require('webpack');

/** @type {import('next').NextConfig} */
const nextConfig = {
reactStrictMode: true,

webpack: (config, { isServer }) => {
if (!isServer) {
config.resolve.fallback = {
stream: require.resolve('stream-browserify'),
crypto: require.resolve('crypto-browserify'),

new webpack.ProvidePlugin({
process: 'process/browser',
new webpack.NormalModuleReplacementPlugin(
(resource) => {
resource.request = resource.request.replace(/^node:/, '');
return config;

module.exports = nextConfig;

Error: No native build was found

If you encounter errors similar to the above structure, ensure your node version and web5.js versions are up to date. If it persists, you can change how you initialize Web5 to use useEffect():

 useEffect(() => {

const initWeb5 = async () => {
// @ts-ignore
const { Web5 } = await import('@web5/api/browser');

try {
const { web5, did } = await Web5.connect();
if (web5 && did) {
console.log('Web5 initialized');
} catch (error) {
console.error('Error initializing Web5:', error);


}, []);

If you run into any errors, check out our troubleshooting guide.

Connect with us on Discord

Submit feedback: Open a GitHub issue

Edit this page: GitHub Repo

Contribute: Contributing Guide