Skip to content

TODO.md

Latest commit

 

History

History
707 lines (596 loc) · 23.8 KB

TODO.md

File metadata and controls

707 lines (596 loc) · 23.8 KB

StoreFuse Development Roadmap

Status: Active Development Last Updated: April 16, 2026

Phase 0: Foundation Setup ✅ COMPLETED

Repository Infrastructure

  • Initialize pnpm workspace
    • Create root package.json
    • Create pnpm-workspace.yaml
    • Create .npmrc configuration
  • Configure Turborepo
    • Create turbo.json
    • Define build pipeline
    • Configure cache settings
  • Setup TypeScript
    • Create root tsconfig.json
    • Create tsconfig.build.json
    • Configure path aliases
  • Development tooling
    • Setup ESLint (.eslintrc.js)
    • Setup Prettier (.prettierrc)
    • Create .gitignore
    • Create .editorconfig

Directory Structure

  • Create apps/ directory
  • Create packages/ directory structure
    • Create packages/core/
    • Create packages/cli/
    • Create packages/adapters/
    • Create packages/modules/
    • Create packages/themes/
    • Create packages/shared/
  • Create docs/ directory
  • Create examples/ directory (optional)

Phase 1: Core Framework (v0.1 Foundation) ✅ COMPLETED

Summary

Phase 1 packages are built and compiling. However a post-phase review found that several systems exist as code but are not yet connected to the running app.

  • ✅ @storefuse/core - Framework core with config, adapter, module system, theme engine
  • ✅ @storefuse/adapter-woo-rest - WooCommerce REST API adapter
  • ✅ @storefuse/module-products - Product listings and pages
  • ✅ @storefuse/module-cart - Cart context and types
  • ✅ @storefuse/theme-core - Default theme with Tailwind v3
  • ✅ @storefuse/theme-child-template - Child theme template for safe overrides
  • ✅ Storefront demo app routes working

Build Status: ✅ All packages build successfully Routes: ✅ Home, Shop, Cart, Product Detail, Category pages working Theme System: ⚠️ Theme engine code exists but is NOT wired to the running app

Known Gaps Found in Review:

  • layout.tsx hard-imports @storefuse/theme-core directly — child theme registry is never consulted
  • storefuse.config.ts theme.child setting is declarative only — does nothing at runtime
  • Module pages registry and actual Next.js app/ routes are two parallel systems — module registry is never used
  • module-products and theme-core both contain duplicate UI components (ProductCard, ProductGrid, etc.) — ownership is unclear
  • CLI init command scaffolds direct theme-core imports — new projects start with the wrong pattern
  • EventBus exists but is not connected to any module lifecycle or rendering pipeline

Package: @storefuse/core ✅ COMPLETED

  • Initialize package
    • Create package.json
    • Create tsconfig.json
    • Setup build configuration
  • Config System
    • Define StoreFuseConfig TypeScript types
    • Implement defineStoreFuseConfig() helper
    • Create config loader with validation
    • Add environment variable support
  • Adapter System
    • Define StoreFuseAdapter interface
    • Create adapter registry
    • Implement adapter loader
    • Add adapter context provider
  • Module System
    • Define StoreFuseModule interface
    • Create module registry (ModuleRegistry class)
    • Implement dependency resolver (with circular detection)
    • Create module loader (ModuleLoader class)
    • Add module hooks system (onInit, onRequest)
    • Export getPage() and getComponent() helpers
  • Theme Engine
    • Define theme component registry interface
    • Implement theme resolver (core + child)
    • Create resolveThemeComponent() function
    • Add theme component loader (ThemeManager class)
  • Cache System
    • Define cache configuration types
    • Implement Next.js fetch cache wrapper
    • Add revalidation helpers
    • Create cache utilities
  • Event System
    • Create event bus
    • Define core events
    • Implement event listeners
  • Shared Types
    • Define Product type
    • Define Category type
    • Define Cart and CartItem types
    • Define SearchResult type
    • Define Post type (blog)
  • Testing
    • Setup Vitest or Jest
    • Write unit tests for config loader
    • Write unit tests for module system
    • Write unit tests for theme resolver

