Project Setup

Let’s get your development environment ready and run the ML Store project! This guide will walk you through every step from downloading the code to seeing it live in your browser.

Quick Start

If you’re experienced with Node.js projects, here’s the TL;DR:

Terminal

# Clone or navigate to the project directory
cd mi-tutorial

# Install dependencies
npm install

# Start development server
npm run dev

For detailed explanations of each step, continue reading below.

Step-by-Step Setup

Navigate to Project Directory

Open your terminal and navigate to where you have the tutorial source code:

cd ~/workspace/source/mi-tutorial

Replace the path above with wherever you’ve placed the mi-tutorial folder on your system.

Verify you’re in the correct directory:

ls
# You should see: index.html  package.json  src/  public/  tsconfig.json

Install Dependencies

Install the required packages (Vite and TypeScript):

npm install

What's happening during installation?

npm reads package.json and downloads:

Vite 7.3.1 - Development server and build tool
TypeScript 5.9.3 - TypeScript compiler and type definitions
Their dependencies (a few dozen packages)

All packages are installed into a node_modules/ folder (which can be safely deleted and reinstalled anytime).This typically takes 30-60 seconds depending on your internet speed.

The node_modules folder can be large (50-100MB). This is normal for modern JavaScript projects.

Start Development Server

Launch the Vite development server:

npm run dev

You’ll see output similar to:

VITE v7.3.1  ready in 234 ms

➜  Local:   http://localhost:5173/
➜  Network: use --host to expose
➜  press h + enter to show help

Success! Your development server is running.

Open in Browser

Open your web browser and navigate to:

http://localhost:5173/

The port number (5173) may differ if that port is already in use. Check your terminal output for the exact URL.

You should see the ML Store homepage with:

Yellow header with search bar
“Envío gratis desde $299” hero banner
Benefits section with icons
“Cargar Productos” button

Test the Application

Click the “Cargar Productos” button to fetch products from the API.

What should happen?

Loading State: Spinner appears briefly
Products Load: Grid of 20 product cards appears
Interactive Features:
- Hover over product cards to see animation
- Click “Agregar al carrito” on any product
- Watch the cart counter in the header update
- See toast notification appear

If products don’t load, check:

Your internet connection (API requires online access)
Browser console for errors (F12 → Console tab)
That the Platzi API is accessible: https://api.escuelajs.co/api/v1/products

Development Workflow

Hot Module Replacement (HMR)

Vite provides instant feedback as you code:

// Try changing this message:
showNotification(`"${product.title}" added to cart! 🎉`);

Save any file and watch your browser update instantly without full page reload!

NPM Scripts Explained

Your package.json defines three scripts:

npm run dev
npm run build
npm run preview

Starts the development server

npm run dev

Runs Vite in development mode
Enables Hot Module Replacement
Serves files from http://localhost:5173/
TypeScript is compiled on-the-fly
Source maps for easy debugging

Use this while actively developing.

Creates production-ready build

npm run build

Compiles TypeScript to JavaScript
Minifies and optimizes code
Creates a dist/ folder with:
- Optimized HTML, CSS, JS
- Hashed filenames for cache busting
- Ready to deploy to any web host

Use this when you’re ready to deploy.

Preview production build locally

npm run build
npm run preview

Serves the dist/ folder
Test production build before deploying
Runs on http://localhost:4173/

Use this to verify your production build works correctly.

Project Structure Deep Dive

Let’s explore what each file does:

📄 index.html - Main HTML Structure

<!DOCTYPE html>
<html lang="es">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>ML Store | Tu Tienda Online</title>
  <link rel="stylesheet" href="/src/style.css" />
</head>
<body>
  <!-- Semantic HTML structure -->
  <header class="header">
    <!-- Logo, search bar, navigation -->
  </header>
  
  <main class="main">
    <!-- Hero section -->
    <!-- Benefits section -->
    <!-- Products section (dynamic) -->
  </main>
  
  <footer class="footer">
    <!-- Footer content -->
  </footer>
  
  <script type="module" src="/src/main.ts"></script>
