# How to Set Up NextChat for Local Development: Complete Guide

> Easily set up NextChat for local development. Clone the repo, configure your API key, install dependencies, and run `yarn dev` to start your private ChatGPT clone locally. Get the complete guide now.

- Repository: [NextChat/NextChat](https://github.com/ChatGPTNextWeb/NextChat)
- Tags: how-to-guide
- Published: 2026-02-28

---

**To set up NextChat for local development, clone the ChatGPTNextWeb/NextChat repository, create a `.env.local` file containing your `OPENAI_API_KEY`, install dependencies with `yarn install`, build the mask files with `yarn mask`, and start the dev server with `yarn dev` to access the app at http://localhost:3000.**

NextChat (formerly ChatGPT-Next-Web) is a modern React and Next.js 14 application that runs entirely in the browser, proxying LLM requests through a lightweight API layer. Setting up NextChat for local development requires Node.js 18+, Yarn 1.x, and a minimal environment configuration to connect to OpenAI or compatible APIs.

## Prerequisites

Before you begin, ensure your system meets the following requirements:

- **Node.js** 18 or higher
- **Yarn** 1.x (classic) – the repository specifies `"packageManager": "yarn@1.22.19"` in [`package.json`](https://github.com/ChatGPTNextWeb/NextChat/blob/main/package.json) to ensure lockfile consistency
- **Git** for cloning the repository
- **Docker** (optional) if you prefer containerized development

## Step-by-Step Local Development Setup

### Clone the Repository

Start by cloning the official repository and navigating into the project directory:

```bash
git clone https://github.com/ChatGPTNextWeb/NextChat.git
cd NextChat

```

The repository root contains the [`README.md`](https://github.com/ChatGPTNextWeb/NextChat/blob/main/README.md) with the "Development" section and the [`package.json`](https://github.com/ChatGPTNextWeb/NextChat/blob/main/package.json) that defines all build scripts.

### Configure Environment Variables

Create a **`.env.local`** file at the project root (same directory as [`package.json`](https://github.com/ChatGPTNextWeb/NextChat/blob/main/package.json)). At minimum, add your OpenAI API key:

```dotenv
OPENAI_API_KEY=sk-your-api-key-here

# Optional: custom proxy for blocked regions or self-hosted APIs

# BASE_URL=https://your-custom-endpoint.com/api/proxy

```

The `dotenv` values are read by [`app/config/client.ts`](https://github.com/ChatGPTNextWeb/NextChat/blob/main/app/config/client.ts) on the server side via `getBuildConfig()` and injected into the client through a `<meta name="config">` tag. You can access these values at runtime using `getClientConfig()` as implemented in [`app/config/client.ts`](https://github.com/ChatGPTNextWeb/NextChat/blob/main/app/config/client.ts).

### Install Dependencies

Install the required packages using Yarn:

```bash
yarn install

```

This resolves the TypeScript compiler (`typescript@5.2.2`), Next.js 14 (`next@14.1.1`), React, and UI libraries defined in [`package.json`](https://github.com/ChatGPTNextWeb/NextChat/blob/main/package.json).

### Build Mask Files

NextChat stores prompt "masks" (prompt templates) as TypeScript files in `app/masks/`. Compile them before starting the dev server:

```bash
yarn mask

```

The `dev` script runs this step automatically, but running it manually ensures the `app/masks` directory is up-to-date before any `next dev` start.

### Start the Development Server

Launch the development environment:

```bash
yarn dev

```

The `dev` script (defined in [`package.json`](https://github.com/ChatGPTNextWeb/NextChat/blob/main/package.json)) concurrently runs `yarn mask:watch` (which re-generates masks on file changes) and `next dev`. The Next.js server listens on **http://localhost:3000** by default.

You should see console output similar to:

```

[Next] build mode standalone
[Next] build with chunk:  true
...
> Ready on http://localhost:3000

```

## Verify Proxy and API Configuration

If you need to route LLM calls through a custom endpoint (e.g., a self-hosted OpenAI-compatible API), set `BASE_URL` in `.env.local`. The proxy rewrites defined in `next.config.mjs` forward `/api/proxy/openai/*` to `https://api.openai.com/*` and similarly for Azure, Google, Anthropic, Alibaba, and other providers (see the `rewrites` array in `next.config.mjs` lines 65-103).

## Testing and Quality Assurance

Run the Jest test suite to ensure core utilities function correctly:

```bash
yarn test   # watches changes

# or for CI mode

yarn test:ci

```

The Jest configuration resides under `test/` and covers utilities such as [`vision-model-checker.test.ts`](https://github.com/ChatGPTNextWeb/NextChat/blob/main/vision-model-checker.test.ts) and [`model-provider.test.ts`](https://github.com/ChatGPTNextWeb/NextChat/blob/main/model-provider.test.ts).

## Optional: Desktop App Development with Tauri

To build the native desktop client:

```bash
yarn app:dev   # runs Tauri dev mode

# or

yarn app:build # creates native binaries for your OS

```

The Tauri configuration resides in `src-tauri/` (e.g., [`src-tauri/src/main.rs`](https://github.com/ChatGPTNextWeb/NextChat/blob/main/src-tauri/src/main.rs)). The `app:dev` script is defined in [`package.json`](https://github.com/ChatGPTNextWeb/NextChat/blob/main/package.json).

## Key Files for Local Development Configuration

| Path | Role |
|------|------|
| `.env.local` | Local runtime configuration (API keys, proxy settings) |
| [`app/config/client.ts`](https://github.com/ChatGPTNextWeb/NextChat/blob/main/app/config/client.ts) | Runtime config helper (`getClientConfig`) that reads build-time constants |
| `next.config.mjs` | API rewrites, CORS headers, and webpack configuration |
| [`package.json`](https://github.com/ChatGPTNextWeb/NextChat/blob/main/package.json) | Development scripts (`dev`, `mask`, `test`, `app:dev`) |
| [`app/layout.tsx`](https://github.com/ChatGPTNextWeb/NextChat/blob/main/app/layout.tsx) | Root layout and metadata for the application |
| [`app/utils/token.ts`](https://github.com/ChatGPTNextWeb/NextChat/blob/main/app/utils/token.ts) | Server-side token handling utilities |
| [`src-tauri/src/main.rs`](https://github.com/ChatGPTNextWeb/NextChat/blob/main/src-tauri/src/main.rs) | Native desktop wrapper entry point (optional) |

## Summary

- **Clone and install**: Use `git clone` and `yarn install` with Node.js 18+ and Yarn 1.x to match the `packageManager` specification in [`package.json`](https://github.com/ChatGPTNextWeb/NextChat/blob/main/package.json).
- **Configure environment**: Create `.env.local` with `OPENAI_API_KEY` and optional `BASE_URL`; these values are injected via [`app/config/client.ts`](https://github.com/ChatGPTNextWeb/NextChat/blob/main/app/config/client.ts).
- **Prepare masks**: Run `yarn mask` to compile prompt templates before starting the dev server.
- **Start developing**: Execute `yarn dev` to launch Next.js on `localhost:3000` with hot reload and mask watching.
- **Test and extend**: Use `yarn test` for Jest validation and `yarn app:dev` to build the Tauri desktop client.

## Frequently Asked Questions

### What Node.js version is required to set up NextChat for local development?

NextChat requires **Node.js 18 or higher**. The build system leverages Next.js 14 features and modern Node APIs that are not available in earlier versions. You can verify your version with `node -v` before running `yarn install`.

### Why does NextChat use Yarn 1.x instead of npm or Yarn 3?

The repository explicitly declares `"packageManager": "yarn@1.22.19"` in [`package.json`](https://github.com/ChatGPTNextWeb/NextChat/blob/main/package.json) to ensure consistent lockfile behavior and compatibility with the mask build scripts. Using Yarn 1.x (classic) prevents lockfile mismatches that can occur with npm or Yarn Berry's Plug'n'Play system.

### How do I connect NextChat to a custom OpenAI-compatible API during local development?

Set the `BASE_URL` environment variable in your `.env.local` file to point to your custom endpoint (e.g., `BASE_URL=https://your-api.com/api/proxy`). The `next.config.mjs` rewrites will automatically route requests from `/api/proxy/openai/*` to your specified base URL, allowing you to use self-hosted or third-party LLM providers.

### What is the purpose of the `yarn mask` command in NextChat development?

The `yarn mask` command compiles TypeScript mask files located in `app/masks/` into the application bundle. These masks are prompt templates that appear in the NextChat UI. Running this command ensures the latest prompt definitions are available before you start the development server with `yarn dev`.