Installation & Setup

System Requirements

Node.js

Version 22 or higherCheck your version: node --version

Package Manager

pnpm (recommended)Or npm/yarn

Database

Supabase AccountFree tier available

Git

Version ControlFor cloning repository

Node.js 22+ is required due to dependencies on latest React 19 and TypeScript 5.9 features.

Installation Methods

Choose your preferred installation method:

Local Development
Docker
Production Deployment

Prerequisites

Install Node.js 22+ from nodejs.org or use a version manager:

# Install nvm from https://github.com/nvm-sh/nvm
nvm install 22
nvm use 22

Install pnpm

pnpm is the recommended package manager for faster installs and better disk usage:

# Enable corepack (comes with Node.js)
corepack enable

# Or install via npm
npm install -g pnpm

Clone and Install

# Clone the repository
git clone <your-repository-url>
cd trazea

# Install dependencies
pnpm install

# This takes 2-3 minutes on first run

The project uses over 50 dependencies including React 19, TypeScript, Vite, Supabase, and Radix UI components.

Configure Environment

Create your environment file:

cp .env.example .env

Edit .env with your credentials:

.env

# Supabase Configuration (Required)
VITE_SUPABASE_URL=https://your-project.supabase.co
VITE_SUPABASE_ANON_KEY=your-anon-key-here

# Sentry Configuration (Optional - for error tracking)
VITE_SENTRY_DSN=https://[email protected]/project-id

# ElevenLabs Configuration (Optional - for voice agent TTS)
VITE_PUBLIC_ELEVENLABS_API_KEY=your-elevenlabs-api-key

Start Development Server

pnpm dev

The application will be available at:

Local: http://localhost:5173
Network: http://0.0.0.0:5173 (accessible from other devices on your network)

Vite’s HMR (Hot Module Replacement) provides instant feedback as you edit files. No manual refresh needed!

Prerequisites

Docker Engine 20.10+
Docker Compose v2.0+

Configuration

The project includes a multi-stage Dockerfile optimized for both development and production:

Dockerfile

# Stage 1: Development environment
FROM node:22-alpine AS dev
ENV PNPM_HOME="/pnpm"
ENV PATH="$PNPM_HOME:$PATH"
RUN corepack enable
WORKDIR /app
COPY package.json pnpm-lock.yaml ./
RUN pnpm install

# Stage 2: Production build
FROM dev AS builder
COPY . .
RUN pnpm build

# Stage 3: Nginx server
FROM nginx:alpine AS runner
COPY --from=builder /app/dist /usr/share/nginx/html
EXPOSE 80

Development with Docker Compose

Create .env file first:

.env

VITE_SUPABASE_URL=https://your-project.supabase.co
VITE_SUPABASE_ANON_KEY=your-anon-key

Start the development container:

docker-compose up --build

The docker-compose.yml configuration:

docker-compose.yml

services:
  app:
    build:
      context: .
      target: dev
      args:
        PUBLIC_SUPABASE_URL: ${VITE_SUPABASE_URL}
        PUBLIC_SUPABASE_ANON_TOKEN: ${VITE_SUPABASE_ANON_KEY}
    ports:
      - "5173:5173"
    container_name: minca-inventory
    env_file:
      - .env
    volumes:
      - .:/app
      - /app/node_modules
    environment:
      - VITE_WATCH_USE_POLLING=true
    command: pnpm run dev -- --host 0.0.0.0 --port 5173

The volume mounts sync your local code with the container for hot reload during development.

Production Docker Build

Build the production image:

docker build \
  --build-arg PUBLIC_SUPABASE_URL=https://your-project.supabase.co \
  --build-arg PUBLIC_SUPABASE_ANON_TOKEN=your-anon-key \
  -t trazea:latest .

Run the production container:

docker run -p 80:80 trazea:latest

Access the application at http://localhost

In production, build arguments become baked into the image. For better security, use environment-specific builds or runtime configuration.

Vercel (Recommended)

Trazea is optimized for Vercel deployment with zero configuration:

Connect Repository

Push your code to GitHub, GitLab, or Bitbucket
Import project in Vercel Dashboard
Vercel auto-detects Vite configuration

Configure Environment Variables

In Vercel project settings → Environment Variables:

VITE_SUPABASE_URL=https://your-project.supabase.co
VITE_SUPABASE_ANON_KEY=your-anon-key
VITE_SENTRY_DSN=https://[email protected]/project-id

Set these for all environments: Production, Preview, and Development

Deploy

Click Deploy and Vercel will:

Run pnpm build
Optimize static assets
Deploy to global CDN
Provide preview URLs for PRs

Deployment typically completes in 2-3 minutes.

Other Platforms

Netlify

# Build settings
Build command: pnpm build
Publish directory: dist
Node version: 22

Add environment variables in Netlify dashboard.

Cloudflare Pages

# Build configuration
Build command: pnpm build
Build output directory: dist
Root directory: /

Add environment variables in Pages settings.

AWS Amplify

amplify.yml

