CROP
ProjectsCROP Frontend

CROP Frontend Roadmap

Phase 1: Core Foundation - x Next.js 16 setup with App Router - x TypeScript strict mode - x Tailwind CSS v4 - x Biome linting/formatting - x Parts catalog...

CROP Frontend Roadmap

Completed Phases

Phase 1: Core Foundation

  • Next.js 16 setup with App Router
  • TypeScript strict mode
  • Tailwind CSS v4
  • Biome linting/formatting
  • Parts catalog with search
  • Product detail pages
  • Equipment fitment display

Phase 2: SEO & Accessibility

  • Lighthouse audit fixes
  • JSON-LD structured data
  • Custom 404 page
  • Recent searches persistence
  • WCAG AA compliance
  • Meta descriptions
  • robots.txt configuration

Phase 3: Shopping Cart (MVP)

  • Zustand cart store with localStorage persistence
  • Add to cart from product pages
  • Cart page with item management
  • Header cart badge with hydration safety
  • Quantity selector
  • Remove item / clear cart

Phase 3 Extensions (Future)

Checkout Flow

  • Checkout page with address form
  • Payment integration (Stripe/Square)
  • Order confirmation page
  • Email notifications

User Account

  • Account dashboard (/account)
  • Order history (/orders)
  • Address management
  • Saved payment methods

Cart Enhancements

  • Wishlist / saved items
  • Quote request workflow
  • Stock notification system
  • Cart sync across devices (requires backend)
  • Guest checkout

Phase 4: Performance (Completed)

Bundle Optimization

  • Bundle analysis (bun run analyze) - largest chunk: 520KB
  • Remove unused recharts library (-330KB potential)
  • Remove unused chart.tsx component
  • Tree shaking verification (lucide-react optimized)
  • MongoDB type-only imports verified (no runtime)
  • Dynamic imports for heavy components (Clerk blocked - needs provider at root)

Image Optimization

  • Next.js Image quality config (75, 90 supported)
  • AVIF/WebP formats enabled
  • Home page grid images - added responsive sizes
  • Hero section images - priority + sizes verified
  • 360° viewer images - sizes attribute verified
  • Placeholder blur images (future)

Core Web Vitals

  • LCP optimization
  • FID/INP improvements
  • CLS reduction
  • TTFB analysis

Caching Strategy

  • Autocomplete API caching (max-age=30, stale-while-revalidate=60)
  • Equipment API caching (s-maxage=300, stale-while-revalidate=600)
  • Categories API caching (s-maxage=3600, stale-while-revalidate=7200)
  • Static generation where possible
  • Service worker optimization

Results

  • Largest chunk: 520KB → 376KB (-27% reduction)
  • Removed ~330KB of unused recharts library

Known Blockers & Upstream Issues

1. Next.js cacheComponents + Clerk Incompatibility

FieldValue
Issuevercel/next.js#85490
StatusOpen - waiting for Clerk update
Fix PRclerk/javascript#7119
WorkaroundcacheComponents disabled in next.config.ts:19-22
ImpactRSC caching disabled, slightly slower page loads
ActionRe-enable after Clerk releases Next.js 16 compatibility update

2. Clerk Dynamic Import (Not a Bug)

FieldValue
StatusArchitectural constraint - not fixable
ReasonClerkProvider must wrap entire app for auth context
Impact~376KB Clerk SDK in initial bundle
NoteSame limitation applies to NextAuth, Auth0, etc.

How to Check for Updates

# Check Clerk version
bun list @clerk/nextjs

# Check for updates
bun update @clerk/nextjs

# After updating, try re-enabling in next.config.ts:
# cacheComponents: true

Phase 5: Testing & Quality (90% Complete)

Unit Tests (Vitest)

  • Cart store tests (25 tests) - lib/stores/cart-store.test.ts
  • Search service client tests (9 tests)
  • Search service adapters tests (57 tests)
  • View model tests (8 tests)
  • Query classifier tests (4 tests)
  • Suggestion helpers tests (5 tests)
  • Inline completion tests (4 tests)
  • Manufacturer config tests (2 tests)
  • usePartImage hook tests (4 tests)
  • fetchPartById tests (5 tests)
  • Checkout action tests (21 tests) - app/actions/checkout.test.ts
  • Parts slug utilities tests (14 tests) - app/parts/[id]/utils.test.ts
  • Component tests with Testing Library

Total: 158 unit tests passing

E2E Tests (Playwright)

  • Playwright setup with chromium
  • Search autocomplete tests (5 tests)
  • Search filters tests (5 tests)
  • Cart flow tests (9 tests) - tests/e2e/cart-flow.spec.ts
  • Admin API tests (exists)
  • Mobile responsiveness tests

Test Infrastructure

  • Vitest config with happy-dom environment
  • localStorage mock for zustand persist middleware
  • server-only mock for SSR components
  • Path aliases resolution (@/)

Visual Regression

  • Storybook component library (setup exists)
  • Chromatic integration

Architecture Plan Status (Amazon-style Store)

1. Frontend Routes (Next.js)

