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

``bash
npm install hey-pharmacist-ecommerce react-hook-form @hookform/resolvers
`

Step-by-Step Integration Guide

$3

Install the library and its peer dependencies:

`bash
npm install hey-pharmacist-ecommerce react-hook-form @hookform/resolvers


or


yarn add hey-pharmacist-ecommerce react-hook-form @hookform/resolvers
`

$3

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.

`css
@import "tailwindcss";
/ Import library styles to get base theme definitions /
@import "hey-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):
`css
@source "./node_modules/hey-pharmacist-ecommerce/*/.{js,ts,jsx,tsx,mdx}";
`

If using tailwind.config.js:
`javascript
module.exports = {
content: [
// ... existing paths
"./node_modules/hey-pharmacist-ecommerce/*/.{js,ts,jsx,tsx,mdx}",
],
// ...
}
`

$3

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

`typescript
import { EcommerceConfig } from 'hey-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",
};
`

$3

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

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

export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (


config={ecommerceConfig}
basePath="/shop" {/ Optional: if shop is under a subpath /}
withToaster={true} {/ Optional: enables global toast notifications /}
>
{children}



);
}
`

$3

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

export default function ShopPage() {
return ;
}
`

Available screens

- - Product listing with filters
- - Individual product page
- - Shopping cart
- - Checkout flow
- - User login
- - User registration
- - User profile
- - Order history
- - 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-- and:

`css
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.

$3


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

$3

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

#### Step 1: Build and Link the Package

In this package directory:

`bash


Build the package

npm run build

Create a global symlink

npm link
`

For active development with auto-rebuild:

`bash


Watch mode - rebuilds on file changes


npm run build:watch
`

#### Step 2: Link in Your Frontend Project

In your frontend project directory:

`bash


Link to the local package

npm link hey-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:

`typescript
// app/ecommerce.config.ts
import { EcommerceConfig } from 'hey-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',
};
`

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

export default function RootLayout({ children }) {
return (



{children}



);
}
`

#### 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:

`bash


In your frontend project


npm unlink hey-pharmacist-ecommerce
npm install hey-pharmacist-ecommerce@latest
`

$3

When everything works as expected:

`bash


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