Skip to main content

​
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

1

Clone the repository

Clone the Gridfinity Builder repository from GitHub:
git clone https://github.com/tunelko/gridfinity-BambuLab-3D.git
cd gridfinity-BambuLab-3D
2

Install dependencies

Install all required npm packages:
npm 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
3

Start the development server

Run the Vite development server:
npm run dev
The server will start on port 5173 with hot module replacement enabled.
4

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

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
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
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.
If changes aren’t reflected automatically:
  1. Check that you’re editing files inside the src/ directory
  2. Restart the dev server: Ctrl+C then npm run dev
  3. Clear browser cache and hard reload (Ctrl+Shift+R)
  4. If using Docker, ensure volumes are mounted correctly
The WASM CSG operations can be memory-intensive:
# Increase Node.js memory limit
export NODE_OPTIONS="--max-old-space-size=4096"
npm run dev

​
Next Steps

Docker Setup

Run Gridfinity Builder in a containerized environment

Building for Production

Create optimized production builds

Build docs developers (and LLMs) love

Get started for freeTalk to us