hi-pharmacist-ecommerce

v1.0.10

Published

2 days ago

Production-ready, multi-tenant e‑commerce UI + API adapter for Next.js with auth, carts, checkout, orders, theming, and pharmacist-focused UX.

0High
0Medium
0Low

botros123

ecommerce nextjs multi-tenant react tailwindcss stripe pharmacy online-store

Hey Pharmacist E‑commerce

Production‑ready, multi‑tenant e‑commerce UI + API adapter for Next.js. It ships with end‑to‑end flows (browse, cart, checkout, orders), robust authentication, typed SDKs, and a polished pharmacist‑grade UX. Drop it into a Next.js app, point it at your API, and ship a beautiful store in hours—not weeks.

Highlights

🛒 Complete flows: Shop, product details, wishlist, cart, checkout, orders (history + current)
🔐 Auth built‑in: Sign up/in, profile, token persistence, background rehydration
💳 Payments: Card/Cash/Credit modes; Stripe‑ready checkout handoff
🧩 Typed API adapters: Generated axios SDK under src/lib/Apis with bearer + store key headers
🎨 Themeable: Brand colors + configurable header gradient via EcommerceConfig
🧠 Smart UX: Skeletons, optimistic UI, searchable overflow filters, and mobile‑first layouts
🧱 Composable: Use our screens, or import atomic components and hooks
⚡ Production‑grade: Tree‑shakable build, types, sourcemaps, React 18, Next 14

Installation

npm install hi-pharmacist-ecommerce react-hook-form @hookform/resolvers

Step-by-Step Integration Guide

1) Install Dependencies

Install the library and its peer dependencies:

npm install hi-pharmacist-ecommerce react-hook-form @hookform/resolvers
# or
yarn add hi-pharmacist-ecommerce react-hook-form @hookform/resolvers

2) Configure CSS and Tailwind

To ensure styles apply correctly, you must update your global CSS and Tailwind config.

A. Update index.css / globals.css Import the library's global styles and map your local variables to the library's namespaced variables.

@import "tailwindcss";
/* Import library styles to get base theme definitions */
@import "hi-pharmacist-ecommerce/styles/globals.css";

/* ... existing source directives ... */

/* Map local variables to library variables if needed */
:root {
  /* ... existing vars ... */
  --primary: var(--hp-primary, #030213);
  --secondary: var(--hp-secondary, #2b4b7c);
  --accent: var(--hp-accent, #e67e50);
}

B. Update Tailwind Config Ensure Tailwind scans the library's components for class names.

If using Tailwind v4 (CSS-only config):

@source "./node_modules/hi-pharmacist-ecommerce/**/*.{js,ts,jsx,tsx,mdx}";

If using tailwind.config.js:

module.exports = {
  content: [
    // ... existing paths
    "./node_modules/hi-pharmacist-ecommerce/**/*.{js,ts,jsx,tsx,mdx}",
  ],
  // ...
}

3) Create Store Configuration

Create a config file for your store (e.g., lib/ecommerce-config.ts):

import { EcommerceConfig } from 'hi-pharmacist-ecommerce';

export const ecommerceConfig: EcommerceConfig = {
  storeId: "your-store-id",
  storeName: "Your Store Name",
  logo: "/path/to/logo.png",
  colors: {
    primary: "#3B82F6",
    primaryDark: "#1E40AF",
    secondary: "#1E40AF",
    accent: "#F59E0B",
    accentDark: "#D97706",
    textMuted: "#6B7280"
  },
  apiBaseUrl: "https://your-api.com",
};

4) Wrap your App with Provider

Wrap your application root with EcommerceProvider. This handles state, auth, and theme injection.

// app/layout.tsx
import { EcommerceProvider } from 'hi-pharmacist-ecommerce';
import { ecommerceConfig } from '@/lib/ecommerce-config';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <EcommerceProvider
            config={ecommerceConfig}
            basePath="/shop" {/* Optional: if shop is under a subpath */}
            withToaster={true} {/* Optional: enables global toast notifications */}
        >
          {children}
        </EcommerceProvider>
      </body>
    </html>
  );
}

