> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/MateoRiosdev/Free-TTS-VozCraft/llms.txt
> Use this file to discover all available pages before exploring further.

# Local Development Setup

> Install and run VozCraft locally for development with React 19 + Vite

# 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:

<CardGroup cols={2}>
  <Card title="Node.js 18+" icon="node-js">
    JavaScript runtime required for npm and build tools

    [Download Node.js](https://nodejs.org/)
  </Card>

  <Card title="Git" icon="git">
    Version control system for cloning the repository

    [Download Git](https://git-scm.com/)
  </Card>
</CardGroup>

### Verify Installation

Check that Node.js and npm are installed:

```bash theme={null}
node --version
# Expected: v18.0.0 or higher

npm --version
# Expected: 8.0.0 or higher
```

<Info>
  **Recommended versions:**

  * Node.js: 18.x, 20.x, or 22.x LTS
  * npm: 8.x or higher (comes with Node.js)
</Info>

## Installation Steps

<Steps>
  <Step title="Clone the repository">
    Clone the VozCraft source code from GitHub:

    ```bash theme={null}
    git clone https://github.com/mateoRiosdev/vozcraft.git
    cd vozcraft
    ```

    Or if you're working with a specific branch:

    ```bash theme={null}
    git clone -b main https://github.com/mateoRiosdev/vozcraft.git
    cd vozcraft
    ```

    <Note>
      Replace `mateoRiosdev/vozcraft` with the actual repository URL if different.
    </Note>
  </Step>

  <Step title="Install dependencies">
    Install all required npm packages:

    ```bash theme={null}
    npm install
    ```

    This installs all dependencies listed in `package.json`:

    ```json package.json theme={null}
    {
      "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"
      }
    }
    ```

    <Tip>
      **Installation time:** Typically takes 1-3 minutes depending on your internet connection.
    </Tip>
  </Step>

  <Step title="Start the development server">
    Launch the Vite development server:

    ```bash theme={null}
    npm run dev
    ```

    You should see output similar to:

    ```plaintext theme={null}
    VITE v7.3.1  ready in 423 ms

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

    <Info>
      Vite uses port **5173** by default. If this port is busy, Vite will automatically try the next available port (5174, 5175, etc.).
    </Info>
  </Step>

  <Step title="Open in browser">
    Navigate to the local development URL:

    ```
    http://localhost:5173
    ```

    You should see the VozCraft interface load in your browser.

    <Tip>
      The page will automatically reload when you make changes to the source code (Hot Module Replacement).
    </Tip>
  </Step>
</Steps>

## Project Structure

Once installed, your VozCraft directory will look like this:

```plaintext theme={null}
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

<Accordion title="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
</Accordion>

<Accordion title="src/main.jsx - Entry Point">
  React application initialization:

  ```javascript src/main.jsx theme={null}
  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)
</Accordion>

<Accordion title="index.html - HTML Template">
  Base HTML file with PWA integration:

  ```html index.html theme={null}
  <!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
</Accordion>

<Accordion title="vite.config.js - Build Configuration">
  Vite build and development configuration:

  ```javascript vite.config.js theme={null}
  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

  <Note>
    This is the minimal Vite configuration. Additional options can be added for custom build behavior.
  </Note>
</Accordion>

<Accordion title="package.json - Project Configuration">
  Project metadata and dependencies:

  ```json package.json theme={null}
  {
    "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)
</Accordion>

## Available Scripts

VozCraft includes several npm scripts for development and production:

<Tabs>
  <Tab title="npm run dev">
    Starts the development server with hot module replacement:

    ```bash theme={null}
    npm run dev
    ```

    **What it does:**

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

    **Options:**

    ```bash theme={null}
    # Expose to network
    npm run dev -- --host

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

    # Open browser automatically
    npm run dev -- --open
    ```
  </Tab>

  <Tab title="npm run build">
    Builds the application for production:

    ```bash theme={null}
    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](/technical/building) for details.
  </Tab>

  <Tab title="npm run preview">
    Previews the production build locally:

    ```bash theme={null}
    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](http://localhost:4173)
  </Tab>

  <Tab title="npm run lint">
    Runs ESLint to check code quality:

    ```bash theme={null}
    npm run lint
    ```

    **What it checks:**

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

    **Fix automatically:**

    ```bash theme={null}
    npm run lint -- --fix
    ```
  </Tab>
</Tabs>

## Development Workflow

### Making Changes

<Steps>
  <Step title="Start dev server">
    ```bash theme={null}
    npm run dev
    ```
  </Step>

  <Step title="Edit source files">
    Modify `src/App.jsx` or other source files. Changes are reflected immediately in the browser.
  </Step>

  <Step title="Check browser console">
    Open DevTools (F12) to see logs, errors, or warnings.
  </Step>

  <Step title="Test changes">
    Interact with the application to verify your changes work correctly.
  </Step>
</Steps>

### Hot Module Replacement (HMR)

Vite provides instant updates without full page reload:

```jsx src/App.jsx theme={null}
// 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.

<Tip>
  **HMR preserves:**

  * Component state
  * Form inputs
  * Scroll position
  * Open modals

  This makes development much faster than traditional full-page reloads.
</Tip>

## Troubleshooting

<Accordion title="Port 5173 already in use">
  **Error:**

  ```plaintext theme={null}
  Error: listen EADDRINUSE: address already in use :::5173
  ```

  **Solutions:**

  1. Kill the process using port 5173:

  ```bash theme={null}
  # macOS/Linux
  lsof -ti:5173 | xargs kill -9

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

  2. Or use a different port:

  ```bash theme={null}
  npm run dev -- --port 3000
  ```
</Accordion>

<Accordion title="Module not found errors">
  **Error:**

  ```plaintext theme={null}
  Error: Cannot find module 'react'
  ```

  **Solution:**
  Reinstall dependencies:

  ```bash theme={null}
  rm -rf node_modules package-lock.json
  npm install
  ```
</Accordion>

<Accordion title="Build fails with out of memory">
  **Error:**

  ```plaintext theme={null}
  JavaScript heap out of memory
  ```

  **Solution:**
  Increase Node.js memory limit:

  ```bash theme={null}
  export NODE_OPTIONS="--max-old-space-size=4096"
  npm run build
  ```

  Or add to `package.json`:

  ```json theme={null}
  "scripts": {
    "build": "node --max-old-space-size=4096 ./node_modules/.bin/vite build"
  }
  ```
</Accordion>

<Accordion title="Hot reload not working">
  **Possible causes:**

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

  **Solutions:**

  1. Increase file watchers (Linux):

  ```bash theme={null}
  echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
  sudo sysctl -p
  ```

  2. Configure editor to save directly:

  * VS Code: Disable "Hot Exit"
  * WebStorm: Enable "Safe Write"
</Accordion>

<Accordion title="Web Speech API not working">
  **Possible causes:**

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

  **Solutions:**

  1. Check browser support:

  ```javascript theme={null}
  if (!('speechSynthesis' in window)) {
    console.error('Web Speech API not supported');
  }
  ```

  2. Check available voices:

  ```javascript theme={null}
  const voices = window.speechSynthesis.getVoices();
  console.log(voices);
  ```

  3. Try Chrome or Firefox (best support)
</Accordion>

## Environment Variables

Vite supports environment variables for configuration:

Create `.env.local`:

```bash .env.local theme={null}
# Development settings
VITE_APP_NAME=VozCraft
VITE_API_URL=http://localhost:3000
VITE_ENABLE_ANALYTICS=false
```

Access in code:

```javascript theme={null}
const appName = import.meta.env.VITE_APP_NAME;
const apiUrl = import.meta.env.VITE_API_URL;
```

<Warning>
  **Important:**

  * Variables must start with `VITE_`
  * Don't commit `.env.local` to version control
  * Use `.env.example` for documentation
</Warning>

## IDE Setup

### VS Code

Recommended extensions:

```json .vscode/extensions.json theme={null}
{
  "recommendations": [
    "dbaeumer.vscode-eslint",
    "esbenp.prettier-vscode",
    "bradlc.vscode-tailwindcss",
    "dsznajder.es7-react-js-snippets"
  ]
}
```

Settings:

```json .vscode/settings.json theme={null}
{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "eslint.validate": [
    "javascript",
    "javascriptreact"
  ]
}
```

### WebStorm / IntelliJ IDEA

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

## Next Steps

<CardGroup cols={2}>
  <Card title="Building for Production" icon="hammer" href="/technical/building">
    Learn how to build and optimize VozCraft
  </Card>

  <Card title="Deployment Guide" icon="rocket" href="/technical/deployment">
    Deploy VozCraft to various hosting platforms
  </Card>
</CardGroup>

## Related Resources

* [Vite Documentation](https://vitejs.dev/)
* [React 19 Documentation](https://react.dev/)
* [Node.js Downloads](https://nodejs.org/)
* [Git Documentation](https://git-scm.com/doc)