Clone
Table of Contents
This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
Battl Builder – Next.js Developer Guide
1. Project Overview
This project is the front-end for Battl Builder, a PCPartPicker-style firearm builder.
It is built with:
- Next.js 14 (App Router)
- TypeScript
- TailwindCSS + DaisyUI
- Server & Client Components
- API integration with the Spring Boot backend
2. Folder Structure
/app
/builder
/builds
/category/[categoryId]/[pageId]
layout.tsx
globals.css
/components
/builder
/cards
/nav
/ui
/lib
api.ts
utils.ts
types.ts
/context
BuildContext.tsx
Key Pages
| Page | Purpose |
|---|---|
/builder |
Main rifle builder UI |
/builds |
Social builds feed (placeholder) |
/category/[categoryId]/[pageId] |
Single category product listing |
3. Data Fetching
Loading products for builder UI
Frontend calls:
GET /api/gunbuilder/products?platform=AR-15&partRoles=optic
Backend returns:
- Product details
- Offer data
- Price ranges
- Images
- Part role
- Slug
Mapped into UI-facing structures via:
import { ProductSummary } from "@/lib/types";
4. Category Mapping
The builder UI groups parts by category slug (e.g., "optic").
Categories come from:
- Hardcoded temporary map OR
- API endpoint
/api/part-role-mappings/AR-15/map
Example:
{
partRole: "OPTIC_LPVO",
categorySlug: "optic"
}
5. Build State Management
Stored in:
/context/BuildContext.tsx
Handles:
- Selected parts
- Total price calculation
- Swapping parts
- Clearing build
6. Styling
TailwindCSS utilities
uppercasetracking-widefont-boldtext-primary
DaisyUI components
- Cards
- Buttons
- Badges
- Alerts
- Inputs
7. Running Locally
Install dependencies
npm install
Run Dev Server
npm run dev
Environment Variables
NEXT_PUBLIC_API_BASE_URL=http://localhost:8080
8. Adding New Builder Categories
- Add category slug to the backend (
part_categoriestable) - Add mapping in
part_role_mappings - Add frontend label in:
/lib/categories.ts
9. Adding New Pages
/app/new-page/page.tsx
Use:
export default function Page() {
return <div>My New Page</div>;
}
10. Recommended Improvements (Future)
- SSR caching with
fetch({ next: { revalidate: 60 } }) - Replace hardcoded PART_ROLE → category mappings
- Add OptimizedImage component wrapper
- Client-side build validation (compatibility engine)
11. Deployment
Recommended:
- Vercel (first-class support)
- Cloudflare Pages (optional)
Environment variables must match backend deployment.
12. Summary
This guide should allow a developer to quickly onboard, understand structure, modify categories, extend the builder, and integrate with the backend services powering Battl Builder.