version: 1
frontend:
  phases:
    preBuild:
      commands:
        - corepack enable
        - pnpm install
    build:
      commands:
        - pnpm build
  artifacts:
    baseDirectory: dist
    files:
      - '**/*'
  cache:
    paths:
      - node_modules/**/*

Self-Hosted (Nginx)

Build locally:

pnpm build

Copy dist/ to your web server:

nginx.conf

server {
  listen 80;
  server_name your-domain.com;
  root /var/www/trazea/dist;
  index index.html;

  location / {
    try_files $uri $uri/ /index.html;
  }

  # Cache static assets
  location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
    expires 1y;
    add_header Cache-Control "public, immutable";
  }
}

Supabase Setup

Create Supabase Project

Go to supabase.com
Sign in with GitHub
Click New Project
Fill in project details:
- Name: trazea-production
- Database Password: (generate a strong password)
- Region: Select closest to your users

Get API Credentials

Navigate to Settings → API:

You’ll need two values:

Project URL → VITE_SUPABASE_URL
anon public key → VITE_SUPABASE_ANON_KEY

VITE_SUPABASE_URL=https://abcdefghijklmn.supabase.co
VITE_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Never commit the service_role key to version control. The anon key is safe for client-side use.

Run Database Migrations

Execute the SQL migrations to create all required tables:

Go to SQL Editor in Supabase dashboard
Create the main tables:

-- Core tables (simplified - see full schema in repository)
CREATE TABLE usuarios (
  id_usuario UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
  email TEXT UNIQUE NOT NULL,
  aprobado BOOLEAN DEFAULT false,
  rol_id UUID REFERENCES roles(id_rol)
);

CREATE TABLE localizacion (
  id_localizacion UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
  nombre TEXT NOT NULL,
  telefono TEXT
);

CREATE TABLE repuestos (
  id_repuesto UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
  referencia TEXT UNIQUE NOT NULL,
  nombre TEXT NOT NULL,
  tipo TEXT,
  marca TEXT,
  descontinuado BOOLEAN DEFAULT false
);

CREATE TABLE inventario (
  id_inventario UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
  id_repuesto UUID REFERENCES repuestos(id_repuesto),
  id_localizacion UUID REFERENCES localizacion(id_localizacion),
  stock_actual INTEGER DEFAULT 0,
  cantidad_minima INTEGER DEFAULT 0,
  posicion TEXT
);

The full database schema includes 17+ tables. See the repository’s supabase/migrations/ folder for complete SQL.

Configure Authentication

Enable authentication providers:

Go to Authentication → Providers
Enable Email provider
(Optional) Enable Google OAuth:
- Add Google OAuth Client ID
- Add OAuth Client Secret
- Set redirect URL: https://your-project.supabase.co/auth/v1/callback

src/features/auth-login/lib/useLogin.ts

// Google OAuth implementation
const loginWithGoogle = async () => {
  const { error } = await supabase.auth.signInWithOAuth({
    provider: 'google',
    options: {
      redirectTo: `${window.location.origin}/auth-callback`,
      queryParams: {
        access_type: 'offline',
        prompt: 'consent',
      },
    },
  });
};

Set Up Row Level Security (RLS)

Enable RLS on all tables for security:

-- Enable RLS
ALTER TABLE inventario ENABLE ROW LEVEL SECURITY;

-- Users can only see inventory from their assigned locations
CREATE POLICY "Users see own location inventory"
ON inventario
FOR SELECT
USING (
  id_localizacion IN (
    SELECT id_localizacion 
    FROM usuarios_localizacion 
    WHERE id_usuario = auth.uid()
  )
);

-- Similar policies for other tables

Always enable RLS in production. Without RLS, all data is publicly accessible.

Environment Variables Reference

Required Variables

Variable	Description	Example
`VITE_SUPABASE_URL`	Your Supabase project URL	`https://abc.supabase.co`
`VITE_SUPABASE_ANON_KEY`	Supabase anonymous/public key	`eyJhbGciOiJIUzI1Ni...`

Optional Variables

Variable	Description	Default
`VITE_SENTRY_DSN`	Sentry error tracking DSN	`undefined`
`VITE_PUBLIC_ELEVENLABS_API_KEY`	ElevenLabs TTS API key	`undefined`

All environment variables must be prefixed with VITE_ to be accessible in the Vite build.

Supabase Client Configuration

The Supabase client is initialized with these options:

src/shared/api/supabase.ts

import { createClient } from '@supabase/supabase-js';

const supabaseUrl = import.meta.env.VITE_SUPABASE_URL || '';
const supabaseAnonKey = import.meta.env.VITE_SUPABASE_ANON_KEY || '';

if (!supabaseUrl || !supabaseAnonKey) {
  console.error('Missing Supabase environment variables. Please check your .env file.');
}

export const supabase = createClient(supabaseUrl, supabaseAnonKey, {
  auth: {
    autoRefreshToken: true,
    persistSession: true,
    detectSessionInUrl: true,
  },
});

Build Configuration

Vite Configuration

The project uses Vite for blazing-fast builds:

