Skip to main content


Docs curently based on: v3.0.0


Requires BDJuno to be on at least v1.1.0 release to support hasura actions(GraphQL API server).

Since v3.0.0, we have merged every chain's Big Dipper UI to be in a single branch according to the monorepo concept.

The following will guide you how to prepare and setup Big Dipper 2.0 UI for your own explorer. If you have any other questions please feel free to open an issue with your enquiry.

Clone the repository

Fork, clone, and check out our latest release for the most stable version or feel free to use the current documentation version.

$ git clone<user>/big-dipper-2.0-cosmos.git
$ cd big-dipper-2.0-cosmos/
$ git checkout tags/[latest release]

Prepare project directory

To run your own Big Dipper 2.0 UI, you will need to create new project directory. The following instructions will guide you how to correctly prepare it. For this example we will take examplenet as the chain name to illustrate it.

Use the base project to create your own project

  1. Rename Directory: Duplicate apps/web base project directory and rename it according to the chain name, in our case we will rename it to apps/web-examplenet.
  2. Update package.json: Update the workspace name with the project name web-examplenet in apps/web-examplenet/package.json at line 2:
"name": "web-examplenet",
"version": "1.0.0",


Remove unnecessary projects (optional)

Under the apps/ directory, you may find many projects such as web-agoric, web-akash..., etc. To reduce the project size, you can simply delete those apps/web-* directories and keep just apps/web-examplenet.

Prepare the config files

Chain config

The chain config file is located at apps/web-examplenet/src/chain.json. To customize your explorer, you need to:

  1. Update chainName field with the chain name of your project. For instance:
"chainName" : "examplenet"
  1. For the rest of the configs, including colors, themes, endpoints, etc., check chain config reference for a better understanding of what each section and field refers to.

General Config

In src/configs/general_config.json, update the json to give proper maintainer credits as well as a way for users to submit bugs/issues. For a better understanding of what each section and field refers to, please read the general config reference.


We will not be handling any opened issues directly related to your explorer as we won't have the proper info.

"maintainer": {
"name": "Forbole", // update
"url": "" // update
"github": {
"reportIssue": "" // update
"version": "v3.0.0"

Enviroment Variables

Create .env file inside the root of the project and update the environment variables


Add images

Add logo and icon files

The logos and icons are located at packages/shared-utils/assets/logos/*.svg & packages/shared-utils/assets/icons/*.svg.

Add your chain logo under packages/shared-utils/assets/logos/examplenet-light.svg and your chain icon under packages/shared-utils/assets/icons/examplenet-light.svg. To reduce the project size you can remove unnecessary logos and icons inside those folders.

Import images

The logos and icons are imported in packages/ui/src/components/ChainIcon/index.tsx. You can now delete the uneccessary imports of other chains in this file and add our examplenet logo and icon as follow:

import examplenetIconLight from 'shared-utils/assets/icons/examplenet-light.svg';
import examplenetLogoLight from 'shared-utils/assets/logos/examplenet-light.svg';

switch (chainName) {
case 'examplenet':
[iconDark, iconLight] =
type === 'icon'
? [examplenetIconLight, examplenetIconLight]
: [examplenetLogoLight, examplenetLogoLight];

Example of index.tsx:
import chainCoing from '@/chainConfig';
import { useStyles } from '@/components/ChainIcon/useStyles';
import classnames from 'classnames';
import Image, { type ImageProps } from 'next/future/image';

import baseIconLight from 'shared-utils/assets/icons/base-light.svg?url';
import baseLogoLight from 'shared-utils/assets/logos/base-light.svg?url';
import examplenetIconLight from 'shared-utils/assets/icons/examplenet-light.svg';
import examplenetLogoLight from 'shared-utils/assets/logos/examplenet-light.svg';

interface IconProps extends Omit<ImageProps, 'id' | 'src'> {
type: 'icon' | 'logo';
chainName?: string;

const ChainIcon = ({
chainName = chainCoing().chainName,
}: IconProps) => {
const { classes, cx } = useStyles();

let [iconDark, iconLight] =
type === 'icon' ? [baseIconLight, baseIconLight] : [baseLogoLight, baseLogoLight];
switch (chainName) {
case 'examplenet':
[iconDark, iconLight] =
type === 'icon'
? [examplenetIconLight, examplenetIconLight]
: [examplenetLogoLight, examplenetLogoLight];

throw new Error(`chain ${chainName} not supported`);
return (
<span className={cx(className, classes.container)}>
<Image width={0} height={0} src={iconDark} {...props} className={classes.dark} unoptimized />

export default ChainIcon;

Check Hasura is in sync with your graphql operations

In apps/web-examplenet/codegen.yml change the schema field to your graphql url to run yarn run graphql:codegen. It will regenerate the needed src/graphql/types.tsx. If an error occurs, it can indicate that the backend hasura was not setup correctly.

overwrite: true
- 'src/graphql/general/*'
schema: <your graphql url>
# omitOperationSuffix: true
skipTypeNameForRoot: true
- "typescript"
- "typescript-operations"
- "typescript-react-apollo" # To generate custom hooks per query

Start Development mode

Run yarn install and corepack enable && yarn dev --filter [project name] to start the dev mode.

$ yarn install
$ corepack enable && yarn dev --filter web-examplenet

Build and Run the Docker Image

Run docker-compose up to build and run the project's docker image. It reads the args from .env file, so if you want to run different project you should update the PROJECT_NAME variable inside the .env file.

List the explorer

If you would like to list your explorer among the rest of the BigDipper explorers, you can open a PR in this Repository with your network information added inside the networks.json file.

Example of networks.json file
"name": "exampleNet",
"logo": "",
"cover": "",
"links": [
"name": "Mainnet",
"chain_id": "examplenet-1",
"url": ""