Build and Deploy a Multi-Vendor E-Commerce Marketplace with Nextjs, React & Stripe Connect (2025)

Key Concepts

• Multi-tenant e-commerce application: A platform where multiple vendors can sell products, each with their own branded storefront.
• Vendor-specific subdomains: Each vendor gets a unique subdomain for their storefront (e.g., vendorname.example.com).
• Stripe Connect: Used for processing payments, paying vendors, and automatically taking platform fees.
• Payload CMS: A headless CMS used for managing product data, categories, and other platform entities.
• Role-based access control (RBAC): Vendors can only manage their own data, while admins have full control.
• Next.js: A React framework used for building the storefront and dashboards.
• Bun: A JavaScript runtime and package manager, chosen for its speed and zero-config script running.
• Shaden UI: A collection of accessible components and a code distribution platform.
• Tailwind CSS: A utility-first CSS framework used for styling the application.
• Neo Brutalism: A design style characterized by black borders, white backgrounds, and a minimalist aesthetic.
• Route Groups: A Next.js feature for organizing files without affecting URL structure.
• Layouts: Reusable components that wrap pages and provide consistent UI elements.
• Server Components: React components that run on the server by default in Next.js.
• Client Components: React components that run on the client, requiring the use client directive.
• TRPC: A TypeScript library for building end-to-end type-safe APIs.
• Tanstack React Query: A data-fetching and caching library for React.
• Zod: A TypeScript-first schema declaration and validation library.
• SuperJSON: A JavaScript library for serializing and deserializing data, including dates and other complex types.
• Use Query: A hook from Tanstack React Query for fetching data.
• Use Mutation: A hook from Tanstack React Query for performing mutations (e.g., creating, updating, deleting data).
• Use Infinite Query: A hook from Tanstack React Query for implementing infinite scrolling.
• Prefetching: Fetching data on the server before rendering a component, improving performance.
• Hydration Boundary: A React component that ensures data fetched on the server is available on the client.
• Use Pathname: A Next.js hook for accessing the current URL path.
• Use Effect: A React hook for performing side effects in functional components.
• Use Ref: A React hook for accessing DOM elements.
• Use State: A React hook for managing component state.
• Lucid React: A library of open source icons.
• Code Rabbit: An AI code review tool.
• Nooks: A type-safe search params state manager for React.
• Seed Script: A script for populating the database with initial data.
• Access Control: Mechanisms for restricting access to data based on user roles and permissions.
• MongoDB: A NoSQL database used for storing application data.
• Versel: A platform for deploying web applications.
• Tenant: In this context, a shop or store on the multi-tenant platform.

1. Setting Up Next.js and Environment

• Node.js Version: Requires Node.js version 18.18 or higher.
• Package Manager: Bun is recommended for faster installation speeds compared to npm, pnpm, and yarn.
• Bun Installation: Visit bun.sh for installation instructions.
• Next.js Installation: Use bunx [email protected] (or the latest version).
• Project Setup:
  • Use TypeScript, ESLint, and Tailwind CSS.
  • Use a source directory (src).
  • Enable the app router.
  • Disable Turbo pack (for consistent results).
  • Keep the default import alias (@).
• Package.json Dependencies:
  • React: 19
  • React DOM: 19
  • Next: 15.2.4
  • Tailwind CSS: Version 4 (important for compatibility).
• Running the App: Use bun rundev and visit localhost:3000.
• Shaden UI Installation: Use bunx [email protected] init (or the latest version).
• Component Addition: Use bunx [email protected] add all to add all components.
• Tailwind CSS IntelliSense: Install the Tailwind CSS IntelliSense extension for VS Code.
• GitHub Repository: Create a new private repository on GitHub and push the project using Git commands.

2. Customizing the Look and Feel

• Font: Add the DM Sans font from Google Fonts in layout.tsx.
• Neo Brutalism Style: Modify globals.css to set the default border color to black by setting the lightness to zero in the OKCH color value for the border.
• Button Styling:
  • Add an elevated variant with a white background, black shadow, and translate hover effect.
  • Remove shadows from other button variants.
  • Set the default text size to text-base.
  • Add cursor-pointer class.
• Input Styling:
  • Set the height to 12.
  • Set the background color to white.
  • Set the font to medium and text to base.
  • Remove shadow.
• Progress Bar Styling:
  • Remove the default background.
  • Add a border and transparent background.
  • Set the indicator background to pink 400.
  • Set the height to 3.
