v3.0.0

Release Notes: Bagisto Headless Commerce v3

This document outlines the key changes and improvements in Bagisto Headless v3 compared to the v2 codebase.

🚀 Core Technology Upgrades

Package	v2 Version	v3 Version
Next.js	v15.3.x	v16.0.10
React	v18.3.x	v19.2.0
TypeScript	v5.6.x	v5.x

🏗 Architectural Overhaul

1. src Directory Structure

The codebase has moved to a standard src/ directory structure to better organize application code and separate it from configuration files.

• Old: app/, components/, lib/ in root.
• New: src/app/, src/components/, src/lib/, src/graphql/.

2. Domain-Driven GraphQL Organization

GraphQL operations have been restructured from a monolithic library to a modular, domain-driven design.

• v2: lib/bagisto/queries, lib/bagisto/mutations
• v3: src/graphql/ with dedicated modules:
  • cart/
  • catalog/
  • checkout/
  • customer/
  • theme/

3. Data Fetching Strategy

• Apollo Client: Introduced @apollo/client (src/lib/apollo-client.ts) for robust state management and caching, replacing/augmenting the previous graphql-request pure fetch implementation.

⚡ Performance & Caching Enhancements

Static Generation (SG) & Incremental Static Regeneration (ISR)

• Static Generation: Implemented static generation for key pages to improve initial load performance and SEO.
• ISR Support: Added Incremental Static Regeneration capabilities, allowing pages to be updated after deployment without full rebuilds.

Cache Component

• New Component: Introduced a dedicated CacheComponent for fine-grained control over component-level caching strategies.
• Benefits: Enables selective caching of expensive operations while maintaining dynamic content freshness.

Enhanced Cache Revalidation Logic

• Smart Revalidation: Implemented intelligent cache revalidation strategies that balance performance with data freshness.
• Time-Based & On-Demand: Support for both time-based revalidation intervals and on-demand cache purging.
• Optimized Patterns: Improved revalidation patterns for catalog, cart, and checkout data to minimize unnecessary API calls.

🛠 Developer Experience & Configuration

Configuration Files

• Type-Safe Next Config: Migrated from next.config.js to next.config.ts.
• Modern Configs: eslint.config.mjs and postcss.config.mjs now use ES modules.

Component & Provider Structure

• Providers: Global providers have been moved to src/providers/ for a cleaner entry point in layout.tsx.
• Components: Organized within src/components/.

📦 Key Dependency Changes

• Added: @apollo/client
• Removed: graphql-request (deprecated in favor of Apollo/Fetch)
• Updated:
  • tailwindcss (v4)
  • framer-motion (v12)
  • @heroui/* packages updated to latest versions.

⚠️ Breaking Changes / Migration Notes

• App Router: Ensure all new routes are added to src/app.
• Imports: Update import paths to reference @/src/... or relative paths correctly, as the root has changed.
• Fetch Logic: Review data fetching logic to utilize the new Apollo Client hooks or the updated graphql-fetch.ts utility.