Skip to main content

​
Quick Start Guide

Get Q-Sopa running on your local machine in just a few minutes. This guide will walk you through cloning the repository, installing dependencies, and starting the development server.
Prerequisites: Make sure you have Node.js version 16 or higher installed on your machine. You can check your version with node --version.

​
Installation

1

Clone the Repository

First, clone the Q-Sopa repository to your local machine:
git clone https://github.com/JhonnyDiaz4753/Q_sopa.git
cd Q_sopa
2

Install Dependencies

Install all required dependencies using your preferred package manager:
npm install
This will install:
  • React 19.2.0
  • React DOM 19.2.0
  • Vite 7.3.1
  • ESLint and related plugins
3

Start the Development Server

Launch the Vite development server with hot module replacement:
npm run dev
The application will start at http://localhost:5173 (or another port if 5173 is in use).
4

Open in Browser

Open your web browser and navigate to the URL shown in your terminal (typically http://localhost:5173).You should see the Q-Sopa menu application with the animated logo splash screen!

​
Configuration

​
API Configuration

The application is pre-configured to use the production API hosted on Railway. The API base URL is set in src/services/api.js:
src/services/api.js
const BASE_URL = "https://apiqsp-production.up.railway.app";
Using a Different API? If you need to point to a local or different API endpoint, modify the BASE_URL constant in src/services/api.js.

​
Environment Variables (Optional)

For more flexible configuration, you can create a .env file in the project root:
.env
VITE_API_URL=https://apiqsp-production.up.railway.app
Then update src/services/api.js to use the environment variable:
src/services/api.js
const BASE_URL = import.meta.env.VITE_API_URL || "https://apiqsp-production.up.railway.app";
Vite exposes environment variables prefixed with VITE_ to your client-side code via import.meta.env.

​
Project Scripts

Q-Sopa includes several npm scripts defined in package.json:
package.json
{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "lint": "eslint .",
    "preview": "vite preview"
  }
}

​
Available Commands

Development Server

npm run dev
Starts Vite dev server with HMR at http://localhost:5173

Build for Production

npm run build
Creates optimized production build in dist/ directory

Lint Code

npm run lint
Runs ESLint to check code quality and style

Preview Build

npm run preview
Previews production build locally

​
First-Time Setup Walkthrough

​
Understanding the Initial State

When you first load the application, you’ll see:
  1. Navigation Bar: Displays the Q-Sopa logo and category navigation
  2. Logo Splash Screen: Animated ripple effect with the logo
  3. Call-to-Action: Text prompting you to “Selecciona una categoría para ver el menú”
  4. Footer: Copyright information
This is the default state when no category is selected, as defined in src/pages/Menu.jsx:
src/pages/Menu.jsx
export default function Menu() {
  const [products, setProducts] = useState([]);
  const [activeCategoryId, setActiveCategoryId] = useState(null); // null = sin categoría

  // ...

  return (
    <>
      <Navbar
        onCategoryChange={handleCategoryChange}
        onLogoClick={handleLogoClick}
      />

      <main className="menu-container">
        {/* Sin categoría → LogoSplash */}
        {activeCategoryId === null && <LogoSplash />}
        
        {/* Products display when category is selected */}
      </main>

      <Footer />
    </>
  );
}

​
Exploring the Application

1

Select a Category

Click on any category button in the navigation bar (e.g., hamburgers, pizzas, bebidas). On mobile, tap the hamburger menu icon to open the category drawer.
2

View Products

The application will:
  1. Show a loading spinner
  2. Fetch products from the API
  3. Display product cards in a responsive grid
Each product card shows:
  • Product image
  • Product name
  • Price
  • Optional badge (if present)
  • “Ingredientes” button
3

Switch Categories

Click different category buttons to see different products. The active category is highlighted with a visual indicator.
4

Return to Home

Click the Q-Sopa logo in the navigation bar to return to the splash screen.

​
Development Workflow

​
Hot Module Replacement (HMR)

Vite provides instant HMR, meaning your changes appear in the browser without a full page reload:
src/components/ProductCard/ProductCard.jsx
export default function ProductCard({ title, price, image, badge }) {
  return (
    <div className="product-card">
      {badge && <div className="badge">{badge}</div>}
      <img src={image} alt={title} />
      <div className="product-info">
        <h4>{title}</h4>
        <span>${price}</span>
      </div>
      <button className="product-btn">Ingredientes</button>
    </div>
  );
}
Try modifying the button text in ProductCard.jsx - your changes will appear instantly in the browser!

​
Project Entry Point

The application bootstraps from src/main.jsx:
src/main.jsx
import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import './index.css'
import App from './App.jsx'

createRoot(document.getElementById('root')).render(
  <StrictMode>
    <App />
  </StrictMode>,
)
React 19’s StrictMode helps identify potential problems in the application during development.

​
Application Root

The App component simply renders the Menu page:
src/App.jsx
import Menu from "./pages/Menu";
import "./App.css";

function App() {
  return <Menu />;
}

export default App

​
Building for Production

1

Create Production Build

Run the build command:
npm run build
This creates an optimized build in the dist/ directory.
2

Preview the Build

Test the production build locally:
npm run preview
3

Deploy

Deploy the contents of the dist/ directory to your hosting provider (Vercel, Netlify, Railway, etc.).

​
Build Output

Vite optimizes your application with:
  • Code splitting: Separate chunks for better caching
  • Minification: Smaller file sizes
  • Tree shaking: Remove unused code
  • Asset optimization: Optimized images and CSS

​
Troubleshooting

​
Port Already in Use

If port 5173 is already in use, Vite will automatically try the next available port. You can also specify a custom port:
vite.config.js
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  server: {
    port: 3000
  }
})

​
API Connection Issues

If you see error messages about loading categories or products:
  1. Check your internet connection
  2. Verify the API URL in src/services/api.js
  3. Check the browser console for detailed error messages
  4. Ensure the API server is running

​
Missing Material Symbols

If category icons don’t appear, verify that the Material Symbols stylesheet is loaded in index.html:
index.html
<link href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined" rel="stylesheet">

​
Next Steps

Explore Components

Deep dive into each component’s implementation

API Integration

Learn how data flows through the application

Styling Guide

Understand the CSS architecture and customize styles

Customization

Learn how to customize and extend Q-Sopa
Ready to customize? Start by exploring the component files in src/components/ - each component is self-contained with its own CSS file for easy modification.

Build docs developers (and LLMs) love

Get started for freeTalk to us