3D Print Builder is a high-performance, web-based parametric 3D modeling tool built with Next.js and React Three Fiber. Currently focused on a "Vase Builder" MVP, this application allows users to visually generate, edit, and manipulate 3D-printable geometry directly in the browser using an intuitive combination of sliders, toggles, and a 2D spline editor.
Designed with a strict separation of concerns, the application features a purely mathematical, React-free TypeScript geometry engine, schema-driven UI panels, and isolated state layers to ensure maximum performance and testability.
Please note that this project is actively being developed as an MVP. Current limitations include:
- Exporting is not yet functional: The export to 3D-printable formats (like STL) is currently stubbed and deferred to a future update.
- Incomplete Modifiers: Not all modifier options and menu settings are fully implemented or working at this time.
- Real-Time 3D Viewport: Industry-standard orbit, pan, and zoom camera controls using Three.js and React Three Fiber.
- Parametric Generation: Modify cross-sections (Polygon, Wave), apply structural transforms (Twist), and layer surface effects (Strip cuts, Low-poly, displacement Voronoi).
- Interactive Spline Editor: Draw and adjust the vase's vertical profile using a 2D canvas editor powered by
react-konva, supporting both Catmull-Rom curves and linear polylines. - Multi-Resolution Rendering: Maintains high frame rates by using low-poly geometry during active interaction (dragging sliders) and auto-refining to high-poly previews upon release.
- Robust Undo/Redo: Action-based temporal state management captures snapshots at meaningful boundaries (e.g., releasing a slider, dropping a control point) without storing heavy derived geometry.
- Template Presets: Quickly start from curated parametric presets (e.g., Pear-Shaped, Twisted Polygon Urn, Low Poly Pot).
| Layer | Technology |
|---|---|
| Framework | Next.js 15 (App Router, strict TypeScript) |
| 3D Rendering | Three.js + React Three Fiber + @react-three/drei |
| UI Components | ShadCN/ui (Radix primitives) + Tailwind CSS v4 |
| State Management | Zustand + zundo (for temporal undo/redo) |
| 2D Editor | react-konva |
| Validation | Zod (parameter schema validation) |
| Testing | Vitest, Testing Library, Playwright, Storybook 8 |
The codebase enforces strict boundaries to keep WebGL performant and logic testable:
- Pure TypeScript Engine (
src/engine/): Contains zero React imports. It handles spline math, base surface revolution, transforms, and surface effects. Geometry is strictly derived via composable pipeline functions. - Isolated State Layers (
src/stores/):
- Model Store: The source of truth containing parametric state (tracked by
zundofor undo/redo). - Geometry Cache: Holds the derived
BufferGeometry. It is treated purely as a cache and is never tracked in undo history. - UI Store: Manages active tools, panels, and modals.
- Schema-Driven UI: The right-hand inspector panel dynamically renders its inputs based on Zod parameter schemas defined in the engine, meaning new features require zero JSX boilerplate.
- Node.js (v22+ recommended)
- Yarn package manager (
npm install -g yarn)
1. Clone the repository
git clone https://github.com/your-username/3d-print-builder.git
cd 3d-print-builder
2. Install dependencies
yarn install
3. Run the development server
yarn dev
Open http://localhost:3000 in your browser. The application will immediately redirect you to the /builder interface.
The project is heavily tested, separating fast pure-function unit tests from complex DOM and E2E WebGL integration tests.
Run unit & component tests (Vitest + Testing Library):
yarn test
Run tests in watch mode:
yarn test:watch
Run End-to-End tests (Playwright):
# Install playwright browsers first if you haven't
npx playwright install --with-deps chromium
yarn test:e2e
yarn dev— Starts the Next.js development server with Turbopack.yarn build— Compiles the application for production.yarn start— Runs the compiled production build.yarn lint— Runs ESLint to check code quality.yarn type-check— Validates TypeScript typings without emitting files.yarn storybook— Boots the Storybook environment (port 6006) for isolated UI component development.