How to Build the Apache Superset Frontend: A Complete Guide

Build the Apache Superset frontend by installing monorepo dependencies with Bun, configuring environment variables from .env.example, and running next build from the apps/web workspace.

The Apache Superset frontend is a modern React application living in the superset-sh/superset repository. Located in the apps/web workspace, it uses Next.js 16, React 19, and TypeScript to deliver the analytics interface. Whether you are contributing features or deploying a production instance, understanding the build pipeline is essential for working with this codebase.

Prerequisites for Building the Superset Frontend

Before initiating the build process, ensure your environment meets the following requirements:

• Node.js compatible with Next.js 16 (the repository uses Bun as its primary package manager, but npm and yarn are supported)
• Bun (recommended) or an alternative package manager installed globally
• A copy of the superset-sh/superset repository cloned locally

The frontend build depends on internal packages referenced as @superset/* within the monorepo structure, so you must install dependencies from the repository root to resolve these workspace links.

Step-by-Step Guide to Build the Apache Superset Frontend

Install Monorepo Dependencies

The first step resolves all third-party libraries and internal workspace packages required by the frontend. From the repository root, run:

bun install

If you prefer npm or yarn, substitute with npm install or yarn install. This command reads the root package.json, which declares the apps/web workspace along with shared TypeScript configurations and internal utilities.

Configure Environment Variables

The build process requires specific environment variables for API endpoints, Sentry integration, and public configuration. Prepare your environment file by copying the template:

cp .env.example .env

Edit the .env file to set values such as NEXT_PUBLIC_API_URL or Sentry tokens. The next.config.ts file in apps/web automatically loads these variables during the build, and the Sentry integration configured there requires certain environment variables to be present to avoid build failures.

Execute the Production Build

Navigate to the frontend workspace and initiate the Next.js build process:

cd apps/web
bun run build

This command executes the build script defined in apps/web/package.json, which runs next build. The process compiles TypeScript using the configuration from apps/web/tsconfig.json, bundles React components, optimizes static assets, and generates the production output in the .next directory. The build also applies Sentry configuration via withSentryConfig as specified in next.config.ts.

Understanding the Build Configuration

Several key files control how the Apache Superset frontend is compiled:

• apps/web/package.json: Declares the "build": "next build" script and workspace dependencies, including internal @superset/* packages and Next.js 16.

• apps/web/next.config.ts: Contains the Next.js configuration object with React compiler settings, image remote patterns for external assets, PostHog rewrites, and Sentry integration via withSentryConfig.

• apps/web/tsconfig.json: Extends the shared Superset TypeScript preset and defines path aliases (such as @/* mapping to ./src/*) used throughout the source code.

These configurations ensure the build produces optimized bundles compatible with the React 19 runtime and Next.js 16 features.

Verifying and Serving the Build Output

After the build completes successfully, verify the generated artifacts in the output directory:

ls -la apps/web/.next

This directory contains server bundles, static assets, and prerendered HTML files ready for deployment.

To test the production build locally before deploying:

cd apps/web
bun run start

This starts the Next.js production server, typically available at http://localhost:3000, using the exact same files served in production deployments on Vercel, Netlify, or self-hosted environments.

Summary

• The Apache Superset frontend resides in the apps/web workspace as a Next.js 16 application using React 19 and TypeScript.
• Build the frontend by running bun install from the repository root, configuring .env from .env.example, and executing bun run build in apps/web.
• Key configuration files include apps/web/package.json (build scripts), apps/web/next.config.ts (Next.js and Sentry settings), and apps/web/tsconfig.json (TypeScript paths).
• Production output is generated in apps/web/.next and can be served locally with bun run start or deployed to any Node.js hosting platform.

Frequently Asked Questions

What package manager should I use to build the Superset frontend?

The repository is optimized for Bun, which resolves workspace dependencies faster than npm or yarn. However, the build scripts in apps/web/package.json are compatible with npm and yarn if you prefer those tools. All three package managers correctly resolve the internal @superset/* workspace packages required by the frontend.

Do I need to set up environment variables before building?

Yes, the build process expects certain environment variables to be present, particularly for Sentry integration and public API configuration. Copy .env.example to .env in the repository root and populate values such as NEXT_PUBLIC_API_URL before running bun run build. The next.config.ts file reads these variables during compilation.

Can I use npm instead of Bun to run the build commands?

Yes, you can substitute bun with npm throughout the build process. Use npm install from the root, then npm run build inside apps/web. The package.json scripts are written to be package-manager agnostic, though Bun offers faster installation times for the large monorepo dependency tree.

Where does the production build output go?

The compiled frontend assets are written to the apps/web/.next directory. This folder contains server-side bundles, static JavaScript and CSS assets, and prerendered HTML pages. You can serve these files locally using bun run start (or npm run start) from the apps/web directory, or deploy the .next folder to any hosting platform supporting Next.js applications.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}