Package: @storefuse/adapter-woo-rest ✅ COMPLETED

  • Initialize package
    • Create package.json
    • Create tsconfig.json
    • Add WooCommerce REST API dependency
  • Implement adapter interface
    • Implement products.list()
    • Implement products.getById()
    • Implement products.getBySlug()
    • Implement categories.list()
    • Implement categories.getBySlug()
    • Implement search.query() (optional)
  • Error handling
    • Add API error handling
    • Add rate limiting support
    • Add retry logic
  • Authentication
    • Implement consumer key/secret auth
    • Add request signing
  • Storefront Integration
    • Create storefuse.config.ts in demo app
    • Add .env.local.example with credentials
    • Create adapter instance singleton
    • Update shop page to fetch real products
    • Display WooCommerce products with images, prices, stock
  • Testing
    • Setup test environment
    • Write integration tests (mock WooCommerce API)
    • Add E2E tests with actual WooCommerce instance

Package: @storefuse/module-products ✅ COMPLETED

  • Initialize package
    • Create package.json
    • Create tsconfig.json
  • Module definition
    • Create module manifest
    • Define dependencies
    • Register pages with module system
    • Add onInit hook
  • Components
    • Create ProductCard component
    • Create ProductList component
    • Create ProductGrid component
    • Create ProductImage component
    • Create Price component
  • Pages (contribution)
    • Define home page loader
    • Define shop page loader
    • Define product detail page loader
    • Define category page loader
  • Data fetching
    • Create product data fetchers
    • Add caching configuration
    • Implement error boundaries
  • Build and Export
    • Build successfully with tsup
    • Export module manifest
    • Export all components and pages
  • Testing
    • Write component tests
    • Write integration tests

Package: @storefuse/theme-core ✅ COMPLETED

  • Initialize package
    • Create package.json
    • Create tsconfig.json
    • Add Tailwind v3 dependency
  • Tailwind Configuration
    • Create globals.css with Tailwind v3
    • Setup traditional Tailwind directives
    • Define design tokens
    • Create global styles
  • Core Components
    • Create Header component
    • Create Footer component
    • Create Navigation component
    • Create Logo component
    • Create ProductCard component
    • Create Button component
    • Create Input component
    • Create Badge component
    • Create Price component
  • Layout Components
    • Create Container component
    • Create Grid component
    • Create Section component
  • Theme Registry
    • Export component registry
    • Document override patterns
  • Storefront Integration
    • Install in storefront app
    • Replace layout Header/Footer with theme components
    • Import theme styles
    • Build and test successfully
  • Build successfully
    • TypeScript compilation
    • Component exports
  • Documentation
    • Create component documentation
    • Add usage examples
    • Document Tailwind customization

Package: @storefuse/theme-child-template ✅ COMPLETED

  • Initialize package
    • Create package.json
    • Create tsconfig.json
    • Setup build configuration (tsup)
  • Child theme structure
    • Create src/index.ts with childThemeRegistry
    • Create src/components/ directory
    • Add example components (Header, ProductCard)
  • Documentation
    • Create comprehensive README
    • Document override pattern
    • Add usage examples
    • Document benefits
  • Storefront Integration
    • Create local theme-child directory in storefront
    • Add example components
    • Update storefuse.config.ts to use child theme
  • Build successfully
    • Fix TypeScript incremental compilation error
    • Generate type definitions
    • Export registry properly

Package: @storefuse/cli ✅ COMPLETED

  • Initialize package
    • Create package.json
    • Create tsconfig.json
    • Setup bin entry point
  • CLI Framework
    • Setup Commander.js
    • Create CLI entry point
    • Add help documentation
  • Command: init
    • Create project scaffolding logic
    • Add template system
    • Implement dependency installation
    • Generate storefuse.config.ts
    • Generate .env.example
    • Print setup instructions
  • Command: add module
    • List available modules
    • Install module package
    • Update config file
    • Install dependencies
  • Command: add theme child
    • Create child theme directory
    • Copy template files
    • Update config
  • Command: doctor
    • Check environment variables
    • Test WooCommerce API connection
    • Verify required packages
    • Check Node.js version
    • Check pnpm version
  • Build successfully
    • TypeScript compilation
    • ESM output
    • Type definitions
  • Testing
    • Write CLI command tests
    • Add E2E tests for scaffolding

