Frontend Template

Reusable Next.js 16 + React 19 frontend starter with a Feature-Sliced-style structure, API layer, local state, and CI quality gates.

What this template includes

• App Router baseline pages:
  • / catalog view
  • /products/[id] detail view
  • /upload upload flow
  • /cart cart flow
  • /orders/[orderId] order status page
• Layered structure:
  • app → routes/layout
  • entities → domain API/models
  • features → user flows (catalog filters, add-to-cart, checkout, upload)
  • widgets → composed UI blocks (navbar, cart view)
  • shared → config/API/provider utilities
• React Query provider for data fetching patterns
• Zustand persisted cart store
• Vitest unit/smoke baseline tests
• CI workflow with lint + tests + typecheck + build

Getting started

1. Install dependencies:

npm ci

2. Configure runtime APIs:

NEXT_PUBLIC_CATALOG_API_URL=http://localhost:8001
NEXT_PUBLIC_ORDER_API_URL=http://localhost:8002

3. Run locally:

npm run dev

4. Open http://localhost:3000.

Reusability Contract

This section defines what is intentionally configurable and what must be replaced when bootstrapping a new domain.

1) Parameterizable surface (keep, configure)

• Runtime API hosts
  • shared/config/env.ts
  • NEXT_PUBLIC_CATALOG_API_URL
  • NEXT_PUBLIC_ORDER_API_URL
• Selectable options used by forms/filters
  • shared/config/constants.ts
  • MATERIALS, PRINT_TYPES, SOURCES, SOURCE_LABELS
• Catalog query params
  • entities/product/api.ts (fetchProducts params: q, source, page, page_size)

2) Required replacements for a new project

Before using this template in production, replace these project-specific parts:

1. Domain API contracts and endpoints

   • entities/product/api.ts
   • entities/order/api.ts
   • Update interfaces, request/response payloads, and endpoint paths to your backend contract.

2. Domain vocabulary and labels

   • shared/config/constants.ts
   • features/* and widgets/* text labels
   • Replace print-oriented terms with your product terminology.

3. Routing model

   • app/products/[id], app/orders/[orderId], app/upload, app/cart
   • Keep the pattern, but adjust route semantics and UX to your business flow.

4. Metadata and branding

   • app/layout.tsx
   • widgets/navbar/ui/Navbar.tsx
   • Update product name, SEO metadata, and navigation labels.

3) Bootstrap checklist for new repo

• Set env vars for API hosts
• Replace API contracts/endpoints in entities/*/api.ts
• Replace constants and domain labels
• Update routing semantics + metadata
• Run full validation:

npm run lint
npm run test
npx tsc --noEmit
npm run build

Quality gates

Local commands:

npm run lint
npm run test
npx tsc --noEmit
npm run build

CI (.forgejo/workflows/ci.yml) runs:

1. ESLint
2. Vitest
3. TypeScript typecheck
4. Production build