</body>
</html>

Key Features:

800+ lines of educational comments
Semantic HTML5 elements
BEM class naming convention
Accessibility attributes (ARIA labels)
Template element for product cards

📘 src/main.ts - TypeScript Application Logic

The main TypeScript file handles:State Management:

interface AppState {
  status: LoadingState;
  products: Product[];
  error: string | null;
}

let appState: AppState = {
  status: LoadingState.Idle,
  products: [],
  error: null
};

API Integration:

async function fetchProducts(limit = 20): Promise<Product[]> {
  const url = `${API_URL}?limit=${limit}`;
  const response = await fetch(url);
  if (!response.ok) {
    throw new Error(`HTTP error: ${response.status}`);
  }
  return await response.json();
}

Shopping Cart:

const cart: Map<number, number> = new Map();

function addToCart(productId: number): void {
  const currentQuantity = cart.get(productId) || 0;
  cart.set(productId, currentQuantity + 1);
  updateCartCount();
}

1000+ lines of explanatory comments teach TypeScript concepts.

🎨 src/style.css - CSS Styling

The stylesheet implements modern CSS:CSS Variables:

:root {
  /* Colors */
  --color-primary: #FFE600;
  --color-secondary: #3483FA;
  
  /* Typography */
  --font-size-base: 1rem;
  --font-size-lg: 1.125rem;
  
  /* Spacing */
  --spacing-md: 1rem;
  --spacing-lg: 1.5rem;
}

BEM Methodology:

.product-card { }
.product-card__image { }
.product-card__title { }
.product-card__btn { }

Modern Layouts:

/* Flexbox for navigation */
.header__container {
  display: flex;
  justify-content: space-between;
  align-items: center;
}

/* CSS Grid for products */
.products__grid {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
  gap: var(--spacing-lg);
}

⚙️ tsconfig.json - TypeScript Configuration

{
  "compilerOptions": {
    "target": "ES2022",          // Modern JavaScript
    "module": "ESNext",          // ES modules
    "lib": ["ES2022", "DOM"],   // Include DOM types
    "strict": true,              // Strict type checking
    "moduleResolution": "bundler" // Vite-compatible
  },
  "include": ["src"]
}

This configuration:

Enables all strict type checking
Targets modern browsers (ES2022)
Includes DOM type definitions
Works seamlessly with Vite

📦 package.json - Project Metadata

{
  "name": "mi-tutorial",
  "version": "0.0.0",
  "type": "module",         // ES modules
  "scripts": {
    "dev": "vite",
    "build": "tsc && vite build",
    "preview": "vite preview"
  },
  "devDependencies": {
    "typescript": "~5.9.3",
    "vite": "^7.3.1"
  }
}

Minimal dependencies = faster installs and simpler maintenance.

Browser Developer Tools Setup

Maximize your learning by using DevTools effectively:

Open DevTools

Press F12 or:

Windows/Linux: Ctrl + Shift + I
Mac: Cmd + Option + I

Explore Key Panels

Elements
Console
Network
Sources

Inspect HTML and CSS

Click the inspector icon (top-left)
Hover over elements to highlight them
View and edit HTML structure
See computed styles and CSS rules
Test style changes live

Try changing --color-primary in :root to see live color changes!

View Logs and ErrorsThe application logs useful information:

🚀 Inicializando ML Store...
Fetching: https://api.escuelajs.co/api/v1/products?limit=20
Productos recibidos: 20
✅ ML Store lista

Errors appear in red with stack traces.

Monitor API Requests

See the fetch request to Platzi API
View request/response headers
Inspect JSON response data
Check response times

Look for the request to api.escuelajs.co when you click “Cargar Productos”.

Common Setup Issues

