# web3-webpacked

> Drop-in web3 solution for single-page Ethereum dApps

Latest version **1.0.11** (published 2018-08-22) · GPL-3.0-or-later license · 0 weekly downloads

> **Deprecated.** This package is deprecated.

## Install

```sh
npm install web3-webpacked
pnpm add web3-webpacked
yarn add web3-webpacked
bun add web3-webpacked
```

## Health

**Score 10/100 (F)** — status: deprecated.

Negative: deprecated.

## Facts

| | |
|---|---|
| Version | 1.0.11 |
| Published | 2018-08-22 |
| First published | 2018-08-03 |
| Weekly downloads | 0 |
| License | GPL-3.0-or-later |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 3 |
| Unpacked size | 81 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 38 |
| Author | Noah Zinsmeister |
| Maintainers | noahwz |
| Keywords | ethereum, solidity, javascript, web3, frontend, webpack, dapp |

## Links

- npm: https://www.npmjs.com/package/web3-webpacked
- Repository: https://github.com/NoahHydro/web3-webpacked
- Homepage: https://github.com/NoahHydro/web3-webpacked#readme
- Issues: https://github.com/NoahHydro/web3-webpacked/issues
- npm.io page: https://npm.io/package/web3-webpacked

## Dependencies (3)

- [web3](https://npm.io/package/web3.md) ^1.0.0-beta.35
- [eth-sig-util](https://npm.io/package/eth-sig-util.md) ^1.4.2
- [ethereumjs-util](https://npm.io/package/ethereumjs-util.md) ^5.2.0

## Alternatives

- [@sindresorhus/slugify](https://npm.io/package/@sindresorhus/slugify.md) — 3.7M weekly downloads
- [solid-js](https://npm.io/package/solid-js.md) — 2.7M weekly downloads
- [expo-glass-effect](https://npm.io/package/expo-glass-effect.md) — 2.5M weekly downloads
- [nanoassert](https://npm.io/package/nanoassert.md) — 780.8K weekly downloads
- [@ffmpeg/ffmpeg](https://npm.io/package/@ffmpeg/ffmpeg.md) — 529.5K weekly downloads

## Recent versions

- 1.0.11 (latest) — 2018-08-22
- 1.0.10 — 2018-08-22
- 1.0.9 — 2018-08-15
- 1.0.7 — 2018-08-13
- 1.0.6 — 2018-08-09
- 1.0.5 — 2018-08-08
- 1.0.4 — 2018-08-08
- 1.0.2 — 2018-08-07
- 1.0.1 — 2018-08-03
- 1.0.0 — 2018-08-03

## README

# Web3: Webpacked

![Example GIF](./_assets/example.gif)

This project is a drop-in solution for single-page Ethereum dApps. It's a [webpacked](https://webpack.js.org/) library consisting of:

- A robust management framework for the global `web3` object injected into browsers by [MetaMask](https://metamask.io/), [Trust](https://trustwalletapp.com/), etc. The framework exposes an instantiated [web3.js](https://web3js.readthedocs.io/en/1.0/) instance, keeps variables such as the current network and default account up-to-date, and fires customizable handlers when key events occur.

- Generic utility functions that fetch Ether and ERC20 balances, sign data, format [Etherscan](https://etherscan.io/) links, expose npm packages, etc.

- A fully managed solution for sending transactions that abstracts away from common annoyances like estimating gas usage and fetching current gas prices.

Building your dApp in React? Check out [`web3-webpacked-react`](https://github.com/NoahHydro/web3-webpacked-react).

## Example Projects
Projects using `web-webpacked` include:
- [Snowflake Dashboard](https://github.com/NoahHydro/snowflake-dashboard)

Open a PR to add your project to this list!

## Installation

### Script Tag

Include the [minified bundle](./dist/web3Webpacked.min.js) (820 KiB) in your source code:

```html
<script src="js/web3Webpacked.min.js"></script>
```

This binds the library to the `window` as `w3w`.

### NPM
If you'd like to roll your own webpack solution, you can use the npm package:

```
npm install web3-webpacked
```

```javascript
const w3w = require('web3-webpacked')
```

In either case, to initialize the package:

```javascript
window.addEventListener('load', () => {
  console.log('Initializing web3 upon page load.')
  w3w.initializeWeb3(config)
})
```

If you don't need `web3` functionality immediately on page load, you can initialize the package later:

```javascript
if (document.readyState === 'complete') {
  console.log('Initializing web3 after page load.')
  w3w.initializeWeb3(config)
}
```

See [Config Options](#config-options) for more instructions on what to include in the optional `config` variable, or [Usage](#usage) to jump right in.

## Config Options
The following options can be set in the `config` variable passed to `initializeWeb3`.

### `handler`
- `Object` Up to five handlers triggered on various events.
  - `noWeb3Handler: function()` Triggered when no injected `window.web3` instance was found. This means that the user's browser does not have web3 support. Will also be triggered if your code calls `initializeWeb3` before web3 injection occurred (in which case you should re-read the [Installation](#installation) instructions).
  - `web3Ready: function()` Triggered when the `web3js` instance is available to be fetched with `getWeb3js`, and the current network/accounts can be fetched with the their respective getters.
  - `web3ErrorHandler: function([error])` Triggered when there was an error communicating with the Ethereum blockchain.
  - `web3NetworkChangeHandler: function([networkId, oldNetworkId])` Triggered on network changes.
  - `web3AccountChangeHandler: function([account, oldAccount])` Triggered on default account changes.

### `pollTime`
- `Number` The poll interval (in milliseconds). The current recommendation is to poll for [account](https://github.com/MetaMask/faq/blob/master/DEVELOPERS.md) and [network](https://medium.com/metamask/breaking-change-no-longer-reloading-pages-on-network-change-4a3e1fd2f5e7) changes.

### `supportedNetworks`
- `Array` of `Numbers` Enforces that the injected `web3` instance is connected to a particular network. If the detected network id is not in the passed list, `web3ErrorHandler` will be triggered with an `UnsupportedEthereumNetworkError` error, and `web3` functionality will be removed. Supported network ids are: `1`, `3`, `4`, and `42`.

### Default Values
The default `config` values are below. You are encouraged to customize these!

```javascript
let config = {
  handlers: {
    // Prompt the user to e.g. install MetaMask or download Trust
    noWeb3Handler: () => {
      console.error('No web3 instance detected.')
    },
    // Check blockchain-dependent data
    web3Ready: () => {
      console.log('web3 initialized.')
    },
    // Notify the user of error, deal with unsupported networks
    web3ErrorHandler: (error) => {
      if (error.name === networkErrorName) {
        console.error(error.message)
      } else {
        console.error(`web3 Error: ${error}`)
      }
    },
    // Notify the user that they have switched networks, potentially re-instatiate smart contracts
    web3NetworkChangeHandler: (networkId, oldNetworkId) => {
      console.log(`Network switched from ${oldNetworkId} to ${networkId}.`)
    },
    // Notify the user that they have switched accounts, update balances
    web3AccountChangeHandler: (account, oldAccount) => {
      if (account === null) {
        console.log('No account detected, a password unlock is likely required.')
      } else {
        console.log(`Primary account switched from ${oldAccount} to ${account}.`)
      }
    }
  },
  pollTime: 1000, // 1 second
  supportedNetworks: [1, 3, 4, 42] // mainnet, ropsten, rinkeby, kovan
}
```

## Usage
- `w3w.initializeWeb3([config])`: Initialize web3 in your project. See above for more details.
- `w3w.getWeb3js()`: Returns a [web3js](https://web3js.readthedocs.io/en/1.0/) instance (web3@1.0.0-beta.34).
- `w3w.getAccount()`: Returns the current default account.
- `w3w.getNetworkId()`: Returns the current network id as a `Number`. Possible values: `1`, `3`, `4`, or `42`.
- `w3w.getNetworkName([networkId])`: Returns the name of a network (defaults to the current network). Possible values: `Mainnet`, `Ropsten`, `Rinkeby`, or `Kovan`.
- `w3w.getNetworkType([networkId])`: Returns the type of a network (defaults to the current network). Possible values: `PoW` or `PoA`.
- `w3w.getContract(ABI[, address, options])`: Returns a web3js Contract object.
- `w3w.getBalance([account, format])`: Returns the balance of an Ethereum address (defaults to the current account).
- `w3w.getERC20Balance([ERC20Address, account])`: Returns the token balance of an Ethereum address (defaults to the personal account) for any ERC20. Decimals are read from the smart contract.
- `w3w.toDecimal(number, decimals)`: number must be a `String`. Returns a decimalized version of the number as a `String`. Helpful when converting e.g. token balances from their `uint256` state in an Ethereum smart contract to actual balances.
- `w3w.fromDecimal(number, decimals)`: number must be a `String`. The opposite of `w3w.toDecimal`. Converts the number to an expanded form.
- `w3w.sendTransaction(method, handlers)`: An all-in-one function that manages the entire transaction sending flow. Ensures that function call won't fail given the current state of the network, that the sender has enough ether to cover the gas costs of the transaction, and calls `handlers` appropriately. `handlers` is an `Object` that must include an `error` handler, as well as optional `transactionHash`, `receipt`, and `confirmation` handlers. These correspond to [emitted web3js events](https://web3js.readthedocs.io/en/1.0/web3-eth.html#eth-sendtransaction-return).
- `w3w.signPersonal(message)`: Signs a message with the current default account per [this article](https://medium.com/metamask/the-new-secure-way-to-sign-data-in-your-browser-6af9dd2a1527). Returns the signing address, message hash, and signature. The returned signature is guaranteed to have originated from the returned address.
- `w3w.signTypedData(typedData)`: Signs typed data with the current default account per [this article](https://medium.com/metamask/scaling-web3-with-signtypeddata-91d6efc8b290). Returns the signing address, message hash, and signature. The returned signature is guaranteed to have originated from the returned address.
- `w3w.etherscanFormat(type, data[, networkId])`: Returns an [Etherscan](https://etherscan.io/) link to a given `transaction`, `address`, or `token` (defaults to the current network).
- `w3w.networkErrorName`: The name of the error thrown when the injected web3 instance is on an unsupported network.
- `w3w.libraries.`
  - `eth-sig-util`: Exposes the [eth-sig-util](https://github.com/MetaMask/eth-sig-util) package.
  - `ethereumjs-util`: Exposes the [ethereumjs-util](https://github.com/ethereumjs/ethereumjs-util) package.


## Notes
- To ensure that your code is accessing the most up-to-date variables, be sure not to hard code values like the `web3js` instance, the default `account`, the current `networkId`, etc. Instead, call functions like `w3w.getWeb3js()` on demand, whenever you need a `web3js` instance.

- `web3-webpacked` is forced to be opinionated, and has integrated web3js in lieu of possible alternatives like [ethjs](https://github.com/ethjs/ethjs). In the future, it's possible that two branches will be maintained, with web3js and ethjs compatibility respectively. There is also an argument to be made for letting users build `web3-webpacked` themselves with arbitrary versions of these web3 APIs (how exactly this would look is TBD). If any of this is of interest, please submit an issue with your ideas/comments.

---
_Source: https://npm.io/package/web3-webpacked · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._