@estori/components

A comprehensive React component library for building AI-powered e-commerce stores.

Installation

npm install @estori/components
# or
yarn add @estori/components
# or
pnpm add @estori/components
# or
bun add @estori/components

Peer Dependencies

Make sure you have React 18+ installed:

npm install react react-dom

Features

• 🎨 UI Components - Button, Input, Sheet, Tooltip (shadcn/radix based)
• 📐 Layout Components - Header, Footer, CartDrawer
• 🖼️ Section Components - Hero, Testimonials, Newsletter, FAQ
• 🛍️ Product Components - ProductGrid, ProductCard, ProductDetail
• 💳 Checkout - Stripe-powered CheckoutForm
• 🔍 Search - Meilisearch-powered SearchBar & Filters
• 📊 Analytics - PostHog A/B testing & feature flags
• 🛒 Cart - Full cart state management
• ✏️ Editor - Inline editing primitives for visual editors
• 🤖 Runtime - Render StoreSpec JSON to React components

Quick Start

import { 
  Hero, 
  ProductGrid, 
  CartProvider, 
  AnalyticsProvider 
} from '@estori/components';

function App() {
  return (
    <AnalyticsProvider apiKey="your-posthog-key">
      <CartProvider>
        <Hero
          headline="Welcome to Our Store"
          subheadline="Discover amazing products"
          ctaText="Shop Now"
          ctaLink="/products"
        />
        <ProductGrid products={products} columns={4} />
      </CartProvider>
    </AnalyticsProvider>
  );
}

Tailwind CSS Setup

This library uses Tailwind CSS. Add the component paths to your tailwind.config.js:

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    './src/**/*.{js,ts,jsx,tsx}',
    // Include the component library
    './node_modules/@estori/components/dist/**/*.{js,mjs}',
  ],
  theme: {
    extend: {
      colors: {
        brand: {
          primary: 'var(--brand-primary, #000000)',
          secondary: 'var(--brand-secondary, #666666)',
          accent: 'var(--brand-accent, #0066FF)',
          background: 'var(--brand-background, #FFFFFF)',
          text: 'var(--brand-text, #000000)',
        },
      },
    },
  },
  plugins: [],
};

Providers

Cart Provider

import { CartProvider, useCart } from '@estori/components';

function App() {
  return (
    <CartProvider>
      <YourApp />
    </CartProvider>
  );
}

function ProductPage() {
  const { addItem, items, total } = useCart();
  // ...
}

Analytics Provider (PostHog)

import { AnalyticsProvider, useAnalytics } from '@estori/components';

function App() {
  return (
    <AnalyticsProvider 
      apiKey="phc_xxx" 
      host="https://us.posthog.com"
    >
      <YourApp />
    </AnalyticsProvider>
  );
}

function ProductPage() {
  const { trackProductViewed } = useAnalytics();
  // ...
}

Stripe Provider

import { StripeProvider, CheckoutForm } from '@estori/components';

function Checkout() {
  return (
    <StripeProvider publishableKey="pk_xxx">
      <CheckoutForm 
        onSuccess={(order) => console.log('Order:', order)}
        onError={(error) => console.error(error)}
      />
    </StripeProvider>
  );
}

Search Provider (Meilisearch)

import { SearchProvider, SearchBar, SearchFilters } from '@estori/components';

function SearchPage() {
  return (
    <SearchProvider 
      host="https://your-meilisearch.com" 
      apiKey="xxx"
      indexName="products"
    >
      <SearchBar placeholder="Search products..." />
      <SearchFilters />
    </SearchProvider>
  );
}

Runtime Rendering

Render a complete store from a StoreSpec JSON:

import { StoreRenderer, validateStoreSpec } from '@estori/components';

function App({ storeSpec }) {
  const validation = validateStoreSpec(storeSpec);
  
  if (!validation.success) {
    console.error('Invalid spec:', validation.errors);
    return null;
  }

  return <StoreRenderer spec={storeSpec} />;
}

Component Categories

UI Components

• Button - Customizable button with variants
• Input - Form input with validation states
• Sheet - Slide-out drawer/panel
• Tooltip - Hover tooltips

Layout Components

• Header - Navigation header with cart
• Footer - Site footer with links
• CartDrawer - Slide-out cart panel

Section Components

• Hero - Hero banner with CTA
• Testimonials - Customer testimonials
• Newsletter - Email signup form
• FAQ - Accordion FAQ section

Product Components

• ProductCard - Product preview card
• ProductGrid - Grid of product cards
• ProductDetail - Full product page

Editor Components

• EditableText - Inline text editing
• EditableImage - Image picker/editor
• EditableButton - Button with editable props
• EditorSection - Section wrapper with controls

Types

All TypeScript types are exported:

import type { 
  Product, 
  Cart, 
  StoreSpec, 
  Theme,
  PageSpec 
} from '@estori/components';

Development

Running the Demo

To see all components in action locally:

# Demo using source files (hot reload)
bun run demo
# Opens http://localhost:3333

Validating the Built Package

Before publishing to npm, validate that the built package works correctly:

# Build and run demo using dist/ (what npm consumers get)
bun run validate
# Opens http://localhost:3334

This ensures that:

• All Tailwind classes are included in the build
• Components render correctly when imported from dist/
• No styles are missing after the build process

Available Scripts

| Script | Description | |--------|-------------| | bun run dev | Watch mode for development | | bun run build | Build the package | | bun run demo | Run demo with source files (port 3333) | | bun run demo:dist | Build + run demo with dist files (port 3334) | | bun run validate | Alias for demo:dist - validate before publishing | | bun run typecheck | Run TypeScript type checking | | bun run clean | Remove dist folder |

Troubleshooting

Styles not appearing in consuming project

If components appear unstyled when using the package, make sure your Tailwind config includes the component library:

// tailwind.config.js
module.exports = {
  content: [
    './src/**/*.{js,ts,jsx,tsx}',
    // ⚠️ IMPORTANT: Include @estori/components
    './node_modules/@estori/components/dist/**/*.{js,mjs}',
  ],
  // ...
};

CSS Variables

Components use CSS variables for theming. Add these to your global CSS:

:root {
  --brand-primary: #0f172a;
  --brand-secondary: #475569;
  --brand-accent: #3b82f6;
  --brand-background: #ffffff;
  --brand-text: #0f172a;
}

License

MIT