App: storefront (Demo App) ✅ COMPLETED (Basic Setup)

  • Initialize Next.js 16 app (using Next.js 15.5.9)
    • Create with App Router
    • Add TypeScript
    • Configure next.config.ts
    • Setup Tailwind v3 (stable, production-ready)
  • Setup StoreFuse
    • Create storefuse.config.ts
    • Install core packages
    • Configure adapter
    • Enable modules
  • Create Routes
    • Create app/layout.tsx
    • Create app/page.tsx (home)
    • Create app/shop/page.tsx
    • Create app/product/[slug]/page.tsx
    • Create app/category/[slug]/page.tsx
    • Create app/cart/page.tsx
  • Environment Setup
    • Create .env.example
    • Document required variables
  • Child Theme Setup
    • Create theme-child directory
    • Add example component overrides
    • Configure in storefuse.config.ts
  • Build Successfully
    • Production build complete
    • Static page generation (137 pages)
    • No TypeScript errors
  • Testing
    • Add Playwright for E2E tests
    • Write basic navigation tests

Completed Interim Work (Originally Planned as Phase 2)

These were completed before the architecture gaps were identified. They are tracked here for reference. Architecture wiring (Phase 2 below) must still be completed.

Package: @storefuse/module-cart ✅ COMPLETED

Status: Fully functional cart implementation with UI

  • Initialize package
  • Basic module structure
  • Cart state management
    • Implement local storage cart
    • Create cart context (CartContext.tsx)
    • Add cart hooks (useCart)
    • Cart operations (add, remove, update, clear)
  • Components
    • Create CartItem component in theme-core
    • Create CartSummary component in theme-core
    • Create AddToCartButton component with feedback
    • Create CartPage with empty state
    • Integrate cart count in Header
  • Cart operations
    • Implement add to cart
    • Implement update quantity
    • Implement remove item
    • Implement clear cart
    • Calculate totals
  • Testing
    • Write cart logic tests
    • Write component tests

Package: @storefuse/module-checkout-redirect ✅ COMPLETED

  • Initialize package
  • Checkout URL generation
    • Generate WooCommerce checkout URL
    • Add cart items to URL
    • Support prefill parameters
  • Components
    • Create CheckoutButton component in theme-core
  • Build successfully
    • TypeScript compilation
    • Type definitions
  • Testing
    • Test URL generation
    • Test redirect flow

Package: @storefuse/module-search

  • Initialize package
  • Search implementation
    • Integrate with WooCommerce search API
    • Create search data fetcher
  • Components
    • Create SearchBar component
    • Create SearchResults component
    • Create SearchFilters component
  • Search page
    • Create search results page
    • Add pagination
  • Testing
    • Write search tests
    • Test filtering

Package: @storefuse/module-seo

  • Initialize package
  • Meta tags
    • Create meta tag generators
    • Add Open Graph support
    • Add Twitter Card support
  • Sitemap
    • Generate dynamic sitemap
    • Add product URLs
    • Add category URLs
  • Structured data
    • Add Product schema
    • Add BreadcrumbList schema
  • Testing
    • Test meta tag generation
    • Validate structured data

Documentation (v0.2 — superseded by Phase 3)

  • Create theme customization guide (docs/themes.md)
  • Write getting started guide
  • Document module system
  • Add deployment guide (Vercel)
  • Create adapter documentation

Phase 2: Architecture Fix — Connect the Dots (v0.2) ✅ COMPLETED

Goal: Make the framework actually work as designed. The code exists. The wiring does not. All original promises (child theme overrides, module-driven routing, config-driven runtime) must become real by the end of this phase.

Step 1: Fix UI Ownership — Remove Duplicate Components from module-products

Rule: Modules own data/logic/contracts. Themes own UI.

  • Delete packages/modules/module-products/src/components/ProductCard.tsx
  • Delete packages/modules/module-products/src/components/ProductGrid.tsx
  • Delete packages/modules/module-products/src/components/ProductImage.tsx
  • Delete packages/modules/module-products/src/components/ProductList.tsx
  • Delete packages/modules/module-products/src/components/Price.tsx
  • Delete packages/modules/module-products/src/components/ directory
  • Update packages/modules/module-products/src/index.ts — remove all component exports
  • Verify packages/themes/theme-core is the single source of truth for all UI components
  • Confirm build passes after deletion