RouteDescriptionStatusNotes
/Home / promo✅ Doneapp/home/page.tsx
/partsCatalog with filters & search✅ Doneapp/parts/(catalog)/page.tsx
/parts?q=...Search results✅ DoneQuery params handled
/parts/[id]Product detail by ID✅ Doneapp/parts/[id]/page.tsx
/parts/[sku]Product by SKU⚠️ PartialUses [id] route, SKU lookup in place
/parts/[slug]SEO-friendly URL✅ DoneRedirects to canonical SKU
/parts/cartShopping cart✅ Doneapp/parts/cart/page.tsx
/checkout/*Checkout flow⚠️ PartialSuccess/cancel pages exist
/sign-in, /sign-upAuth✅ DoneClerk integration
Header searchSearch in header✅ Donefeatures/search-bar/

2. Domain Plan

DomainPurposeStatusNotes
crop-dev.appFrontend (Vercel)✅ DoneCloudflare proxied
api-dev.crop-dev.appAPI Gateway⚠️ PartialSearch service exists
Admin domainSeparate admin app🔜 Out of scopeNot in this repo

3. Backend Chain: Cloudflare → API Gateway → Cloud Run

ComponentStatusNotes
Cloudflare DNS/proxy✅ DoneTLS, WAF enabled
Cloudflare caching✅ DoneCache headers set
GCP API Gateway✅ Donecrop-gateway-2u6j9u5d.ue.gateway.dev
Cloud Run services⚠️ PartialSearch + Payment deployed
Hono microservices🔜 PendingCart service planned

4. API Endpoints

EndpointTypeStatusNotes
GET /public/partsPublic✅ DoneVia search-service
GET /public/parts/sku/{sku}Public✅ DonefetchPartById
GET /public/parts/slug/{slug}Public❌ Not donePlanned
GET /customer/cartAuth⚠️ Client Readylib/cart-service/client.ts
PUT /customer/cart/syncAuth⚠️ Client Readyapp/actions/cart.ts
DELETE /customer/cart/items/{id}Auth⚠️ PartialLocal only
GET /customer/ordersAuth❌ Not donePlanned
POST /customer/checkoutAuth⚠️ PartialStripe intent exists

5. Authentication (Clerk)

ItemStatusNotes
ClerkProvider in layout✅ Doneapp/layout.tsx
Sign-in/Sign-up pages✅ Doneapp/sign-in/, app/sign-up/
JWT template for API✅ Donegcp-api template configured
getToken() for backend calls✅ DoneAll API clients updated
API Gateway JWT validation⚠️ DocumentedSee docs/GCP_API_GATEWAY_PLAN.md
Hono authenticateRequest()❌ Not donePhase 1 of auth plan

6. Summary

CategoryProgress
Frontend Routes90%
Search & Catalog95%
Shopping Cart (local)100%
Cart Backend Sync30%
Checkout Flow30%
Auth Integration70%
API Gateway40%
Cloud Run Services30%

Next Steps (Prioritized)

PriorityTaskPhaseComplexityStatus
1Component tests with Testing LibraryPhase 5MediumPending
2Mobile responsiveness E2E testsPhase 5MediumPending
3Checkout page with address formPhase 3 ExtHighPending
4Payment integration (Stripe)Phase 3 ExtHighPending
5Core Web Vitals optimizationPhase 4MediumPending
6Filters persistence in URLPhase 6LowPending
7/parts/[slug] SEO routeArchitectureLow✅ Done
8Cart backend sync (Cloud Run)ArchitectureHigh⚠️ Client Ready
9GCP API Gateway OpenAPI specArchitectureMedium✅ Deployed
10Clerk JWT template for GCPArchitectureLow✅ Done

Phase 6: Advanced Features

Search Enhancements

  • Filters persistence in URL
  • Search analytics
  • Autocomplete improvements
  • Category navigation

Product Features

  • Related products
  • Recently viewed
  • Compare products
  • Product reviews

Admin Features

  • Inventory management
  • Order management
  • Analytics dashboard

Environment Configuration

Quick Start for New Developers

Parts search bar UX notes

Overview The widget (see ) powers every catalog page. It is composed of three interactive zones:

On this page

CROP Frontend RoadmapCompleted PhasesPhase 1: Core FoundationPhase 2: SEO & AccessibilityPhase 3: Shopping Cart (MVP)Phase 3 Extensions (Future)Checkout FlowUser AccountCart EnhancementsPhase 4: Performance (Completed)Bundle OptimizationImage OptimizationCore Web VitalsCaching StrategyResultsKnown Blockers & Upstream Issues1. Next.js cacheComponents + Clerk Incompatibility2. Clerk Dynamic Import (Not a Bug)How to Check for UpdatesPhase 5: Testing & Quality (90% Complete)Unit Tests (Vitest)E2E Tests (Playwright)Test InfrastructureVisual RegressionArchitecture Plan Status (Amazon-style Store)1. Frontend Routes (Next.js)2. Domain Plan3. Backend Chain: Cloudflare → API Gateway → Cloud Run4. API Endpoints5. Authentication (Clerk)6. SummaryNext Steps (Prioritized)Phase 6: Advanced FeaturesSearch EnhancementsProduct FeaturesAdmin Features