Development Setup

Prerequisites

Before you begin, ensure you have the following installed on your system:

Node.js 20.x or higher
npm (comes with Node.js) or your preferred package manager
Git for version control
A code editor (VS Code recommended)

Quick Start

Get BeeHex running locally in minutes:

Clone the Repository

Clone the BeeHex repository to your local machine:

git clone <repository-url>
cd beehex_v2

Install Dependencies

Install all required npm packages:

npm install

This will install:

Next.js 14.2.20 (React framework)
Socket.IO Client 4.7.5 (real-time communication)
TypeScript 5.x (type safety)
Styled Components 6.1.13 (styling)
ECharts 5.6.0 (data visualization)
And other dependencies

Configure Environment

Create your environment configuration file:

# The env.ts file is gitignored for security
touch src/env/env.ts

Add your environment configuration:

src/env/env.ts

export default function getEnv() {
  return {
    'IP_HOST': '127.0.0.1', // Game server IP
  };
}

The IP_HOST variable points to your game server. For local development, use 127.0.0.1 or localhost.

Start Development Server

Launch the Next.js development server:

npm run dev

Your app will be available at http://localhost:3000

Environment Configuration

Environment Variables

BeeHex uses a custom environment configuration system located in src/env/env.ts:

export default function getEnv() {
  return {
    'IP_HOST': '127.0.0.1',
  };
}

The src/env/env.ts file is excluded from version control (.gitignore) to prevent exposing sensitive configuration. Never commit this file.

Required Configuration

Variable	Description	Default	Required
`IP_HOST`	Game server IP address for WebSocket connections	`127.0.0.1`	Yes

Using Environment Variables

Import the configuration in your components:

import getEnv from '@/env/env';

const env = getEnv();
const socket = new WebSocket(`ws://${env['IP_HOST']}:3002/`);

Project Structure

Understanding the BeeHex codebase organization:

beehex_v2/
├── src/
│   ├── app/                    # Next.js App Router
│   │   ├── about/             # About page
│   │   ├── game_mode/         # Game mode selection
│   │   ├── hex/               # Hex game pages
│   │   │   └── [gameId]/      # Dynamic game routes
│   │   ├── history/           # Game history
│   │   ├── home/              # Home page
│   │   ├── login_register/    # Authentication
│   │   ├── my_account/        # User account
│   │   ├── rank/              # Rankings
│   │   ├── layout.tsx         # Root layout
│   │   ├── page.tsx           # Landing page
│   │   └── definitions.ts     # TypeScript interfaces
│   ├── components/            # Reusable React components
│   │   ├── analysis_board/    # Game analysis UI
│   │   ├── bottom_navbar/     # Navigation bar
│   │   ├── button/            # Button components
│   │   ├── custom_alert/      # Alert dialogs
│   │   ├── input_text/        # Input fields
│   │   ├── loading_page/      # Loading states
│   │   ├── stepped_slider/    # Slider controls
│   │   └── title_h1/          # Heading components
│   ├── assets/                # Static assets
│   └── env/                   # Environment config
│       └── env.ts             # Environment variables (gitignored)
├── public/                    # Static files
│   ├── favicon.svg           # App icon
│   ├── exemple.gif           # Demo assets
│   └── logo_polytech.png     # Branding
├── next.config.mjs           # Next.js configuration
├── tsconfig.json             # TypeScript config
├── tsconfig.worker.json      # Web Worker TypeScript config
├── package.json              # Dependencies and scripts
└── .eslintrc.json            # ESLint configuration

Available Scripts

BeeHex includes several npm scripts for development and production:

# Start the development server with hot reload
npm run dev

# Development server runs on http://localhost:3000
# Changes auto-update without page refresh

Script Details

Script	Command	Description
`dev`	`next dev`	Starts development server on port 3000 with hot reload
`build`	`next build`	Creates optimized production build
`start`	`next start`	Runs production server (requires build first)
`lint`	`next lint`	Runs ESLint with Next.js configuration

TypeScript Configuration

BeeHex uses TypeScript with strict mode enabled for type safety:

Main Configuration (`tsconfig.json`)

