Production-ready, multi-tenant e‑commerce UI + API adapter for Next.js with auth, carts, checkout, orders, theming, and pharmacist-focused UX.
npm install hey-pharmacist-ecommerceProduction‑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.
- 🛒 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
``bash`
npm install hey-pharmacist-ecommerce react-hook-form @hookform/resolvers
Install the library and its peer dependencies:
`bash`
npm install hey-pharmacist-ecommerce react-hook-form @hookform/resolversor
yarn add hey-pharmacist-ecommerce react-hook-form @hookform/resolvers
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}",
],
// ...
}
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",
};
`
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 (
$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 ordersTheming 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-adapterAuth 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 buildCreate 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-ecommerceInstall 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 majorPublish 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`.MIT