@atomic-solutions/woocommerce-utils

Type-safe WooCommerce Store API client with React Query integration

Status: 🚧 Work in Progress

Features

• ✅ Type-Safe - Full TypeScript support with Zod validation
• ✅ WooCommerce Store API v1 - Designed for headless/mobile apps
• ✅ React Query Integration - Optimized caching and state management
• ✅ Cart Session Management - Automatic nonce/cart-token handling
• ✅ JWT Authentication - Secure user authentication support
• ✅ Error Handling - Built-in error classes with optional error reporter injection
• ✅ Tree-Shakeable - Sub-path exports for minimal bundle size
• ✅ Platform Agnostic - Works in React Native, Next.js, and web

Installation

yarn add @atomic-solutions/woocommerce-utils

Peer Dependencies

yarn add axios @tanstack/react-query zod

Quick Start

1. Create Client

import { createClient } from '@atomic-solutions/woocommerce-utils';

// For React Native
import AsyncStorage from '@react-native-async-storage/async-storage';

const cartHeadersAdapter = {
  get: async () => {
    const nonce = await AsyncStorage.getItem('woo_nonce');
    const cartToken = await AsyncStorage.getItem('woo_cart_token');
    return { nonce, cartToken };
  },
  save: async ({ nonce, cartToken }) => {
    if (nonce) await AsyncStorage.setItem('woo_nonce', nonce);
    if (cartToken) await AsyncStorage.setItem('woo_cart_token', cartToken);
  },
  clear: async () => {
    await AsyncStorage.removeItem('woo_nonce');
    await AsyncStorage.removeItem('woo_cart_token');
  },
};

const client = createClient({
  baseURL: 'https://your-store.com/wp-json',
  cartHeaders: cartHeadersAdapter,
  debug: process.env.DEBUG === 'true',
});

2. Setup Provider

Important: You must provide your own QueryClientProvider from @tanstack/react-query.

import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { WooCommerceProvider } from '@atomic-solutions/woocommerce-utils';

const queryClient = new QueryClient();

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <WooCommerceProvider client={client}>
        <YourApp />
      </WooCommerceProvider>
    </QueryClientProvider>
  );
}

3. Use Hooks

import { useProducts, useAddToCart } from '@atomic-solutions/woocommerce-utils/hooks';

function ProductList() {
  const { data: products, isLoading } = useProducts({
    category: 'electronics',
    per_page: 20,
  });

  const addToCart = useAddToCart();

  if (isLoading) return <Loading />;

  return (
    <FlatList
      data={products}
      renderItem={({ item }) => (
        <ProductCard
          product={item}
          onAddToCart={() =>
            addToCart.mutate({
              id: item.id,
              quantity: 1,
            })
          }
        />
      )}
    />
  );
}

Documentation

Coming soon...

License

MIT © Atomic Solutions