Migrating to v4.0

Guide for upgrading from v3.x to v4.0 (alpha).

Overview

Version 4.0 brings significant improvements while maintaining 100% backward compatibility with v3.x. The main changes include:

• Redux Removal: Now uses React's native useSyncExternalStore
• Modern Stripe Features: Phone collection, promotion codes, automatic tax, etc.
• React 19 Support: Full compatibility with React 19
• Client-Only Deprecation: Client-only mode is deprecated (still works, but not recommended)
• Improved TypeScript: Better type inference and exported types
• Smaller Bundle: Reduced bundle size without Redux

Quick Start

Installation

npm install use-shopping-cart@4.0.0-alpha.1

# or
yarn add use-shopping-cart@4.0.0-alpha.1

# or
pnpm add use-shopping-cart@4.0.0-alpha.1

Dependencies

React 19 is now required:

npm install react@19 react-dom@19

Breaking Changes

Client-Only Mode Removed

Breaking: cartMode="client-only" is no longer supported. You must use checkout-session mode with a server endpoint.

All other APIs: 100% backward compatible for checkout-session mode users.

What's New in v4.0

React 19 Support

Full compatibility with React 19, including support for:

• useOptimistic for optimistic cart updates
• useActionState for form-based cart actions
• Concurrent rendering features

Improved Performance

• 40% smaller bundle size
• Faster cart operations
• Better TypeScript support

What's Changed

1. Redux Removal (Internal Change)

Impact: None on your code

What happened:

• Removed Redux as an internal dependency
• Now uses React's native useSyncExternalStore hook
• Uses a custom ShoppingCart class with pub/sub pattern

Benefits:

• Smaller bundle size: ~40% smaller
• Better performance: Fewer re-renders
• Simpler mental model: No Redux concepts to understand
• React 19 compatible: Works with React's latest features

Migration: No action required. This is an internal refactor.

2. Client-Only Mode Removed

Impact: Projects using cartMode="client-only" must migrate

Status: Removed in v4.0

Required: Migrate to checkout-session mode

Migration Example

Before (Client-Only - v3.x):

import { CartProvider } from 'use-shopping-cart'
;<CartProvider
  mode="payment"
  cartMode="client-only"
  stripe={STRIPE_KEY}
  successUrl="https://yoursite.com/success"
  cancelUrl="https://yoursite.com/cancel"
  currency="USD"
>
  <App />
</CartProvider>

After (Checkout-Session - v4.0):

import { CartProvider } from 'use-shopping-cart'
;<CartProvider stripe={STRIPE_KEY} currency="USD">
  <App />
</CartProvider>

Additional Steps Required:

1. Create a server endpoint to generate checkout sessions
2. Move successUrl and cancelUrl to server-side
3. Update product data structure (use id instead of price_id)

See: Getting Started for detailed setup guide.

3. React Version Requirement

Before: React 16.8+

After: React 19+

Migration:

npm install react@19 react-dom@19

Checkout Features

For checkout-session mode, modern Stripe features (phone collection, promotion codes, automatic tax, custom fields, shipping options, etc.) should be configured server-side when creating your checkout session:

// In your server endpoint
const session = await stripe.checkout.sessions.create({
  mode: 'payment',
  line_items,
  success_url: `${origin}/success`,
  cancel_url: origin,

  // Configure Stripe features server-side
  phone_number_collection: { enabled: true },
  allow_promotion_codes: true,
  automatic_tax: { enabled: true },
  shipping_options: [
    {
      shipping_rate_data: {
        display_name: 'Standard Shipping',
        type: 'fixed_amount',
        fixed_amount: { amount: 500, currency: 'usd' }
      }
    }
  ]
})

See: Stripe Checkout Session API for all available options.

TypeScript Improvements

Better Type Exports

import type {
  CartState,
  CartConfig,
  Product,
  CartEntry,
  CartDetails
} from 'use-shopping-cart/core'

Improved Type Inference

const { cartDetails } = useShoppingCart()

// cartDetails is now properly typed
Object.values(cartDetails).forEach((item) => {
  console.log(item.name) // ✓ TypeScript knows all properties
})

Performance Improvements

Reduced Bundle Size

• Before (v3.x): ~45 KB (minified + gzipped)
• After (v4.0): ~27 KB (minified + gzipped)
• Savings: ~40% smaller

Fewer Re-renders

Thanks to React's useSyncExternalStore, components only re-render when the specific cart data they use changes.

API Stability

Unchanged APIs

All existing APIs continue to work:

✅ addItem(product, options?) ✅ incrementItem(id, options?) ✅ decrementItem(id, options?) ✅ setItemQuantity(id, quantity) ✅ removeItem(id) ✅ clearCart() ✅ redirectToCheckout() ✅ All cart properties (cartCount, totalPrice, etc.)

Deprecated (Still Works)

⚠️ cartMode="client-only" - Use checkout-session instead ⚠️ checkoutSingleItem() - Only works with client-only mode

Step-by-Step Migration

Step 1: Update Dependencies

npm install use-shopping-cart@4.0.0-alpha.1 react@19 react-dom@19

Step 2: Test Your Application

Run your application. Everything should work as before.

Step 3: Configure Stripe Features (Server-Side)

If you want modern Stripe checkout features, configure them in your server endpoint:

// pages/api/create-checkout-session.js
const session = await stripe.checkout.sessions.create({
  mode: 'payment',
  line_items,
  success_url: `${origin}/success`,
  cancel_url: origin,

  // Configure features server-side
  phone_number_collection: { enabled: true },
  allow_promotion_codes: true,
  automatic_tax: { enabled: true }
})

Step 4: Migrate from Client-Only (If Applicable)

If using cartMode="client-only", plan migration to checkout-session:

1. Create server endpoint for session creation
2. Update CartProvider configuration
3. Test checkout flow
4. Deploy

See: Getting Started for complete setup guide

Troubleshooting

React Version Errors

Error: "Invalid hook call" or "React version mismatch"

Solution: Ensure React 19 is installed:

npm install react@19 react-dom@19

TypeScript Errors

Error: Type errors after upgrading

Solution: Update @types packages:

npm install -D @types/react@19 @types/react-dom@19

Checkout Not Working

Issue: Checkout redirects not working

Check:

1. cartMode is set correctly
2. For checkout-session: Server endpoint is configured
3. For client-only: successUrl and cancelUrl are set
4. Stripe key is valid

Getting Help

• 📖 Full Documentation
• 💬 Discord Community
• 🐛 GitHub Issues

Summary

No Breaking Changes ✅

• 100% backward compatible
• Existing code works without modifications
• Opt-in to new features when ready

Major Improvements ✨

• 40% smaller bundle size
• Better performance
• React 19 support
• Improved TypeScript
• Simpler architecture

Removed ❌

• Client-only mode (must migrate to checkout-session)
• All client-only mode props (mode, cartMode, successUrl, cancelUrl, billingAddressCollection, allowedCountries)

If you're using checkout-session mode in v3.x, upgrading to v4.0 is seamless. If you're using client-only mode, migration is required but straightforward.