Local Development Setup

This guide walks you through setting up VozCraft for local development. VozCraft is built with React 19 and Vite, providing a fast, modern development environment with hot module replacement (HMR).

Prerequisites

Before installing VozCraft, ensure you have the following installed:

Node.js 18+

JavaScript runtime required for npm and build toolsDownload Node.js

Git

Version control system for cloning the repositoryDownload Git

Verify Installation

Check that Node.js and npm are installed:

node --version
# Expected: v18.0.0 or higher

npm --version
# Expected: 8.0.0 or higher

Recommended versions:

Node.js: 18.x, 20.x, or 22.x LTS
npm: 8.x or higher (comes with Node.js)

Installation Steps

Clone the repository

Clone the VozCraft source code from GitHub:

git clone https://github.com/mateoRiosdev/vozcraft.git
cd vozcraft

Or if you’re working with a specific branch:

git clone -b main https://github.com/mateoRiosdev/vozcraft.git
cd vozcraft

Replace mateoRiosdev/vozcraft with the actual repository URL if different.

Install dependencies

Install all required npm packages:

npm install

This installs all dependencies listed in package.json:

package.json

{
  "dependencies": {
    "react": "^19.2.4",
    "react-dom": "^19.2.4"
  },
  "devDependencies": {
    "@eslint/js": "^9.39.2",
    "@types/react": "^19.2.13",
    "@types/react-dom": "^19.2.3",
    "@vitejs/plugin-react": "^5.1.3",
    "eslint": "^9.39.2",
    "eslint-plugin-react-hooks": "^7.0.1",
    "eslint-plugin-react-refresh": "^0.5.0",
    "globals": "^17.3.0",
    "vite": "^7.3.1"
  }
}

Installation time: Typically takes 1-3 minutes depending on your internet connection.

Start the development server

Launch the Vite development server:

npm run dev

You should see output similar to:

VITE v7.3.1  ready in 423 ms

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

Vite uses port 5173 by default. If this port is busy, Vite will automatically try the next available port (5174, 5175, etc.).

Open in browser

Navigate to the local development URL:

http://localhost:5173

You should see the VozCraft interface load in your browser.

The page will automatically reload when you make changes to the source code (Hot Module Replacement).

Project Structure

Once installed, your VozCraft directory will look like this:

vozcraft/
├── public/              # Static assets
│   ├── icons.svg        # SVG icon sprite
│   ├── logo.png         # App logo (5 KB)
│   ├── logotipo.png     # PWA icon (205 KB)
│   └── manifest.json    # PWA manifest
├── src/                 # Source code
│   ├── App.jsx          # Main application component (1007+ lines)
│   └── main.jsx         # React entry point
├── .gitignore
├── eslint.config.js     # ESLint configuration
├── index.html           # HTML entry point
├── package.json         # Dependencies and scripts
├── package-lock.json    # Locked dependency versions
├── README.md
└── vite.config.js       # Vite configuration

Key Files

src/App.jsx - Main Application

The primary React component containing all VozCraft functionality:

Lines 1-53: Configuration constants (voices, moods, speeds)
Lines 108-139: GenderToggle component
Lines 141-209: Custom Select component
Lines 211-269: RenameModal component
Lines 271-373: AudioPlayer component
Lines 375-490: HistoryItem component
Lines 492-554: Audio generation function
Lines 556-571: WAV encoding function
Lines 610-1040+: Main VozCraft component

Key features implemented:

Web Speech API integration
Audio generation and download
History management
Multi-language support (Spanish/English)
Dark/light theme
22 language variants
8 mood presets
2 gender options

src/main.jsx - Entry Point

React application initialization:

src/main.jsx

import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import App from './App.jsx'

createRoot(document.getElementById('root')).render(
  <StrictMode>
    <App />
  </StrictMode>,
)

Mounts React app to #root div
Enables StrictMode for development warnings
Single-component architecture (entire app in App.jsx)

index.html - HTML Template

Base HTML file with PWA integration:

index.html

<!DOCTYPE html>
<html lang="es">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>VozCraft - TTS</title>
    <meta name="description" content="Texto a voz con IA" />
    <link rel="icon" type="image/png" href="/logo.png" />
    <link rel="manifest" href="/manifest.json" />
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/src/main.jsx"></script>
  </body>
</html>

Minimal HTML structure
PWA manifest link
Module script for Vite entry point

vite.config.js - Build Configuration

Vite build and development configuration:

vite.config.js

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

// https://vite.dev/config/
export default defineConfig({
  plugins: [react()],
})

What this enables:

React Fast Refresh (HMR)
JSX transformation
Optimized production builds
ES modules in development

This is the minimal Vite configuration. Additional options can be added for custom build behavior.

package.json - Project Configuration

Project metadata and dependencies:

package.json

{
  "name": "vite-react-starter",
  "private": true,
  "version": "0.0.0",
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "lint": "eslint .",
    "preview": "vite preview"
  },
  "dependencies": {
    "react": "^19.2.4",
    "react-dom": "^19.2.4"
  },
  "devDependencies": {
    "@eslint/js": "^9.39.2",
    "@types/react": "^19.2.13",
    "@types/react-dom": "^19.2.3",
    "@vitejs/plugin-react": "^5.1.3",
    "eslint": "^9.39.2",
    "eslint-plugin-react-hooks": "^7.0.1",
    "eslint-plugin-react-refresh": "^0.5.0",
    "globals": "^17.3.0",
    "vite": "^7.3.1"
  }
}

Key details:

"type": "module": Enables ES modules in Node.js
"private": true: Prevents accidental npm publish
Zero external runtime dependencies (only React)

Available Scripts

VozCraft includes several npm scripts for development and production:

npm run dev
npm run build
npm run preview
npm run lint