3) Use the screens

// app/shop/page.tsx
import { ShopScreen } from 'hi-pharmacist-ecommerce';

export default function ShopPage() {
  return <ShopScreen />;
}

Available screens

<ShopScreen /> - Product listing with filters
<ProductDetailScreen /> - Individual product page
<CartScreen /> - Shopping cart
<CheckoutScreen /> - Checkout flow
<LoginScreen /> - User login
<RegisterScreen /> - User registration
<ProfileScreen /> - User profile
<OrdersScreen /> - Order history
<CurrentOrdersScreen /> - Active orders

Theming and customization

The package exposes CSS variables for theme colors and a dynamic header gradient. Update via EcommerceConfig:

Under the hood, ThemeProvider sets --color-<brand>-<shade> and:

from: rgb(var(--header-from));
via:  rgb(var(--header-via));
to:   rgb(var(--header-to));

Update colors/gradient at runtime and the UI updates automatically.

Using individual components

You can import components like Header, Footer, ProductCard, OrderCard, and UI primitives (Button, Input, Modal, etc.) for bespoke pages.

Requirements

React 18+
Next.js 14+
react-hook-form 7+

Architecture

Screens (page‑level flows) under src/screens
Providers for Auth, Cart, Wishlist, Theme under src/providers
Hooks for products, orders, wishlist, addresses under src/hooks
Generated API SDK under src/lib/Apis (axios + typed models)
API adapter bridge under src/lib/api-adapter

Auth persists access token using localStorage and rehydrates on load. Requests attach x-store-key and Authorization: Bearer automatically.

Local development & testing

Testing locally before publishing

You can test the package locally in your frontend project using npm link:

Step 1: Build and Link the Package

In this package directory:

# Build the package
npm run build

# Create a global symlink
npm link

For active development with auto-rebuild:

# Watch mode - rebuilds on file changes
npm run build:watch

Step 2: Link in Your Frontend Project

In your frontend project directory:

# Link to the local package
npm link hi-pharmacist-ecommerce

# Install peer dependencies if not already installed
npm install react react-dom next react-hook-form @hookform/resolvers

Step 3: Use the Package

Now you can use the package in your frontend as if it were installed from npm:

// app/ecommerce.config.ts
import { EcommerceConfig } from 'hi-pharmacist-ecommerce';

export const config: EcommerceConfig = {
  storeId: '68e3b34ca07948e882f9418f',
  storeName: 'Briarmill Pharmacy',
  logo: '/logo.png',
  colors: {
    primary: '#EF821F',
    secondary: '#8B5CF6',
    accent: '#10B981',
  },
  apiBaseUrl: 'https://api.heypharmacist.com',
};

// app/layout.tsx
import { EcommerceProvider } from 'hi-pharmacist-ecommerce';
import { config } from './ecommerce.config';

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <EcommerceProvider config={config}>
          {children}
        </EcommerceProvider>
      </body>
    </html>
  );
}

Step 4: Test Your Changes

Make changes to the package source code, and:

If using npm run build:watch, changes rebuild automatically
If not, run npm run build after each change
Refresh your frontend to see the changes

Step 5: Unlink When Done

When you're ready to use the published version:

# In your frontend project
npm unlink hi-pharmacist-ecommerce
npm install hi-pharmacist-ecommerce@latest

Publishing to npm

When everything works as expected:

# Update version (will auto-build before publish)
npm version patch  # or minor, or major

# Publish to npm
npm publish

Troubleshooting

Types not emitted: ensure tsup dts is enabled and tsconfig does not use incremental for dts build.
401 after refresh: confirm AuthProvider calls setAuthToken on login/register and that initializeApiAdapter runs at app boot.
Filters not working server‑side: pass orderStatus and paymentStatus to useOrders to forward to getAllOrders.

License

MIT