ethereum
web3.js - Ethereum JavaScript API
Web3.js 4.x has been released. Checkout 4.x API documentation and migration guide for testing, early feedback and contributions.
This is the Ethereum JavaScript API which connects to the Generic JSON-RPC spec.
You need to run a local or remote Ethereum node to use this library.
Please read the documentation for more.
Installation
You can install the package either using NPM or using Yarn
Using NPM
npm install web3Yarn
yarn add web3In the Browser
Use the prebuilt dist/web3.min.js, or
build using the web3.js repository:
npm run buildThen include dist/web3.min.js in your html file.
This will expose Web3 on the window object.
Or via jsDelivr CDN:
<script src="https://cdn.jsdelivr.net/npm/web3@latest/dist/web3.min.js"></script>UNPKG:
<script src="https://unpkg.com/web3@latest/dist/web3.min.js"></script>Usage
// In Node.js
const Web3 = require('web3');
const web3 = new Web3('ws://localhost:8546');
console.log(web3);
// Output
{
eth: ... ,
shh: ... ,
utils: ...,
...
}Additionally you can set a provider using web3.setProvider() (e.g. WebsocketProvider):
web3.setProvider('ws://localhost:8546');
// or
web3.setProvider(new Web3.providers.WebsocketProvider('ws://localhost:8546'));There you go, now you can use it:
web3.eth.getAccounts().then(console.log);Usage with TypeScript
We support types within the repo itself. Please open an issue here if you find any wrong types.
You can use web3.js as follows:
import Web3 from 'web3';
import { BlockHeader, Block } from 'web3-eth' // ex. package types
const web3 = new Web3('ws://localhost:8546');If you are using the types in a commonjs module, like in a Node app, you just have to enable esModuleInterop and allowSyntheticDefaultImports in your tsconfig for typesystem compatibility:
"compilerOptions": {
"allowSyntheticDefaultImports": true,
"esModuleInterop": true,
....Troubleshooting and known issues.
Web3 and Create-react-app
1.8 UPDATE: If you are facing any issues with create-react-app or angular, make sure you are using a web3 version of 1.8.0 or greater, as its been fixed
If you are using create-react-app version >=5 you may run into issues building. This is because NodeJS polyfills are not included in the latest version of create-react-app.
Solution
- Install react-app-rewired and the missing modules
If you are using yarn:
yarn add --dev react-app-rewired process crypto-browserify stream-browserify assert stream-http https-browserify os-browserify url bufferIf you are using npm:
npm install --save-dev react-app-rewired crypto-browserify stream-browserify assert stream-http https-browserify os-browserify url buffer process- Create
config-overrides.jsin the root of your project folder with the content:
const webpack = require('webpack');
module.exports = function override(config) {
const fallback = config.resolve.fallback || {};
Object.assign(fallback, {
"crypto": require.resolve("crypto-browserify"),
"stream": require.resolve("stream-browserify"),
"assert": require.resolve("assert"),
"http": require.resolve("stream-http"),
"https": require.resolve("https-browserify"),
"os": require.resolve("os-browserify"),
"url": require.resolve("url")
})
config.resolve.fallback = fallback;
config.plugins = (config.plugins || []).concat([
new webpack.ProvidePlugin({
process: 'process/browser',
Buffer: ['buffer', 'Buffer']
})
])
return config;
}- Within
package.jsonchange the scripts field for start, build and test. Instead ofreact-scriptsreplace it withreact-app-rewired
before:
"scripts": {
"start": "react-scripts start",
"build": "react-scripts build",
"test": "react-scripts test",
"eject": "react-scripts eject"
},after:
"scripts": {
"start": "react-app-rewired start",
"build": "react-app-rewired build",
"test": "react-app-rewired test",
"eject": "react-scripts eject"
},The missing Nodejs polyfills should be included now and your app should be functional with web3.
- If you want to hide the warnings created by the console:
In config-overrides.js within the override function, add:
config.ignoreWarnings = [/Failed to parse source map/];Web3 and Angular
New solution
If you are using Angular version >11 and run into an issue building, the old solution below will not work. This is because polyfills are not included in the newest version of Angular.
- Install the required dependencies within your angular project:
npm install --save-dev crypto-browserify stream-browserify assert stream-http https-browserify os-browserify- Within
tsconfig.jsonadd the followingpathsincompilerOptionsso Webpack can get the correct dependencies
{
"compilerOptions": {
"paths" : {
"crypto": ["./node_modules/crypto-browserify"],
"stream": ["./node_modules/stream-browserify"],
"assert": ["./node_modules/assert"],
"http": ["./node_modules/stream-http"],
"https": ["./node_modules/https-browserify"],
"os": ["./node_modules/os-browserify"],
}
}- Add the following lines to
polyfills.tsfile:
import { Buffer } from 'buffer';
(window as any).global = window;
global.Buffer = Buffer;
global.process = {
env: { DEBUG: undefined },
version: '',
nextTick: require('next-tick')
} as any;Old solution
If you are using Ionic/Angular at a version >5 you may run into a build error in which modules crypto and stream are undefined
a workaround for this is to go into your node-modules and at /angular-cli-files/models/webpack-configs/browser.js change the node: false to node: {crypto: true, stream: true} as mentioned here
Another variation of this problem was an issue opned on angular-cli
Documentation
Documentation can be found at ReadTheDocs.
Building
Requirements
sudo apt-get update
sudo apt-get install nodejs
sudo apt-get install npmBuilding (webpack)
Build the web3.js package:
npm run buildTesting (mocha)
npm testContributing
Please follow the Contribution Guidelines and Review Guidelines.
This project adheres to the Release Guidelines.
Community
Similar libraries in other languages
- Haskell: hs-web3
- Java: web3j
- PHP: web3.php
- Purescript: purescript-web3
- Python: Web3.py
- Ruby: ethereum.rb
- Scala: web3j-scala
Semantic versioning
This project follows semver as closely as possible from version 1.3.0 onwards. Earlier minor version bumps might have included breaking behavior changes.