CrowCommerce Medusa TailwindUI

CrowCommerce is a commerce template monorepo that pairs a Vercel Commerce-derived Next.js 16 storefront with a Medusa v2 backend, Tailwind Plus UI patterns, and production integrations for Stripe, PostHog, Sentry, Resend, Meilisearch, and Cloudflare R2.

Last updated: 2026-03-30

• Setup Guide — local development through production deployment
• Fork-Per-Client Ownership Model — template boundaries, site-owned paths, and backport rules
• Downstream forks: keep LICENSE and storefront/license.md, review Tailwind Plus rights before redistribution, and preserve any required third-party notices

Vercel ownership: This storefront is deployed from the CrowCommerce Vercel team with slug crow-commerce. The correct Vercel project path is crow-commerce/commerce-tailwindui-medusa.

Built On

This project builds directly on:

• Vercel Commerce — the storefront is a Vercel Commerce fork, with the Shopify adapter replaced by Medusa. The routing conventions, caching patterns, and type shapes follow Vercel Commerce closely.
• Medusa Starter / Medusa v2 — the backend is a Medusa v2 starter extended with custom modules, workflows, admin extensions, and integrations.
• Tailwind Plus / Tailwind UI — the UI design system is built on Tailwind Plus ecommerce blocks. Component layouts, the seed catalog, and interaction patterns all draw from Tailwind UI.
• Medusa Next.js Starter — the customer account flows and Stripe checkout customization follow patterns from the Medusa Next.js starter.
• Untitled UI React Email — the email system was rebuilt from Untitled UI email primitives, remapped to CrowCommerce/Tailwind tokens.
• Medusa Product Reviews Tutorial — primary reference for the review module and storefront/admin review flows.
• Medusa Wishlist Tutorial plus @alphabite/medusa-wishlist and @godscodes/medusajs-wishlist-plugin — the wishlist architecture, guest flows, share tokens, and storefront action patterns draw from all three.
• Medusa Checkout Docs, Saved Payment Methods Tutorial, and lambda-curry/medusa2-starter — the Stripe checkout flow, saved cards, and guest checkout are built against these references.
• Medusa Invoice Generator Tutorial — reference for the invoice module and PDF generation workflow.
• Medusa Abandoned Cart Tutorial — reference for the cart recovery email flow.
• lambda-curry/medusa-plugins and @devx-commerce/plugin-product-reviews — pattern references for the review image uploads and admin response features.

Screenshots

Lighthouse Scores

Baseline scores with zero performance optimization passes.

Metric	Desktop	Mobile
Performance	99	81
Accessibility	100	100
Best Practices	100	100
SEO	100	100

Desktop

Mobile

Tech Stack

Layer	Actual packages / services	Version(s) from repo	Purpose
Monorepo	Bun workspaces, Turborepo	[email protected], [email protected]	Workspace management, parallel dev/build/test orchestration
Storefront framework	Next.js, React, React DOM	[email protected], [email protected], [email protected]	App Router storefront with RSC, Server Actions, metadata, OG image routes
Frontend language/tooling	TypeScript, PostCSS	[email protected], [email protected]	Strict typing and build tooling
Styling and UI	Tailwind CSS, Headless UI, Heroicons, clsx, Geist	[email protected], @headlessui/[email protected], @heroicons/[email protected], [email protected], [email protected]	Design system implementation and accessible interactive UI
Commerce storefront client	@medusajs/js-sdk, @medusajs/types	2.13.1	Store API access and Medusa response typing
Payments	Stripe JS + React Stripe JS	@stripe/[email protected], @stripe/[email protected]	Checkout, Payment Element, saved cards, redirect flows
Search	Meilisearch, React InstantSearch	[email protected], @meilisearch/[email protected], [email protected]	Search command palette, /search query-param filtering, backend indexing
Analytics and error monitoring	PostHog, Sentry	[email protected], [email protected], @sentry/nextjs@^10, @sentry/node@^10, @sentry/profiling-node@^10	Typed analytics, feature flags, replay, tracing, exception capture
Validation	Zod	[email protected]	Server action and route validation
Backend framework	Medusa core packages	@medusajs/[email protected], , ,

Workspace Layout

storefront/           Next.js 16 storefront
backend/              Medusa v2 backend + admin
packages/site-config/ Site-owned brand, navigation, and integration config
tooling/typescript/   Shared TypeScript configuration

Feature Overview

Features shipped in roughly this order: Medusa integration, customer accounts, reviews, wishlist, Stripe checkout, production deployment, product quick view, email infrastructure, invoice generation, S3/R2 storage, Sentry, PostHog, newsletter signup, Meilisearch search, legal/company pages, and site-boundary scaffolding.