Port Already in Use

Error:

Port 5173 is already in use

Solution:

Stop other Vite instances
Or specify a different port:
```
npm run dev -- --port 3000
```

Module Not Found

Error:

Cannot find module 'vite'

Solution: Run npm install again:

rm -rf node_modules package-lock.json
npm install

TypeScript Errors

Error:

Property 'textContent' does not exist on type 'Element'

Solution: This means type assertions are needed. The tutorial code already handles this correctly. If you’re modifying code, use type assertions:

const element = document.querySelector('.my-class') as HTMLElement;

API Request Fails

Error:

Error al cargar productos: Failed to fetch

Solutions:

Check your internet connection
Verify the API is accessible: https://api.escuelajs.co/api/v1/products
Check browser console for CORS errors
Try disabling browser extensions (especially ad blockers)

The Platzi Fake Store API is free and public, but occasionally may have downtime.

Blank Page

Problem: Browser shows blank page or loading forever.Solutions:

Check Console (F12 → Console) for JavaScript errors
Hard Refresh: Ctrl+Shift+R (Windows) or Cmd+Shift+R (Mac)
Clear Cache: In DevTools → Network → Check “Disable cache”
Restart Dev Server: Ctrl+C to stop, then npm run dev again

Next Steps: Exploring the Code

Now that everything is running, here’s how to learn effectively:

Start with HTML

Open index.html and read through the comments. They explain:

Why we use semantic elements
How BEM class naming works
HTML accessibility best practices
Form and input fundamentals

Study the CSS

Open src/style.css and explore:

CSS variable system
Flexbox and Grid layouts
BEM class organization
Responsive design patterns
Animations and transitions

Dive into TypeScript

Open src/main.ts and follow:

Interface and type definitions
Async/await patterns
State management approach
DOM manipulation techniques
Event handling strategies

Experiment!

Make changes and see what happens:

Change colors and spacing
Modify product card layouts
Add new features to the cart
Style the loading spinner differently
Add new product filters

Helpful Commands Reference

npm install

VS Code Tips

Quick File Navigation: Ctrl+P (Windows) or Cmd+P (Mac) to quickly open files by name.

Format on Save: In VS Code settings, enable “Format On Save” with Prettier for automatic code formatting.

Split Editor: Ctrl+\ to split the editor and view HTML, CSS, and TypeScript side-by-side.

View Source Code

The complete source code is in ~/workspace/source/mi-tutorial/

Start Learning

Read through the comments in each file to understand how everything works together.

You’re all set! Start exploring the code and building amazing web applications.

Get Started

HTML Fundamentals

CSS Fundamentals

TypeScript Basics

Project Tutorial

Project Setup

Project Setup

Quick Start

Step-by-Step Setup

Development Workflow

Hot Module Replacement (HMR)

NPM Scripts Explained

Project Structure Deep Dive

Browser Developer Tools Setup

Common Setup Issues

Next Steps: Exploring the Code

Helpful Commands Reference

VS Code Tips

View Source Code

Start Learning

Build docs developers (and LLMs) love

Get Started

HTML Fundamentals

CSS Fundamentals

TypeScript Basics

Project Tutorial

Documentation Index

​Project Setup

​Quick Start

​Step-by-Step Setup

​Development Workflow

​Hot Module Replacement (HMR)

​NPM Scripts Explained

​Project Structure Deep Dive

​Browser Developer Tools Setup

​Common Setup Issues

​Next Steps: Exploring the Code

​Helpful Commands Reference

​VS Code Tips

View Source Code

Start Learning

Build docs developers (and LLMs) love

Project Setup

Quick Start

Step-by-Step Setup

Development Workflow

Hot Module Replacement (HMR)

NPM Scripts Explained

Project Structure Deep Dive

Browser Developer Tools Setup

Common Setup Issues

Next Steps: Exploring the Code

Helpful Commands Reference

VS Code Tips