Local Development Setup

Prerequisites

Before you begin, ensure you have the following installed:

Node.js 18+ (LTS recommended)
npm 9+

You can verify your installation by running:

node --version
npm --version

Installation

Clone the repository

Clone the Gridfinity Builder repository from GitHub:

git clone https://github.com/tunelko/gridfinity-BambuLab-3D.git
cd gridfinity-BambuLab-3D

Install dependencies

Install all required npm packages:

npm install

yarn install

pnpm install

This will install all dependencies including:

React 18.3.1
Three.js for 3D rendering
Manifold WASM CSG engine
Vite build tool
TypeScript compiler

Start the development server

Run the Vite development server:

npm run dev

yarn dev

pnpm dev

The server will start on port 5173 with hot module replacement enabled.

Access the application

Open your browser and navigate to:

http://localhost:5173

The app should load with the Gridfinity Builder interface.

Development Features

The development server includes:

Hot Module Replacement (HMR) - Changes reflect instantly without full page reload
TypeScript support - Full type checking and IntelliSense
PWA dev mode - Service worker enabled in development
File watching - Automatically rebuilds on file changes

Project Structure

src/
├── main.tsx                     # Entry point
├── App.tsx                      # Layout: Toolbar + Sidebar + Canvas
├── store/
│   └── useStore.ts              # Zustand store (bins, grid, undo/redo)
├── components/
│   ├── Toolbar.tsx              # Top bar: view modes, export, camera
│   ├── Sidebar.tsx              # Left panel: presets, bin list, BOM
│   ├── GridCanvas2D.tsx         # 2D SVG grid interactions
│   └── Viewport3D.tsx           # Three.js 3D preview
├── gridfinity/
│   ├── binGeometry.ts           # Manifold CSG bin generation
│   ├── baseplateGeometry.ts     # Baseplate generation
│   └── export3mf.ts             # 3MF packaging
└── workers/
    └── manifoldWorker.ts        # Background geometry generation

Troubleshooting

Port 5173 already in use

If port 5173 is already occupied, Vite will automatically try the next available port (5174, 5175, etc.). Check the terminal output for the actual port.Alternatively, you can specify a different port:

npm run dev -- --port 3000

WASM module fails to load

The Manifold 3D WASM module may fail to load due to browser restrictions or CORS issues.Solution:

Clear your browser cache
Ensure you’re using a modern browser (Chrome, Edge, Firefox)
Check the browser console for specific error messages
Verify that manifold-3d is properly installed in node_modules

TypeScript errors on install

If you see TypeScript compilation errors:

# Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

# Ensure TypeScript version is correct
npm list typescript

The project requires TypeScript ~5.6.2.

Hot reload not working

If changes aren’t reflected automatically:

Check that you’re editing files inside the src/ directory
Restart the dev server: Ctrl+C then npm run dev
Clear browser cache and hard reload (Ctrl+Shift+R)
If using Docker, ensure volumes are mounted correctly

Out of memory errors

The WASM CSG operations can be memory-intensive:

# Increase Node.js memory limit
export NODE_OPTIONS="--max-old-space-size=4096"
npm run dev

Setup

Contributing

Prerequisites

Installation

Development Features

Project Structure

Troubleshooting

Next Steps

Docker Setup

Building for Production

​Prerequisites

​Installation

​Development Features

​Project Structure

​Troubleshooting

​Next Steps

Docker Setup

Building for Production

Prerequisites

Installation

Development Features

Project Structure

Troubleshooting

Next Steps