Feature	Status	What's shipped	What's remaining
Medusa v2 integration	✅ Shipped	Full catalog + cart	—
Customer accounts	✅ Shipped	Auth, profile, addresses, order history, and order detail pages	—
Stripe checkout	✅ Shipped	5-step flow, saved cards, guest checkout	—
Product quick view	✅ Shipped	Hover overlay modal on grid	—
Production deployment	✅ Shipped	Vercel + Railway	—
Email infrastructure	🟡 Partial	Stacks 1-5 (8 templates + invoices)	Stacks 6-7 (premium, quotes)
Product reviews	🟡 Partial	Core reviews, admin responses, review images, and verified purchase badges	Admin review search and review editing
Wishlist	✅ Shipped	Full feature + E2E tests	Code review follow-ups only
Invoice generation	✅ Shipped	On-demand PDF with product thumbnails, admin config, email toggle, customer + admin download, code review fixes applied	—
Newsletter signup + email preferences	✅ Shipped	Footer signup, welcome + welcome-back emails, Resend Audience sync, opaque server-stored unsubscribe tokens, tokenless unsubscribe confirmation redirect, account-managed email preferences, email-link preferences page, rate limiting, and PostHog events	—
Search

Infrastructure & Tooling

Item	Status	Notes
S3 file provider (Cloudflare R2)	✅ Shipped	Persistent file storage via R2, E2E tests
Sentry error monitoring	✅ Shipped	Full error capture (checkout, cart, auth, 13 subscribers, jobs), user context enrichment, environment separation, 5xx-only proxy policy
PostHog analytics	✅ Shipped	45 storefront events + 8 backend events, session replay, web vitals, feature flags, experiments, surveys (NPS + exit), trackGoal()
CI/CD (GitHub Actions)	🟡 Partial	GitHub Actions now runs storefront/backend typecheck, Prettier, storefront/backend unit tests, a storefront production compile check, and Playwright smoke coverage for eligible PRs. Preview/health checks are still missing.
Medusa webhooks for cache revalidation	🟡 Partial	Backend product and collection events already trigger storefront catalog revalidation. Production end-to-end verification is still pending.
Vitest unit tests	🟡 Partial	Deterministic unit coverage exists for transforms, analytics PII redaction, checkout schemas, Sentry config, structured data, order status, and shared validation.
Playwright E2E coverage	🟡 Partial	Smoke flows cover storefront load, browse-to-cart, guest checkout, and wishlist login; deeper suites cover wishlist, reviews, search, orders, newsletter, and checkout variants.
React Compiler optimization	⏳ Not started	Compiler enabled, no audit yet

Deferred Features

These are features identified but not yet planned in detail:

• Multi-region / multi-currency support
• Collections/categories with images
• CMS pages (Payload CMS integration)
• Re-order previous purchases (temporarily disabled pending checkout hardening)
• Agentic commerce (AI shopping assistant, natural language search)
• Newsletter campaigns (sending/scheduling — signup is shipped)

Quick Start

Start with SETUP.md. It covers local prerequisites, self-documenting .env.example files, seeding the Medusa backend, optional services like Redis/Meilisearch/Stripe/Resend, and production deployment on Railway + Vercel.

For day-to-day development from the repo root:

bun install
bun run dev

Architecture

CrowCommerce is organized as a Bun/Turbo monorepo with a shared template core and explicit override zones for downstream forks. The shared paths live in storefront/, backend/, tooling/, and docs/; site-specific customization already has reserved scaffolded zones in packages/site-config/, storefront/site/, and backend/src/site/.

• Fork-per-client ownership model
• Email infrastructure
• Medusa integration design
• PostHog analytics ADR

Archive

Completed plans and specs: docs/archive/

License

This monorepo uses layered licensing:

• Repo-authored template code and documentation are licensed under the root LICENSE.
• The storefront preserves the upstream Vercel Commerce MIT notice in storefront/license.md. Downstream forks should keep that notice in place for inherited storefront portions.
• Tailwind Plus / Tailwind UI components, templates, and design assets remain subject to Tailwind Labs' commercial license. This repository does not grant or transfer Tailwind Plus rights. If a downstream fork keeps Tailwind Plus-derived UI, the fork owner is responsible for holding their own valid Tailwind Plus license or access and for replacing that material if they cannot satisfy those terms.
• Other upstream code, npm packages, and third-party assets remain under their own licenses. When redistributing a fork, preserve existing notices and add any new notices required by the dependencies or assets you introduce.