# How to Build the Apache Superset Frontend: A Complete Guide

> Learn to build the Apache Superset frontend. Follow this guide to install dependencies with Bun, configure env vars, and run the build command for a seamless development experience.

- Repository: [Superset/superset](https://github.com/superset-sh/superset)
- Tags: how-to-guide
- Published: 2026-03-08

---

**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:

```bash
bun install

```

If you prefer npm or yarn, substitute with `npm install` or `yarn install`. This command reads the root [`package.json`](https://github.com/superset-sh/superset/blob/main/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:

```bash
cp .env.example .env

```

Edit the `.env` file to set values such as `NEXT_PUBLIC_API_URL` or Sentry tokens. The [`next.config.ts`](https://github.com/superset-sh/superset/blob/main/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:

```bash
cd apps/web
bun run build

```

This command executes the `build` script defined in [`apps/web/package.json`](https://github.com/superset-sh/superset/blob/main/apps/web/package.json), which runs `next build`. The process compiles TypeScript using the configuration from [`apps/web/tsconfig.json`](https://github.com/superset-sh/superset/blob/main/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`](https://github.com/superset-sh/superset/blob/main/next.config.ts).

## Understanding the Build Configuration

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

- **[`apps/web/package.json`](https://github.com/superset-sh/superset/blob/main/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`](https://github.com/superset-sh/superset/blob/main/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`](https://github.com/superset-sh/superset/blob/main/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:

```bash
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:

```bash
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`](https://github.com/superset-sh/superset/blob/main/apps/web/package.json) (build scripts), [`apps/web/next.config.ts`](https://github.com/superset-sh/superset/blob/main/apps/web/next.config.ts) (Next.js and Sentry settings), and [`apps/web/tsconfig.json`](https://github.com/superset-sh/superset/blob/main/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`](https://github.com/superset-sh/superset/blob/main/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`](https://github.com/superset-sh/superset/blob/main/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`](https://github.com/superset-sh/superset/blob/main/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.