• Text Area Styling:
  • Set the text to base.
  • Remove shadow.
• Radius Modification: Change the radius MD to be -4 pixels in globals.css.
• Git Branching: Create a new branch for customization using git checkout -b 02-customization.
• Code Rabbit: Use Code Rabbit for code review and suggestions.

3. Creating the Home Layout

• Route Groups: Use route groups (folders in parentheses) to organize files without affecting URLs.
• Layout Files: Create layout.tsx files within route groups to define reusable UI elements.
• Navbar Component:
  • Create a Navbar component with a logo, navigation items, and login/registration buttons.
  • Use next/link for navigation.
  • Use the usePathname hook to highlight the active navigation item.
  • Use the use client directive to enable client-side functionality.
• Mobile Navbar (Sidebar):
  • Create a NavbarSidebar component with a menu icon and a sheet component for the sidebar.
  • Use a state variable to control the sidebar's visibility.
• Footer Component:
  • Create a Footer component with copyright information.
• Flex Layout: Use flexbox to structure the layout with a navbar, main content area, and footer.
• GitHub Branching: Create a new branch for the home layout using git checkout -b 03-home-layout.

4. Integrating Payload CMS

• Database Choice: MongoDB is chosen for its flexible schema and free cloud hosting via Atlas.
• MongoDB Atlas Setup: Create a free cluster on MongoDB Atlas, create a database user with Atlas admin role, and allow access from anywhere (0.0.0.0/0) for development.
• Payload Installation: Use bunx create-payload-app --use-bun (or the equivalent for other package managers).
• Database URL: Provide the MongoDB connection string, including the username, password, and database name.
• Directory Structure: Payload creates frontend, payload, and route folders inside the app directory.
• Remove Front-end Folder: Remove the frontend folder created by Payload to avoid conflicts.
• Admin Dashboard: Access the Payload admin dashboard at localhost:3000/admin.
• Collections: Payload uses collections to manage data.
• Categories Collection: Create a categories collection with fields for name (text, required), slug (text, required, unique, indexed), color (text), parent (relationship to self), and subcategories (join to self).
• Payload Configuration: Add the categories collection to the payload.config.ts file.
• Payload Types: Generate Payload types using bun run generate-types.
• Direct-to-Database API: Use Payload's Node.js API to fetch data directly in server components.
• Access Control: Use the access object in collections to restrict create and update permissions.
• GitHub Branching: Create a new branch for Payload integration using git checkout -b 04-payload-integration.

5. Developing Basic Search Filters

• Enhance Categories Collection: Add fields for slug (unique identifier), color (background color), and subcategories (relationship to itself).
• Search Filters Component: Create a SearchFilters component with an input for search and a category dropdown menu.
• Category Dropdown: Display all categories in a dropdown menu.
• Subcategories: When hovering over a category, display its subcategories in a submenu.
• Data Fetching: Load categories from Payload CMS using the Node.js API.
• Formatted Data: Transform the data structure to easily display categories and subcategories.
• Use Client Directive: Add the use client directive to the SearchFilters component to enable client-side functionality.
• Use Pathname Hook: Use the usePathname hook to highlight the active category.
• GitHub Branching: Create a new branch for search filters using git checkout -b 05-search-filters.

6. Finalizing Categories

• Seed Script: Create a seed.ts script to populate the database with categories.
• Database Fresh Command: Add a database:fresh script to the package.json file to reset the database.
• Database Seed Command: Add a database:seed script to the package.json file to seed the database.
• Database Reset Command: Add a database:reset script to the package.json file to reset and seed the database.
• Elevated State: Ensure that the elevated state of the button is maintained when the submen is open.
• Custom Types: Create custom types for categories and subcategories to improve type safety.
• Responsive Design: Hide categories that do not fit on the screen.
• View All Button: Add a "View All" button to open a sidebar with all categories.
• Categories Sidebar: Create a CategoriesSidebar component to display all categories in a sidebar menu.
• GitHub Branching: Create a new branch for categories finalization using git checkout -b 06-categories-finalization.

7. TRPC Integration

• Install TRPC Packages: Install the necessary TRPC packages using bun add.
• Create TRPC Router: Create a TRPC router with a base procedure.
• Create Query Client Factory: Create a query client factory for Tanstack React Query.
• Create TRPC Client: Create a TRPC client for client components.
• Mount TRPC in Root: Mount the TRPC provider in the root of the application.
• Create Server Fetcher: Create a server fetcher for server components.
• Categories Router: Add a categories router to the TRPC router.
• Fetch Categories: Fetch categories in the layout using the TRPC server.
• Client-Side Fetching: Fetch categories in the categories sidebar using the TRPC client.
• Infer TRPC Types: Infer the output types from the TRPC router.
• GitHub Branching: Create a new branch for TRPC integration using git checkout -b 07-TRPC-integration.

