Skip to main content
Been is a web application that lets you track and visualize the countries you’ve visited on an interactive 3D globe powered by Mapbox GL JS. This guide will help you get the application running locally.

​
Prerequisites

Before you begin, ensure you have the following installed:
  • Node.js 18.0 or later
  • pnpm 10.30.3 or later (specified as the package manager)
  • A Mapbox account and API access token (free tier works fine)
Been uses pnpm as its package manager. While npm or yarn might work, pnpm is recommended for compatibility.

​
Get a Mapbox Access Token

Been requires a Mapbox API key to render the interactive globe. Here’s how to get one:
1

Create a Mapbox Account

Go to mapbox.com and sign up for a free account if you don’t have one already.
2

Access Your Tokens

Once logged in, navigate to your Account Dashboard and click on “Tokens” in the sidebar.
3

Copy Your Token

Copy your default public token, or create a new token with public scopes. You’ll need this in the next section.
Keep your Mapbox token secure. Never commit it to version control or share it publicly.

​
Installation

1

Clone the Repository

Clone the Been repository to your local machine:
git clone https://github.com/yourusername/been.git
cd been
2

Install Dependencies

Install the required dependencies using pnpm:
pnpm install
This will install all necessary packages including:
  • React 19 for the UI framework
  • Mapbox GL JS and react-map-gl for map rendering
  • Tailwind CSS 4 for styling
  • Jotai for state management
  • Turf.js for geospatial calculations
3

Configure Environment Variables

Create a .env file in the root directory by copying the example file:
cp .env.example .env
Open the .env file and add your Mapbox access token:
.env
VITE_API_KEY_MAPBOX=your_mapbox_token_here
Replace your_mapbox_token_here with the token you copied from Mapbox.
4

Start the Development Server

Launch the development server:
pnpm start
You should see output similar to:
VITE v7.0.0  ready in 324 ms

➜  Local:   http://localhost:5173/
➜  Network: http://192.168.1.10:5173/
➜  press h + enter to show help
5

Open in Browser

Navigate to http://localhost:5173 in your web browser.You should see the Been application with:
  • The “been” header at the top
  • An interactive 3D globe taking up most of the screen
  • A menu panel where you can select countries

​
Verify Your Setup

To ensure everything is working correctly:
  1. Check the Globe Renders: You should see a 3D Mapbox globe that you can rotate and zoom
  2. Test Dark Mode: Your system’s color scheme preference should be reflected (light or dark theme)
  3. Select a Country: Use the menu panel to search for and select a country
  4. View Visualization: Selected countries should appear highlighted in orange on the globe
The globe adapts to your system’s color scheme automatically. If you prefer dark mode, enable it in your system preferences.

​
Project Structure

Here’s a quick overview of the key files and directories: 
been/
├── src/
│   ├── components/       # React components
│   │   ├── app.tsx      # Main application component
│   │   ├── globe.tsx    # Mapbox GL globe component
│   │   ├── menu.tsx     # Country selection menu
│   │   └── ...
│   ├── hooks/           # Custom React hooks
│   ├── state/           # Jotai state management
│   ├── data/            # Country data
│   ├── models/          # TypeScript models and enums
│   ├── utils/           # Utility functions
│   ├── index.tsx        # Application entry point
│   └── index.html       # HTML template
├── .env                 # Environment variables (create this)
├── .env.example         # Environment template
├── package.json         # Project dependencies
├── vite.config.ts       # Vite configuration
└── tsconfig.json        # TypeScript configuration

​
Common Issues

This is usually caused by a missing or invalid Mapbox token. Double-check that:
  • Your .env file exists in the root directory
  • The variable is named exactly VITE_API_KEY_MAPBOX
  • Your Mapbox token is valid and has public scopes
  • You restarted the dev server after creating the .env file
Install pnpm globally using npm:
npm install -g pnpm
Or use other installation methods from the pnpm documentation.
If port 5173 is already in use, Vite will automatically try the next available port. Check the terminal output for the actual URL.Alternatively, you can specify a different port:
pnpm start -- --port 3000
Make sure all dependencies are properly installed. Try:
rm -rf node_modules pnpm-lock.yaml
pnpm install

​
Next Steps

Now that you have Been running locally, you can:
  • Start tracking countries you’ve visited
  • Explore the codebase to understand how the Mapbox integration works
  • Customize the styling using Tailwind CSS
  • Run the test suite with pnpm test
  • Build for production with pnpm build

Architecture

Learn about the project architecture and how components work together

Components

Explore the component library and their APIs

Deployment

Deploy your instance of Been to production

Testing

Learn about the testing setup and how to write tests

Build docs developers (and LLMs) love

Get started for freeTalk to us