Skip to main content

​
Prerequisites

Before you begin, ensure you have the following installed:
  • Node.js (v18 or higher)
  • pnpm (v10.30.3 or higher)
The project uses pnpm as its package manager. If you don’t have it installed: 
npm install -g pnpm

​
Installation

  1. Clone the repository:
git clone <repository-url>
cd been
  1. Install dependencies:
pnpm install
  1. Set up environment variables:
cp .env.example .env
Edit .env and add your Mapbox API key: 
VITE_API_KEY_MAPBOX=your_mapbox_token_here
You can obtain a free Mapbox API key from mapbox.com

​
Available Scripts

The project includes several npm scripts for development:

​
Development Server

Start the development server with hot module replacement: 
pnpm start
The application will be available at http://localhost:5173. The --host flag allows access from other devices on your network.

​
Build

Create a production build: 
pnpm build
This command:
  1. Runs TypeScript type checking (tsc --noEmit)
  2. Builds the application with Vite
  3. Outputs to the dist/ directory

​
Preview

Preview the production build locally: 
pnpm preview
Serves the built application at http://localhost:4173.

​
Linting

Check code quality with oxlint: 
pnpm lint
Automatically fix linting issues: 
pnpm lint:fix
The project uses oxlint with type-aware linting for fast, comprehensive code analysis.

​
Formatting

Check code formatting with Prettier: 
pnpm format
Automatically fix formatting issues: 
pnpm format:fix
Prettier is configured to format TypeScript, JavaScript, SCSS, HTML, JSON, YAML, and Markdown files.

​
Project Structure

The project uses Vite with the following configuration:
  • Source root: ./src
  • Build output: ../dist
  • Environment variables: ../.env

​
Tech Stack

  • Framework: React 19
  • Build Tool: Vite 7
  • State Management: Jotai
  • Styling: Tailwind CSS 4
  • Maps: Mapbox GL JS via react-map-gl
  • TypeScript: Strict configuration

​
Development Workflow

  1. Start the development server:
pnpm start
  1. Make your changes
  2. Run tests: 
pnpm test
  1. Check linting and formatting:
pnpm lint
pnpm format
  1. Build to verify production build works:
pnpm build

​
Troubleshooting

​
Port already in use

If port 5173 is already in use, Vite will automatically try the next available port.

​
Module resolution errors

Try clearing the node_modules and reinstalling: 
rm -rf node_modules pnpm-lock.yaml
pnpm install

​
Mapbox not loading

Ensure your VITE_API_KEY_MAPBOX environment variable is set correctly in .env. Environment variables must be prefixed with VITE_ to be accessible in the browser.

Build docs developers (and LLMs) love

Get started for freeTalk to us