Step 2: Wire the Theme Engine — ThemeProvider + useThemeComponent

Goal: Child theme registry is read at runtime and overrides core components transparently.

  • Create packages/core/src/theme-engine/ThemeProvider.tsx
    • ThemeProvider component — accepts coreRegistry and childRegistry props, merges them (child wins), exposes via React context
    • useThemeComponent(key) hook — returns the resolved component for a given key from context
    • ThemeContext — typed React context holding the merged registry
  • Export ThemeProvider and useThemeComponent from packages/core/src/index.ts
  • Export ThemeProvider and useThemeComponent from packages/core/src/theme-engine/index.ts
  • Add server-side helper getThemeComponent(key, coreRegistry, childRegistry) for use in Server Components
  • Write unit tests for merge logic (child wins, core fallback, missing key throws)

Step 3: Connect ThemeProvider in the Storefront App

Goal: layout.tsx no longer hard-imports from @storefuse/theme-core. All components resolve through the theme engine.

  • Update apps/storefront/app/layout.tsx
    • Import coreThemeRegistry from @storefuse/theme-core
    • Import childThemeRegistry from ../theme-child
    • Wrap app with <ThemeProvider core={coreThemeRegistry} child={childThemeRegistry}>
    • Remove direct import { Header, Footer } from "@storefuse/theme-core"
    • Replace <Header> and <Footer> with components resolved via useThemeComponent
  • Update apps/storefront/app/product/[slug]/ClientProductDetail.tsx
    • Remove direct import { ProductDetailPage } from "@storefuse/theme-core"
    • Resolve ProductDetailPage via theme engine
  • Update apps/storefront/app/category/[slug]/ClientCategoryPage.tsx
    • Remove direct import { CategoryPage } from "@storefuse/theme-core"
    • Resolve CategoryPage via theme engine
  • Test: activate a child theme component (e.g. custom Header) and confirm it renders instead of core Header without touching any core file

Step 4: Make storefuse.config.ts Drive the Runtime

Goal: The config file is the single source of truth — reading theme.child loads the correct child registry automatically.

  • Create packages/core/src/runtime/index.ts — createStoreFuseApp(config) factory
    • Reads config.theme.core and config.theme.child
    • Dynamically imports and returns merged theme registry
    • Returns loaded module list
  • Export createStoreFuseApp from packages/core/src/index.ts
  • Update apps/storefront/app/layout.tsx to call createStoreFuseApp instead of manually importing registries
  • Confirm changing only storefuse.config.ts theme.child is enough to switch child themes

Step 5: Fix CLI — Scaffold the Correct Pattern

Goal: Every project created with storefuse init starts with the correct wiring.

  • Update packages/cli/src/commands/init.ts template for layout.tsx
    • Generated layout.tsx must use ThemeProvider + useThemeComponent — not direct imports
    • Generated layout.tsx must call createStoreFuseApp(config) to load registries
  • Update CLI add theme child command
    • Generated theme-child/index.ts has correct registry export
    • Generated example component uses correct prop types from @storefuse/core
  • Re-test storefuse init my-store end-to-end and confirm child theme override works out of the box

Step 6: Connect Module Page Registry to Next.js Routing

Goal: Module pages definitions become the source of truth. Next.js route files delegate to modules instead of duplicating logic.

  • Decide routing strategy (Option A — Thin shell routes): Keep app/shop/page.tsx etc. but make them thin delegations through the theme engine
  • Update app/shop/page.tsx — server-side data fetch, delegates rendering to ClientShopPage (uses useThemeComponent("ProductGrid"))
  • Update app/product/[slug]/page.tsx — already thin shell to ClientProductDetail (uses useThemeComponent)
  • Update app/category/[slug]/page.tsx — already thin shell to ClientCategoryPage (uses useThemeComponent)
  • Update app/cart/page.tsx — delegates to ClientCartPage (uses useThemeComponent("CartPage"))
  • Confirm adding a new module with a pages entry works without manually creating route files

Step 7: Wire EventBus to Module Lifecycle for Behavior Overrides

