Note

This documentation is under construction and the web3.js 1.0 stable version isn’t released. If your using a version v0.x.x of web3.js then please have a look at github.com/ethereum/wiki/wiki/JavaScript-API.

Getting Started

The web3.js library is a collection of modules which contain specific functionality for the Ethereum ecosystem.

  • The web3-eth is for the Ethereum blockchain and smart contracts
  • The web3-shh is for the whisper protocol to communicate p2p and broadcast
  • The web3-utils contains useful helper functions for DApp developers.

Adding web3.js

First you need to get web3.js into your project. This can be done using the following methods:

  • npm: npm install web3

After that you need to create a web3 instance and set a provider. A Ethereum compatible browser will have a window.ethereum or web3.currentProvider available. For web3.js, check Web3.givenProvider. If this property is null you should connect to your own local or remote node.

// in node.js use: const Web3 = require('web3');

// use the given Provider, e.g in the browser with Metamask, or instantiate a new websocket provider
const web3 = new Web3(Web3.givenProvider || 'ws://localhost:8546', null, {});

// or
const web3 = new Web3(Web3.givenProvider || new Web3.providers.WebsocketProvider('ws://localhost:8546'), null, {});

// Using the IPC provider in node.js
const net = require('net');

const web3 = new Web3('/Users/myuser/Library/Ethereum/geth.ipc', net, {}); // mac os path
// or
const web3 = new Web3(new Web3.providers.IpcProvider('/Users/myuser/Library/Ethereum/geth.ipc', net, {})); // mac os path
// on windows the path is: '\\\\.\\pipe\\geth.ipc'
// on linux the path is: '/users/myuser/.ethereum/geth.ipc'

That’s it! now you can use the web3 object.