Skip to content
Alethio's Light Weight Open Source Ethereum Explorer
TypeScript JavaScript HTML Other
Branch: master
Clone or download
Pull request Compare This branch is 94 commits behind Alethio:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

Ethereum Lite Explorer by Alethio

The Lite Explorer is a client-side only web application that connects directly to a Ethereum JSON RPC compatible node. This means you can have your own private Ethereum Explorer should you wish so. No need for servers, hosting or trusting any third parties to display chain data.

CircleCI Docker

WARNING v1.x.x is a breaking update from previous v0.x.x releases

NOTICE This is a big piece of work in progress. Please report any bugs using Github's issues


Short Term Roadmap

  • Post 1.0
    • Plugins System

Technical Details

The project is built using React, TypeScript and the Ethstats UI Components.

Project structure

├─📁dev             - dev server for serving the app and mocking block-explorer-api responses
├─📁dist            - target folder for application that contains deployables
└─📁src             - source files
  ├─📁app (*1)      - application source code
  ├─📁assets        - static assets (e.g. images) that will be bundled together with the application
  └─📁public        - contains static assets that are copied to the dist folder as they are

├─📁components      - application-level components to be reused across all pages (render layer)
├─📁data            - data layer (data structures, parsing server responses, caching, transformations, state mgmt)
├─📁helpers         - application-specific helpers/utils that couldn't be categorized differently 😄
├─📁page            - components for each page/view of the application
│ └─📁<pageName>
├─📁translation     - localized strings
├─📁util            - application-agnostic utilities. Ideally these would be in a separate repo/package.
└─📄index.ts         - entry point

Managing SVG icons

Original SVG sources should be kept in the src/assets/original-svg folder. To create SVG icon components from them, the following steps should be taken:

  1. Copy the SVG markup in the render method of a new React component
  2. Replace all dash (-) attributes with camelCase
  3. Remove any unneeded attributes or run the SVG through an optimizer tool
  4. The viewBox of the icon should be a square. If needed use <g transform="translate(x,y)"> to center the icon in the new viewBox. This allows proper sizing via size prop
  5. Replace the main fill/stroke color with currentColor, to ensure proper cascading, or parametrize if more than one color
  6. The resulting component should be configured with a size prop that applies to both width and height

Getting started

Known Issues Currently nodes behind HTTP basic auth do not work.


Please make sure you have the following installed and running properly


You can set any of the following variables either in, config.json or as environment variables for the Docker image to change the behavior of the explorer.

ENV var Description
APP_NODE_URL URL of RPC enabled node.
APP_NODE_URL_USER If your RPC node is behind HTTP Basic Authentification then use this to set the username.
APP_NODE_URL_PASS HTTP Basic Authentification Password.
APP_INFURA_PROJECT_ID Infura Project ID. You can get this from your Infura Dashboard. Adding this will enable a dropdown to select from the available Infura endpoints.
APP_ROUTER_HISTORY_MODE When false (default mode) the explorer uses the URL hash for routing. Works with all browsers/servers, including those that do not support HTML5 History API. true requires HTML5 History API and server config to redirect all requests that do not have a file to index.html so they are picked by the react router. (false, true)
APP_NETWORK_MONITOR_URL Setting this variable to an URL will add a menu item in the sidebar with a link to the set url
APP_EXTRA_HEADER_TYPE This variable controls how the extraData block header is decoded and displayed. hexstring (default) converts the block extra data from hex to ASCII. ibft2 uses a specific mechanism for ibft2 based chains (hexstring, ibft2)

NOTICE: you must specify at least one of APP_NODE_URL or APP_INFURA_PROJECT_ID.

Only when building you also have access to

ENV var Description
APP_BASE_URL Deployment URL. This used in index.html for og:tags

Running in Docker

You can run the Lite Explorer in Docker without having to get the source code and build it. The simplest command to run it is

$ docker run -p 80:80 -e APP_INFURA_PROJECT_ID=429cef11213a44ada93a561fa8a85ff6 alethio/ethereum-lite-explorer