vite.config.ts

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tailwindcss from "@tailwindcss/vite"
import { VitePWA } from 'vite-plugin-pwa'

export default defineConfig({
  plugins: [
    react(),
    tailwindcss(),
    VitePWA({
      registerType: 'autoUpdate',
      manifest: {
        name: 'Trazea',
        short_name: 'Trazea',
        description: 'Sistema de gestión de taller y inventario',
        theme_color: '#ffffff',
      }
    })
  ],
  resolve: {
    alias: {
      "@": path.resolve(__dirname, "./src"),
    },
  },
  build: {
    chunkSizeWarningLimit: 1000,
    rollupOptions: {
      output: {
        manualChunks(id) {
          if (id.includes('react')) return 'react-vendor';
          if (id.includes('@supabase')) return 'supabase-vendor';
          if (id.includes('@radix-ui')) return 'ui-vendor';
          return 'vendor';
        },
      },
    },
  },
})

TypeScript Configuration

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "jsx": "react-jsx",
    "strict": true,
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

Available Scripts

Command	Description
`pnpm dev`	Start development server (port 5173)
`pnpm build`	Build for production
`pnpm preview`	Preview production build locally
`pnpm lint`	Run ESLint on codebase

Build Output

# Production build
pnpm build

# Output structure
dist/
├── assets/
│   ├── index-[hash].js       # Main bundle
│   ├── react-vendor-[hash].js   # React/Router chunks
│   ├── supabase-vendor-[hash].js # Supabase chunks
│   ├── ui-vendor-[hash].js      # Radix UI chunks
│   └── index-[hash].css         # Compiled styles
├── index.html
└── trazea-icon.svg

The build process automatically:

Minifies JavaScript and CSS
Optimizes images and assets
Generates service worker for PWA
Splits code into optimal chunks

Troubleshooting

Build fails with module resolution errors

Clear node_modules and reinstall:

rm -rf node_modules pnpm-lock.yaml
pnpm install

Ensure you’re using Node.js 22+:

node --version  # Should be v22.x.x or higher

Supabase connection issues

Check your environment variables:

# In browser console
console.log(import.meta.env.VITE_SUPABASE_URL)
console.log(import.meta.env.VITE_SUPABASE_ANON_KEY)

Both should be defined. If undefined, check:

.env file exists in project root
Variables start with VITE_ prefix
Development server was restarted after .env changes

Port 5173 already in use

Change the port in package.json:

{
  "scripts": {
    "dev": "vite --host 0.0.0.0 --port 3000"
  }
}

Or set via command line:

pnpm dev -- --port 3000

Hot reload not working

Enable polling in vite.config.ts:

export default defineConfig({
  server: {
    watch: {
      usePolling: true,
    },
  },
})

This is already configured in the project.

Docker build fails

Clear Docker cache and rebuild:

docker-compose down -v
docker system prune -a
docker-compose up --build

Ensure .env file exists before running docker-compose.

Performance Optimization

Production Checklist

Enable HTTPS/SSL certificate
Configure CDN for static assets
Set up database connection pooling in Supabase
Enable Gzip/Brotli compression
Configure caching headers
Set up Sentry for error tracking
Enable RLS on all Supabase tables
Review and optimize database indexes
Set up monitoring and alerting

Vite Build Optimization

The project is already configured with optimal settings:

Code Splitting: Automatic vendor chunks for better caching
Tree Shaking: Removes unused code
Minification: JavaScript and CSS minified
PWA: Service worker for offline functionality
Asset Optimization: Images and fonts optimized

Next Steps

Quickstart Guide

Create your first inventory item and explore core features

Database Schema

Understand the complete data model and relationships

User Management

Configure user roles and permissions

API Reference

Explore Supabase API endpoints and client methods

Get Started

Core Features

Architecture

Guides

Deployment

​System Requirements

Node.js

Package Manager

Database

Git

​Installation Methods

​Prerequisites

​Install pnpm

​Clone and Install

​Configure Environment

​Start Development Server

​Prerequisites

​Configuration

​Development with Docker Compose

​Production Docker Build

​Vercel (Recommended)

​Other Platforms

​Supabase Setup

​Environment Variables Reference

​Required Variables

​Optional Variables

​Supabase Client Configuration

​Build Configuration

​Vite Configuration

​TypeScript Configuration

​Available Scripts

​Build Output

​Troubleshooting

​Performance Optimization

​Production Checklist

​Vite Build Optimization

​Next Steps

Quickstart Guide

Database Schema

User Management

API Reference

Build docs developers (and LLMs) love

System Requirements

Installation Methods

Prerequisites

Install pnpm

Clone and Install

Configure Environment

Start Development Server

Prerequisites

Configuration

Development with Docker Compose

Production Docker Build

Vercel (Recommended)

Other Platforms

Supabase Setup

Environment Variables Reference

Required Variables

Optional Variables

Supabase Client Configuration

Build Configuration

Vite Configuration

TypeScript Configuration

Available Scripts

Build Output

Troubleshooting

Performance Optimization

Production Checklist

Vite Build Optimization

Next Steps