{
  "compilerOptions": {
    "lib": ["dom", "dom.iterable", "esnext"],
    "strict": true,
    "module": "es2020",
    "moduleResolution": "bundler",
    "jsx": "preserve",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

The @/* path alias allows you to import from src/ without relative paths:

import getEnv from '@/env/env';
import { Game } from '@/app/definitions';

Web Worker Configuration (`tsconfig.worker.json`)

BeeHex uses Web Workers for game algorithm calculations:

{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "outDir": "./public/workers",
    "module": "ES2020",
    "noEmit": false
  },
  "include": [
    "src/app/hex/[gameId]/AlgorithmWorker.ts"
  ]
}

Workers are compiled to public/workers/ for client-side execution.

Next.js Configuration

Configuration File (`next.config.mjs`)

const nextConfig = {
  reactStrictMode: false
};
export default nextConfig;

React Strict Mode is disabled to prevent double-rendering issues with WebSocket connections and game state management.

Key Features

App Router: BeeHex uses Next.js 14’s App Router for file-based routing
Dynamic Routes: Game pages use dynamic routes (hex/[gameId])
Server Components: Leverages React Server Components for optimal performance
Font Optimization: Automatic optimization for Nunito and Noto Sans fonts

Development Workflow

Start the Dev Server

npm run dev

Make Changes

Edit files in src/app/ or src/components/Changes hot-reload automatically in your browser

Check Type Safety

TypeScript checks types in real-time

# Run type checking manually
npx tsc --noEmit

Lint Your Code

npm run lint

Test Your Changes

Open http://localhost:3000 and verify your changes

Common Issues

Port Already in Use

If port 3000 is already in use:

# Use a different port
PORT=3001 npm run dev

Module Not Found

If you see module resolution errors:

# Clear Next.js cache and reinstall
rm -rf .next node_modules package-lock.json
npm install

WebSocket Connection Failed

If WebSocket connections fail:

Verify IP_HOST in src/env/env.ts is correct
Ensure the game server is running on port 3002
Check browser console for connection errors

TypeScript Errors

If you encounter TypeScript errors:

# Regenerate Next.js types
rm -rf .next
npm run dev

IDE Setup

VS Code (Recommended)

Recommended extensions:

ES7+ React/Redux/React-Native snippets: Code snippets
TypeScript Vue Plugin (Volar): Enhanced TypeScript support
ESLint: Real-time linting
Prettier: Code formatting
Error Lens: Inline error display

VS Code Settings

Create .vscode/settings.json:

{
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "typescript.tsdk": "node_modules/typescript/lib"
}

Next Steps

Architecture Overview

Learn about BeeHex’s technical architecture

Contributing

Start contributing to the project

Deployment

Deploy BeeHex to production

Game Engine

Explore the game engine implementation

Architecture

Development

Documentation Index

​Prerequisites

​Quick Start

​Environment Configuration

​Environment Variables

​Required Configuration

​Using Environment Variables

​Project Structure

​Available Scripts

​Script Details

​TypeScript Configuration

​Main Configuration (tsconfig.json)

​Web Worker Configuration (tsconfig.worker.json)

​Next.js Configuration

​Configuration File (next.config.mjs)

​Key Features

​Development Workflow

​Common Issues

​Port Already in Use

​Module Not Found

​WebSocket Connection Failed

​TypeScript Errors

​IDE Setup

​VS Code (Recommended)

​VS Code Settings

​Next Steps

Architecture Overview

Contributing

Deployment

Game Engine

Build docs developers (and LLMs) love

Prerequisites

Quick Start

Environment Configuration

Environment Variables

Required Configuration

Using Environment Variables

Project Structure

Available Scripts

Script Details

TypeScript Configuration

Main Configuration (`tsconfig.json`)

Web Worker Configuration (`tsconfig.worker.json`)

Next.js Configuration

Configuration File (`next.config.mjs`)

Key Features

Development Workflow

Common Issues

Port Already in Use

Module Not Found

WebSocket Connection Failed

TypeScript Errors

IDE Setup

VS Code (Recommended)

VS Code Settings

Next Steps