which will start a container on port 80 of your computer with a nginx embedded to serve the pre-build explorer. You can then open localhost in your browser to use it.

Please create an Infura project and get your own project ID to replace the one in the example above.

To configure the container at runtime please see configuration

So for example if you want to start the explorer with both infura and a custom node url, and have the container auto delete itself after you close it, you would run something like

docker \
    run --rm \
    -p 80:80 \
    -e APP_INFURA_PROJECT_ID=your-infura-proj-id \
    -e APP_NODE_URL= \

Setup/Build Instructions

Clone the explorer in a folder of your choosing

$ git clone
$ cd ethereum-lite-explorer

Install npm packages

$ npm install

Copy the sample config variables

$ cp config.default.json

Adjust to your needs. You can remove the variables you do not wish to change from default. Full list of options available here

After which you can build the explorer for production

$ npm run build

or development

$ npm run build-dev

the dist folder will then contain the minimised and optimised version fo the app. Got ahead and deploy it somewhere.

Finally you can run the explorer with

$ npm start

Running tests

npm test (or npm run test-coverage to generate code coverage as well).

Test coverage is written to ./coverage in HTML and LCOV formats.

Configuration for the VSCode LCOV extension is already included in the project.

Example setups

With Infura

Sign-up for an account or sign-in into your Infura account.

After that you have two options:

  • connect to a single network From the control panel, obtain your endpoint url for the network you are interested in (mainnet, ropsten, kovan, rinkeby). It will looks similar to

    Update .env.local file and set APP_NODE_URL to your Infura endpoint.

  • have a choice of infura networks and be able to switch between them From the control panel obtain your Infura Project ID

    Update .env.local file and set APP_INFURA_PROJECT_ID to your project id to get a dropdown of all the available Infura networks.

Build and start Lite Explorer

$ npm run build && npm start

With Parity Light Client

This will allow you to run both your own node and explorer. No third-party dependencies. It will be slower to browse older data because it is fetching it real time from other ethereum peer nodes but it's fast to sync and low in resource usage.

Install Parity Ethereum through one of the convenient methods and start it with the --light cli flag.

As a simple step, if you have Docker, you could just run

$ docker run -d --restart always --name parity-light -p parity/parity:stable --light --jsonrpc-interface all

Build and start Lite Explorer

$ npm run build && npm start

With Ganache

First of all, if you do not have it, download and install Ganache which will give you your own personal test chain.

After setting up and starting Ganache, update the .env.local file and set APP_NODE_URL to 'http://localhost:7545'.

Build and start Lite Explorer

$ npm run build && npm start

With Pantheon

This is a great way to use a full featured client, and to see how the explorer works with a private network.

First of all, if you do not have it, download and install Pantheon stable release.

To get started, run a Pantheon node in development mode, with the HTTP and WebSockets JSON-RPC services enabled, mining enabled, allowing traffic from all hosts and CORS origins :

$ pantheon --dev-mode --rpc-enabled --ws-enabled --miner-enabled --miner-coinbase=fe3b557e8fb62b89f4916b721be55ceb828dbd73 --host-whitelist=* --rpc-cors-origins=*

(Note: using "*" values for host whitelist and CORS origins is not a recommended way to run a production node securely, this configuration is intended for test or developement purpose only. For more information about these options, refer to the Pantheon CLI reference).

After running Pantheon, update the file, and set APP_NODE_URL to point to your running Pantheon URL:


Build and start Lite Explorer

$ npm run build && npm start

Example Deployments is a simple, single-command web publishing service that you can use to deploy your own version of the Lite Explorer.

Make sure you have set a proper and accessible APP_NODE_URL

# copy and edit a config file
$ cp config.default.json config.deploy.json
# install surge
$ npm install --global surge
# build explorer
$ npm run build
# go to build dir
$ cd dist
# make push state work as it should
$ cp ../config.deploy.json config.json && cp index.html 200.html
# deploy
$ surge
You can’t perform that action at this time.