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

# Create an optimized production build
npm run build

# Generates static and server files in .next/ directory
# Minifies JavaScript and CSS
# Optimizes images and fonts

# Start the production server
npm start

# Must run 'npm run build' first
# Serves optimized production build

# Run ESLint to check code quality
npm run lint

# Uses Next.js ESLint config
# Checks for common errors and style issues

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

​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

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