Environment:Apache Druid Web Console Development

Knowledge Sources	Apache Druid
Domains	Frontend Development, TypeScript, React, Webpack
Last Updated	2026-02-10 10:00 GMT

Overview

The Web Console Development environment provides the toolchain and runtime configuration for building, testing, and running the Apache Druid web console -- a TypeScript/React single-page application served via the Druid Router.

Description

The Apache Druid web console is a React 18 single-page application written in TypeScript, bundled with Webpack 5, and styled with SCSS via Dart Sass. It uses @blueprintjs/core as its primary UI component library, axios for HTTP communication with the Druid cluster API, d3 and echarts for data visualization, and druid-query-toolkit for SQL query construction.

The build pipeline compiles TypeScript to ES2016 (matching the target in tsconfig.json), processes SCSS through PostCSS with autoprefixer, and outputs bundled JavaScript and assets to the public/ directory. The browserslist configuration excludes Internet Explorer 11 and targets modern browsers supporting ES6.

The development server runs on port 18081 and proxies API requests (/status, /druid, /proxy) to the Druid Router, whose address defaults to localhost:8888 but can be overridden via the druid_host environment variable.

Usage

Use this environment when:

Developing new features or fixing bugs in the Druid web console UI
Running the webpack dev server for hot-reloading during frontend development
Executing unit tests (Jest) or end-to-end tests (Playwright) against the console
Building production bundles for inclusion in the Druid distribution
Auditing or updating frontend dependency licenses

System Requirements

Category	Requirement	Notes
Runtime	Node.js >= 20	`engines` field in `package.json:40`; Volta pins to 20.9.0
Package Manager	npm 10.9.0	Volta-pinned in `package.json:44`
Language	TypeScript ~5.5.4	`devDependencies` in `package.json:156`
Build Target	ES2016	`tsconfig.json` `target` field, line 23
Browser Support	ES6+ (no IE11)	`browserslist` in `package.json:46-51`
OS	Linux, macOS, Windows	Cross-platform via Node.js
Disk Space	~500 MB	For `node_modules` after `npm install`
Dev Server Port	18081	`webpack.config.mjs` line 100

Dependencies

System Packages

Node.js >= 20 (recommended: 20.9.0 via Volta)
npm 10.9.0
Git (for pre-commit hooks and version control)

Language Packages

Runtime dependencies (from package.json):

react ^18.3.1, react-dom ^18.3.1
@blueprintjs/core ^5.16.0
axios ^1.12.0
druid-query-toolkit ^1.2.2
echarts ^5.5.1
d3-array ^3.2.4, d3-axis ^3.0.0, d3-scale ^4.0.2, d3-selection ^3.0.0, d3-shape ^3.2.0
zustand ^4.5.5
react-router-dom ^5.3.4
ace-builds ~1.5.3

Dev dependencies (from package.json):

webpack ^5.89.0, webpack-dev-server ^5.2.2, webpack-cli ^5.1.4
typescript ~5.5.4
jest ^29.7.0, ts-jest ^29.2.5
playwright-chromium ^1.24.1
eslint ^9.31.0
prettier ^2.5.1
sass ^1.59.3

Allowed Licenses

Production dependencies must use one of the following licenses (enforced by npm run check-licenses):

Apache-1.1, Apache-2.0, BSD-2-Clause, BSD-3-Clause, 0BSD, MIT, ISC, CC0-1.0, OFL-1.1

Credentials

No secrets or API keys are required. The following environment variables configure the build and dev server:

Variable	Purpose
`druid_host`	Target Druid cluster URL for the dev server proxy (default: `localhost:8888`)
`NODE_ENV`	Set to `production` for optimized builds; defaults to `development`
`BUNDLE_ANALYZER_PLUGIN`	Set to `TRUE` to enable webpack bundle analysis on port 18082
`DRUID_E2E_TEST_HEADLESS`	Controls headless mode for Playwright E2E tests
`DRUID_E2E_TEST_UNIFIED_CONSOLE_PORT`	Port override for E2E test target

Quick Install

# Clone the repository
git clone https://github.com/apache/druid.git
cd druid/web-console

# Install dependencies (Volta recommended for version pinning)
npm install

# Start the dev server (proxies to a running Druid cluster on localhost:8888)
npm start

# Or specify a custom Druid host
druid_host=my-druid-router:8888 npm start

# Run unit tests
npm test

# Run E2E tests (requires a running Druid cluster)
npm run test-e2e

# Build for production
NODE_ENV=production npm run compile

# Check dependency licenses
npm run check-licenses

Code Evidence

Node.js engine requirement (web-console/package.json:39-44):

  "engines": {
    "node": ">=20"
  },
  "volta": {
    "node": "20.9.0",
    "npm": "10.9.0"
  },

TypeScript build target (web-console/tsconfig.json:23):

    "target": "es2016"

Webpack dev server port and proxy (web-console/webpack.config.mjs:98-116):

    devServer: {
      host: '0.0.0.0',
      port: 18081,
      hot: true,
      // ...
      proxy: [
        {
          context: ['/status', '/druid', '/proxy'],
          target: druidUrl,
          secure: false,
        },
      ],
    },

Browserslist configuration (web-console/package.json:46-51):

  "browserslist": [
    "> 1% and supports es6",
    "last 3 versions and supports es6",
    "Firefox ESR",
    "not dead",
    "not ie 11"
  ],

License enforcement (web-console/package.json:36):

    "check-licenses": "license-checker --production --onlyAllow 'Apache-1.1;Apache-2.0;BSD-2-Clause;BSD-3-Clause;0BSD;MIT;ISC;CC0-1.0;OFL-1.1' --summary"

Common Errors

Error Message	Cause	Solution
`Node.js version mismatch: expected >=20`	Node.js version older than 20	Install Node.js 20+ or use Volta: `volta install node@20.9.0`
`ECONNREFUSED 127.0.0.1:8888`	Dev server cannot reach Druid Router	Start a Druid cluster or set `druid_host` to point to an available cluster
`Module not found: Error: Can't resolve ...`	Missing `node_modules`	Run `npm install` in the `web-console` directory
License check failure	A dependency uses a non-allowed license	Review the dependency with `npm run generate-licenses-file` and remove or replace the offending package
`TypeError: Cannot read properties of undefined (reading 'consoleConfig')`	HTML entry point missing `window.consoleConfig`	Ensure `unified-console.html` defines `window.consoleConfig = {}` before the bundle loads

Compatibility Notes

The build target is ES2016, so all output JavaScript uses ES2016 features. Browsers must support at minimum ES6 (ES2015).
Internet Explorer 11 is explicitly excluded via the browserslist configuration.
The Webpack dev server binds to 0.0.0.0 (all interfaces), allowing access from Docker containers or remote machines.
HTTPS-enabled Druid clusters on port 9088 are auto-detected when the druid_host value ends with :9088.
Dart Sass is used instead of node-sass for broader CPU architecture compatibility (ARM64, x86_64).
Blueprint SCSS requires a workaround for svg-icon functions that are not available outside of Blueprint's own build process (see webpack.config.mjs sass-loader options).

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment