StoreCraft Framework

A powerful Next.js framework for building Shopify headless stores with WordPress-like theme management.

Features

• 🛍️ Complete Shopify Integration: Products, collections, cart, customer accounts
• 🎨 Powerful Theme System: Easy theme switching and customization without touching core code
• 📱 PWA Ready: Progressive Web App capabilities out of the box
• ⚡ Next.js 15: Built on the latest Next.js with App Router
• 🔧 TypeScript: Full TypeScript support
• 💳 Shopify Checkout: Seamless checkout integration
• 🔒 Core Protection: Users can't modify framework core, only extend via themes

Quick Start

npx create-storecraft-app my-store
cd my-store
cp .env.example .env.local
# Add your Shopify credentials to .env.local
npm install
npm run dev

How It Works

This framework uses a theme-first routing system where:

1. Theme files take priority: If a page exists in your active theme, it will be used
2. Core fallback: If no theme file exists, the framework uses the core implementation
3. No core modification: You cannot modify core files, only override them via themes
4. Dynamic theme switching: Switch themes without restarting the application

Architecture

your-project/
├── themes/                    # 👤 User themes (customizable)
│   ├── default/
│   │   ├── pages/            # Custom page overrides
│   │   ├── components/       # Custom components
│   │   └── styles/           # Custom styles
│   └── my-custom-theme/
│       └── ...
├── node_modules/
│   └── storecraft-framework/
│       └── core/             # 🔒 Framework core (protected)
│           ├── app/          # Core Next.js pages
│           ├── components/   # Core components
│           ├── lib/          # Core utilities
│           └── hooks/        # Core hooks
└── theme.config.json         # Theme configuration

Theme System

Creating a Theme

# Create a new theme directory
mkdir themes/my-theme

# Create theme structure
mkdir themes/my-theme/{pages,components,styles,assets}

# Switch to your theme
npm run theme:switch my-theme

Overriding Core Pages

Create any file in your theme to override the core implementation:

// themes/my-theme/pages/index.tsx
export default function HomePage() {
  return (
    <div>
      <h1>My Custom Homepage</h1>
      {/* Your custom implementation */}
    </div>
  );
}

Available Core Routes to Override

• pages/index.tsx - Homepage
• pages/products/[handle].tsx - Product pages
• pages/collections/[handle].tsx - Collection pages
• pages/cart.tsx - Cart page
• pages/search.tsx - Search page
• pages/account/ - Account pages
• pages/login.tsx - Login page
• And more...

Using Core Components in Themes

// Import core components in your theme files
import { ProductGrid } from 'shopify-headless-framework/core/components/product/ProductGrid';
import { Header } from 'shopify-headless-framework/core/components/layout/Header';

export default function MyCustomPage() {
  return (
    <div>
      <Header />
      <ProductGrid products={products} />
    </div>
  );
}

Core Framework Features

The framework core provides:

Components

• Product Components: ProductCard, ProductGrid, ProductForm, ProductGallery
• Cart Components: CartDrawer, CartLineItem, CartSummary
• Layout Components: Header, Footer, Breadcrumbs
• UI Components: Button, Input
• SEO Components: JsonLd

Hooks

• useAuth: Customer authentication management
• useCart: Shopping cart state management

Stores (Zustand)

• authStore: Global authentication state
• cartStore: Global cart state

Shopify Integration

• Complete Storefront API: Products, collections, cart, customers
• GraphQL Client: Optimized queries and mutations
• Error Handling: Retry logic and rate limiting
• TypeScript Types: Full type definitions

Environment Variables

# Required: Shopify Store Configuration
NEXT_PUBLIC_SHOPIFY_STORE_DOMAIN=your-store.myshopify.com
NEXT_PUBLIC_SHOPIFY_STOREFRONT_ACCESS_TOKEN=your-storefront-access-token

# Optional: Custom domain
NEXT_PUBLIC_SITE_URL=https://your-domain.com

Theme Commands

# Switch active theme
npm run theme:switch theme-name

# List available themes
ls themes/

# Create new theme (manual)
mkdir themes/new-theme
mkdir themes/new-theme/{pages,components,styles,assets}

Development

Framework Development

# Clone the framework
git clone <framework-repo>
cd shopify-headless-framework

# Install dependencies
npm install

# Build the framework
npm run build

# Link for local development
npm link

Using Local Framework

# In your project
npm link shopify-headless-framework

Contributing

1. Fork the repository
2. Create your feature branch
3. Make changes to core framework only
4. Add tests
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

• Documentation
• GitHub Issues
• Discord Community