Skip to content

Frontend Getting Started

This tutorial walks you through setting up the 2Sigma frontend (ai-tutor-ui) locally and getting it connected to a running backend.

What You'll Learn

By the end of this tutorial, you will:

  1. Clone the frontend repository
  2. Install Node.js dependencies
  3. Configure environment variables
  4. Start the development server
  5. Verify the app works end-to-end with the backend
  6. Know which npm scripts are available and what they do

Prerequisites

Before starting, make sure you have:

  • Node.js 20+ installed
  • npm installed (comes with Node.js)
  • Git installed
  • The backend running locally (follow the Backend Getting Started first)

Estimated Time

This tutorial takes approximately 10 minutes to complete.

Backend Required

The frontend is a client app. Most features won't work without the backend API running. Complete the Backend Getting Started before continuing here.

Step 1: Clone the Repository

git clone <your-repo-url>
cd ai-tutor-ui

Step 2: Install Dependencies

npm install

This downloads and installs all packages listed in package.json, including Next.js, React, Tailwind CSS, and the testing libraries.

Tip

If you see peer dependency warnings, they're usually safe to ignore. Only act on errors.

Step 3: Configure Environment

The frontend reads configuration from a .env.local file that you create locally. This file is never committed to version control.

Create .env.local in the ai-tutor-ui directory:

NEXT_PUBLIC_APP_NAME=2Sigma
NEXT_PUBLIC_API_BASE_URL=http://localhost:9898/api/v1

NEXT_PUBLIC_API_BASE_URL tells the frontend where to find the backend API. It must match the address and port your backend is actually listening on.

Environment Variable Prefix

Variables prefixed with NEXT_PUBLIC_ are embedded into the browser bundle at build time. They are visible to anyone who inspects your JavaScript. Never put secrets or API keys in NEXT_PUBLIC_ variables.

Step 4: Start the Development Server

npm run dev

You should see output like this:

  ▲ Next.js 16.x.x
  - Local:        http://localhost:3000
  - Environments: .env.local

 ✓ Starting...
 ✓ Ready in 2.1s

Server Running

Your frontend is now running at http://localhost:3000

The dev server includes hot reload. Any changes you save to source files will reflect in the browser immediately, without a manual refresh.

Step 5: Verify It Works

Open your browser and go to http://localhost:3000.

You should land on the sign-in page. From there:

  1. Click Register to create a new account
  2. Fill in your name, email, and password
  3. Submit the form
  4. You should be redirected to the dashboard

If registration succeeds, the frontend is correctly talking to the backend.

Already Have an Account?

If you registered a user while following the backend tutorial, you can sign in with those credentials directly.

Step 6: Available npm Scripts

Command Description
npm run dev Start development server with hot reload
npm run build Build production bundle
npm start Start production server
npm run lint Run ESLint
npm run test Run tests in watch mode
npm run test:run Run tests once
npm run test:coverage Run tests with coverage report
npm run test:ui Open Vitest UI

Troubleshooting

Port 3000 Already in Use

If you see Error: listen EADDRINUSE: address already in use :::3000, something else is running on that port.

# Find what's using port 3000
lsof -i :3000

# Kill it by PID
kill -9 <PID>

PORT=3001 npm run dev

Then open http://localhost:3001 instead.

API Connection Errors

If you see network errors or the app shows "Failed to connect" messages:

  • Confirm the backend is running: open http://localhost:9898/docs in your browser. You should see the Swagger UI.
  • Check that NEXT_PUBLIC_API_BASE_URL in .env.local matches the backend address exactly, including the port.
  • After changing .env.local, restart the dev server. Next.js only reads environment files on startup.

Restart Required

Changes to .env.local don't hot-reload. Stop the server with Ctrl+C and run npm run dev again.

Module Not Found Errors

If you see Cannot find module '...' errors after pulling new changes:

npm install

A teammate likely added a new dependency. Running npm install again syncs your local node_modules with package.json.

Next Steps

You now have a working local frontend connected to the backend.

Here's what to explore next:

Need help? Check the Backend Getting Started if the API isn't responding, or review the Frontend Architecture for a deeper understanding of the codebase.