Goal: Child themes and modules can hook into business logic events, not just swap UI.

  • Define standard commerce events in packages/core/src/events/index.ts
    • cart:before-add / cart:after-add
    • cart:before-remove / cart:after-remove
    • checkout:before-redirect
    • product:view
    • search:query
  • Fire cart:before-add and cart:after-add inside module-cart CartContext
  • Fire cart:before-remove and cart:after-remove inside module-cart CartContext
  • Fire cart:cleared inside module-cart CartContext
  • Fire checkout:before-redirect inside module-checkout-redirect
  • Expose global storefuseEvents singleton from @storefuse/core
  • Add example in theme-child/index.ts showing how to hook cart:after-add
  • Document behavior override pattern in docs/themes.md

Phase 2 Complete When:

  • Activating a component in theme-child/index.ts causes it to render instead of the core version — with zero changes to core files
  • storefuse.config.ts is the only file that needs to change to switch child themes
  • A new module can register a page and it renders without manually creating an app/ route file
  • A child theme can subscribe to cart:after-add and run custom code
  • storefuse init scaffolds all of the above correctly for new projects

Phase 3: Enhanced Features (v0.3) ⏳ AFTER PHASE 2

Package: @storefuse/adapter-woo-graphql

  • Initialize package
  • Setup WPGraphQL integration
    • Add GraphQL client
    • Create queries
    • Implement adapter interface
  • Implement all adapter methods
  • Add caching strategy
  • Testing
    • Write integration tests

Package: @storefuse/module-blog

  • Initialize package
  • Blog adapter methods
    • Extend adapter interface
    • Implement in REST adapter
    • Implement in GraphQL adapter
  • Components
    • Create PostCard component
    • Create PostList component
    • Create PostContent component
  • Pages
    • Create blog index page
    • Create post detail page
    • Create category/tag pages
  • Testing
    • Write component tests
    • Write integration tests

Package: @storefuse/module-account

  • Initialize package
  • Authentication
    • Add JWT authentication
    • Create auth context
    • Add auth hooks
  • Components
    • Create LoginForm component
    • Create RegisterForm component
    • Create AccountDashboard component
    • Create OrderHistory component
  • Pages
    • Create login page
    • Create register page
    • Create account page
    • Create orders page
  • Testing
    • Write auth tests
    • Write component tests

Package: @storefuse/theme-child-template

Moved to Phase 1 - Already completed! ✅

See Phase 1 section above for completion status.

Phase 4: Polish & Release

Documentation

  • Complete API documentation
  • Add video tutorials
  • Create migration guides
  • Write contribution guidelines
  • Add troubleshooting guide

Developer Experience

  • Add development mode logging
  • Create debug utilities
  • Add TypeScript strict mode
  • Improve error messages
  • Add CLI autocomplete

Testing & Quality

  • Achieve 80%+ test coverage
  • Add E2E test suite
  • Performance testing
  • Accessibility audit
  • Security audit

Examples

  • Create basic store example
  • Create custom theme example
  • Create multi-language example
  • Create headless checkout example

CI/CD

  • Setup GitHub Actions
    • Automated testing
    • Build verification
    • Linting and formatting
  • Setup Changesets
    • Version management
    • Changelog generation
  • Setup automated publishing
    • npm publish workflow
    • GitHub releases

Website & Marketing

  • Create documentation website
  • Setup demo site
  • Create announcement post
  • Social media content
  • Submit to directories

Release v1.0

  • Final testing
  • Security review
  • Performance optimization
  • Documentation review
  • Publish to npm
  • Announce release
  • Create GitHub release

Maintenance & Future

Community

  • Setup Discord server
  • Create GitHub Discussions
  • Define contribution process
  • Setup issue templates
  • Create PR templates

Roadmap Items (Post v1.0)

  • Payment provider modules (Stripe, PayPal)
  • Analytics modules
  • Email marketing integrations
  • Multi-language support
  • Multi-currency support
  • Advanced filtering
  • Product reviews module
  • Wishlist module
  • Compare products module
  • WordPress plugin (optional)

Notes

  • Keep all packages independently versioned
  • Follow semantic versioning strictly
  • Maintain backward compatibility in minor versions
  • Document breaking changes clearly
  • Test with real WooCommerce instances regularly
  • Get community feedback early and often