8. Authentication

• Modify Users Collection: Add a username field to the users collection.
• Create Auth Procedures: Create auth procedures for registration, login, and logout.
• Use Payload Auth Utils: Leverage Payload's auth utils for authentication.
• Create Auth Screens: Create sign-in and sign-up screens.
• Display Authenticated States: Display different UI elements based on the user's authentication state.
• GitHub Branching: Create a new branch for authentication using git checkout -b 08-authentication.

9. Authentication States

• Alternative Login: Implement login using Payload's REST API.
• Cookie Prefix: Use the cookiePrefix option in Payload's configuration to customize the cookie name.
• Generate Auth Cookie Util: Create a utility function to generate the auth cookie.
• Invalidate Session: Invalidate the session after login and registration.
• Authenticated State: Prevent authenticated users from accessing the login and registration pages.
• Dashboard Button: Display a dashboard button in the navbar for authenticated users.
• Library Button: Display a library button in the search input for authenticated users.
• GitHub Branching: Create a new branch for authentication states using git checkout -b 09-auth-states.

10. Category Pages

• Dynamic Category Route: Create a dynamic category route in Next.js.
• Subcategory Route: Create a dynamic subcategory route in Next.js.
• Load Categories: Load categories based on the URL parameters.
• Apply Style: Apply a specific style to the search filter component.
• Breadcrumb Navigation: Implement breadcrumb navigation for category and subcategory pages.
• GitHub Branching: Create a new branch for category pages using git checkout -b 10-category-pages.

11. Products

• Products Collection: Create a products collection with fields for name, description, price, category, image, and refund policy.
• Admin Use as Title: Set the useAsTitle field in the categories collection to display the category name in the admin panel.
• Load Products: Load products based on the category.
• Prefetching: Use prefetching to load products on the server.
• Suspense Loading: Use suspense to load products on the client.
• GitHub Branching: Create a new branch for products using git checkout -b 11-products.

12. Filtering Products

• Price Filters: Add minimum and maximum price filters to the products collection.
• Nooks Integration: Integrate Nooks for type-safe search params state management.
• Use Product Filters Hook: Create a useProductFilters hook to manage the filter state.
• Product Filter Component: Create a ProductFilter component to display the filters.
• GitHub Branching: Create a new branch for filtering products using git checkout -b 12-filtering-products.

13. API Filters and Sorting

• Tags Collection: Create a tags collection with a relationship to products.
• Tags Filter: Add a tags filter to the products collection.
• Infinite Load: Implement infinite scrolling for tags.
• Sorting: Add sorting options to the products collection.
• GitHub Branching: Create a new branch for API filters and sorting using git checkout -b 13-API-filters-and-sorting.

14. Product List UI

• Product Card Component: Create a reusable ProductCard component to display product information.
• Product Card Skeleton: Create a ProductCardSkeleton component for loading states.
• Infinite Load for Products: Implement infinite scrolling for products.
• No Products Found Message: Display a message when no products are found.
• GitHub Branching: Create a new branch for product list UI using git checkout -b 14-product-list-UI.

15. Multi-Tenancy

• Tenants Collection: Create a tenants collection with fields for name, slug, image, stripe account ID, and stripe details submitted.
• Multi-Tenant Plugin: Install and configure the multi-tenant plugin.
• User Roles: Add a roles field to the users collection with options for super admin and user.
• Tenant Field to User: Add a tenant field to the users collection using the multi-tenant plugin.
• Create Tenant on Registration: Create a tenant when a new user registers.
• GitHub Branching: Create a new branch for multi-tenancy using git checkout -b 15-multi-tenancy.

16. Tenant Pages

• Tenant Shop Page: Create a dynamic tenant shop page to display products for a specific tenant.
• Layout Component: Create a layout component for the tenant shop page.
• Navbar and Footer: Add a navbar and footer to the tenant shop page.
• Prefetch Tenant Data: Prefetch tenant data in the layout component.
• Generate Tenant URL Util: Create a utility function to generate tenant URLs.
• GitHub Branching: Create a new branch for tenant pages using git checkout -b 16-tenant-pages.