# 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 hi-pharmacist-ecommerce react-hook-form @hookform/resolvers ``` ## Step-by-Step Integration Guide ### 1) Install Dependencies Install the library and its peer dependencies: ```bash 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. ```css @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): ```css @source "./node_modules/hi-pharmacist-ecommerce/**/*.{js,ts,jsx,tsx,mdx}"; ``` If using `tailwind.config.js`: ```javascript 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`): ```typescript 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. ```tsx // app/layout.tsx import { EcommerceProvider } from 'hi-pharmacist-ecommerce'; import { ecommerceConfig } from '@/lib/ecommerce-config'; export default function RootLayout({ children, }: { children: React.ReactNode; }) { return ( {children} ); } ``` ### 3) Use the screens ```tsx // app/shop/page.tsx import { ShopScreen } from 'hi-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. ### 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: ```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 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: ```typescript // 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', }; ``` ```tsx // app/layout.tsx import { EcommerceProvider } from 'hi-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 hi-pharmacist-ecommerce npm install hi-pharmacist-ecommerce@latest ``` ### Publishing to npm 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