Skip to main content

​
Quick Start

Get Villa Buena E-Commerce running on your local machine in just a few minutes. This guide will take you from zero to a fully functional e-commerce application.
Before you begin, make sure you have Node.js 18+ and npm (or yarn/pnpm) installed on your machine.

​
Step-by-Step Setup

1

Clone the Repository

Clone the Villa Buena source code to your local machine:
git clone <repository-url>
cd villa-buena-ecommerce
2

Install Dependencies

Install all required packages using your preferred package manager:
npm install
This will install all dependencies including:
  • React 19.2.0 and React DOM
  • Vite 7.3.1 build tooling
  • Auth0 authentication library
  • TanStack Query for data fetching
  • Zustand for state management
  • Bootstrap 5.3.8 for UI components
  • And more…
3

Configure Environment Variables

Create a .env file in the root directory and add your API endpoint:
VITE_API_URL=https://dummyjson.com
The application uses import.meta.env.VITE_API_URL in the API service layer (see src/services/api.js:4).
All environment variables must be prefixed with VITE_ to be accessible in your application code.
4

Configure Auth0 (Optional)

The application comes pre-configured with a demo Auth0 setup. For production use, you should configure your own Auth0 application:
  1. Create a free account at auth0.com
  2. Create a new Single Page Application
  3. Update the Auth0 configuration in src/main.jsx:
src/main.jsx
<Auth0Provider
  domain="YOUR_AUTH0_DOMAIN"
  clientId="YOUR_CLIENT_ID"
  authorizationParams={{ redirect_uri: window.location.origin }}
  onRedirectCallback={onRedirectCallback}
  cacheLocation="localstorage"
>
  <RouterProvider router={router} />
</Auth0Provider>
For quick testing, you can use the pre-configured demo credentials. Just skip this step to use the defaults.
5

Start the Development Server

Launch the Vite development server:
npm run dev
The application will start and be available at http://localhost:5173 (default Vite port).You should see output similar to:
VITE v7.3.1  ready in 324 ms

➜  Local:   http://localhost:5173/
➜  Network: use --host to expose
6

Verify Installation

Open your browser and navigate to http://localhost:5173. You should see:
  • The home page with a product catalog
  • A navigation bar with authentication options
  • Product filtering and search functionality
  • A shopping cart icon
The application fetches products from the configured API endpoint. Make sure your VITE_API_URL is set correctly.

​
Test the Application

Now that Villa Buena is running, try these features:

​
Browse Products

The home page displays a paginated product catalog with:
  • Category filtering
  • Search functionality
  • Price sorting (ascending/descending)
  • Pagination (12 products per page)

​
Add to Cart

  1. Click on any product to view details
  2. Click “Add to Cart” button
  3. See the cart icon update with item count
  4. Open the cart drawer to review items
Cart data persists in localStorage thanks to Zustand’s persist middleware (see src/store/useCartStore.js:62-64).

​
Authentication

  1. Click the login button in the navigation bar
  2. Sign in using the Auth0 login flow
  3. Access protected features like account and order history

​
Checkout Flow

  1. Add products to cart
  2. Navigate to cart
  3. Proceed through shipping (/checkout/shipping)
  4. Complete payment information (/checkout/payment)
  5. See order confirmation (/payment/success)

​
What’s Running?

When you start the development server, several key systems initialize:

​
Application Providers

The app is wrapped with multiple providers in src/main.jsx: 
<QueryProvider>           {/* TanStack Query client */}
  <Auth0Provider>         {/* Authentication context */}
    <RouterProvider />     {/* React Router navigation */}
  </Auth0Provider>
</QueryProvider>

​
Layout System

Every page uses the Layout component (src/app/Layout.jsx) which includes:
  • Navbar - Navigation and authentication controls
  • Toast - Global notification system
  • CartDrawer - Slide-out cart panel
  • Outlet - Renders the current route component

​
State Stores

Three Zustand stores are initialized:
  • useCartStore - Shopping cart state with persistence
  • useUserStore - User profile data
  • useUIStore - UI preferences (dark mode, notifications)

​
Common Development Commands

npm run build

​
Troubleshooting

If port 5173 is already in use, Vite will automatically try the next available port (5174, 5175, etc.).To specify a custom port, update vite.config.js:
export default defineConfig({
  plugins: [react()],
  server: {
    port: 3000
  }
})
Make sure your .env file contains the correct API URL:
VITE_API_URL=https://dummyjson.com
After changing environment variables, restart the dev server.
If you’re experiencing redirect loops:
  1. Clear localStorage: localStorage.clear() in browser console
  2. Verify your Auth0 application settings
  3. Check that the redirect URI matches your app URL
Delete node_modules and reinstall:
rm -rf node_modules
npm install

​
Next Steps

Installation Guide

Deep dive into installation and configuration options

Architecture

Learn about the application structure and design patterns

API Reference

Explore the API services and data models

Building

Build and deploy Villa Buena to production
Now that you have Villa Buena running, explore the codebase starting with src/main.jsx to understand how everything connects together.

Build docs developers (and LLMs) love

Get started for freeTalk to us