Starts the development server with hot module replacement:

npm run dev

What it does:

Starts Vite dev server on http://localhost:5173
Enables Hot Module Replacement (HMR)
Provides source maps for debugging
Watches for file changes
Fast refresh for React components

Options:

# Expose to network
npm run dev -- --host

# Use specific port
npm run dev -- --port 3000

# Open browser automatically
npm run dev -- --open

Builds the application for production:

npm run build

What it does:

Compiles and bundles all code
Minifies JavaScript and CSS
Optimizes assets
Generates dist/ directory
Tree-shakes unused code

Output location: dist/See the Building Guide for details.

Previews the production build locally:

npm run build
npm run preview

What it does:

Serves the dist/ directory
Simulates production environment
Useful for testing before deployment

Default URL: http://localhost:4173

Runs ESLint to check code quality:

npm run lint

What it checks:

React best practices
React Hooks rules
React Refresh compatibility
JavaScript syntax errors

Fix automatically:

npm run lint -- --fix

Development Workflow

Making Changes

Start dev server

npm run dev

Edit source files

Modify src/App.jsx or other source files. Changes are reflected immediately in the browser.

Check browser console

Open DevTools (F12) to see logs, errors, or warnings.

Test changes

Interact with the application to verify your changes work correctly.

Hot Module Replacement (HMR)

Vite provides instant updates without full page reload:

src/App.jsx

// Change this:
const ANIMOS = [
  { label: 'Neutral', pitch: 1.00, ... },
  // ...
];

// To this:
const ANIMOS = [
  { label: 'Neutral', pitch: 1.00, ... },
  { label: 'Excited', pitch: 1.45, rateMulti: 1.35, volume: 1.00, ... },
  // ...
];

Save the file → Browser updates immediately without losing state.

HMR preserves:

Component state
Form inputs
Scroll position
Open modals

This makes development much faster than traditional full-page reloads.

Troubleshooting

Port 5173 already in use

Error:

Error: listen EADDRINUSE: address already in use :::5173

Solutions:

Kill the process using port 5173:

# macOS/Linux
lsof -ti:5173 | xargs kill -9

# Windows
netstat -ano | findstr :5173
taskkill /PID <PID> /F

Or use a different port:

npm run dev -- --port 3000

Module not found errors

Error:

Error: Cannot find module 'react'

Solution: Reinstall dependencies:

rm -rf node_modules package-lock.json
npm install

Build fails with out of memory

Error:

JavaScript heap out of memory

Solution: Increase Node.js memory limit:

export NODE_OPTIONS="--max-old-space-size=4096"
npm run build

Or add to package.json:

"scripts": {
  "build": "node --max-old-space-size=4096 ./node_modules/.bin/vite build"
}

Hot reload not working

Possible causes:

File watchers limit reached (Linux)
Editor saving to temp file first
Files outside src/ directory

Solutions:

Increase file watchers (Linux):

echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

Configure editor to save directly:

VS Code: Disable “Hot Exit”
WebStorm: Enable “Safe Write”

Web Speech API not working

Possible causes:

Browser doesn’t support Web Speech API
No system voices installed
Microphone permission issues

Solutions:

Check browser support:

if (!('speechSynthesis' in window)) {
  console.error('Web Speech API not supported');
}

Check available voices:

const voices = window.speechSynthesis.getVoices();
console.log(voices);

Try Chrome or Firefox (best support)

Environment Variables

Vite supports environment variables for configuration: Create .env.local:

.env.local

# Development settings
VITE_APP_NAME=VozCraft
VITE_API_URL=http://localhost:3000
VITE_ENABLE_ANALYTICS=false

Access in code:

const appName = import.meta.env.VITE_APP_NAME;
const apiUrl = import.meta.env.VITE_API_URL;

Important:

Variables must start with VITE_
Don’t commit .env.local to version control
Use .env.example for documentation

IDE Setup

VS Code

Recommended extensions:

.vscode/extensions.json

{
  "recommendations": [
    "dbaeumer.vscode-eslint",
    "esbenp.prettier-vscode",
    "bradlc.vscode-tailwindcss",
    "dsznajder.es7-react-js-snippets"
  ]
}

Settings:

.vscode/settings.json

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "eslint.validate": [
    "javascript",
    "javascriptreact"
  ]
}

WebStorm / IntelliJ IDEA

Enable ESLint: Settings → Languages & Frameworks → JavaScript → Code Quality Tools → ESLint
Set Node.js interpreter: Settings → Languages & Frameworks → Node.js
Enable automatic imports: Settings → Editor → General → Auto Import

Architecture

Development

Local Development Setup

Local Development Setup

Prerequisites

Node.js 18+

Git

Verify Installation

Installation Steps

Project Structure

Key Files

Available Scripts

Development Workflow

Making Changes

Hot Module Replacement (HMR)

Troubleshooting

Environment Variables

IDE Setup

VS Code

WebStorm / IntelliJ IDEA

Next Steps

Building for Production

Deployment Guide

​Local Development Setup

​Prerequisites

Node.js 18+

Git

​Verify Installation

​Installation Steps

​Project Structure

​Key Files

​Available Scripts

​Development Workflow

​Making Changes

​Hot Module Replacement (HMR)

​Troubleshooting

​Environment Variables

​IDE Setup

​VS Code

​WebStorm / IntelliJ IDEA

​Next Steps

Building for Production

Deployment Guide

​Related Resources

Local Development Setup

Prerequisites

Verify Installation

Installation Steps

Project Structure

Key Files

Available Scripts

Development Workflow

Making Changes

Hot Module Replacement (HMR)

Troubleshooting

Environment Variables

IDE Setup

VS Code

WebStorm / IntelliJ IDEA

Next Steps

Related Resources