Installation

This guide provides comprehensive instructions for installing and setting up Generador QR Pro for development. Whether you’re contributing to the project or customizing it for your needs, this guide covers everything you need to know.

Prerequisites

Before installing Generador QR Pro, ensure your development environment meets these requirements:

Node.js and npm

Generador QR Pro requires Node.js version 16 or higher.

# Check your current Node.js version
node --version

# Check your npm version
npm --version

If you don’t have Node.js installed, download it from nodejs.org. We recommend using the LTS (Long Term Support) version.

Git

You’ll need Git to clone the repository:

git --version

If Git is not installed, download it from git-scm.com.

Clone the repository

Clone the Generador QR Pro repository to your local machine:

git clone <repository-url>
cd generador_qr

Replace <repository-url> with the actual URL of the repository you’re cloning from.

Install dependencies

Install all required npm packages using your preferred package manager:

npm install

This will install all dependencies listed in package.json, including: Core dependencies:

react@^19.2.0 - React library
react-dom@^19.2.0 - React DOM renderer
qrcode.react@^4.2.0 - QR code generation library
lucide-react@^0.576.0 - Icon library

Development dependencies:

vite@^7.3.1 - Build tool and dev server
@vitejs/plugin-react@^5.1.1 - Vite plugin for React
eslint@^9.39.1 - JavaScript linter
ESLint plugins for React development

Available npm scripts

Generador QR Pro includes several npm scripts for development, building, and maintenance. All scripts are defined in package.json.

Development server

Start the Vite development server with hot module replacement:

npm run dev

What this does:

Starts a local development server (usually on http://localhost:5173)
Enables Hot Module Replacement (HMR) for instant updates
Watches for file changes and rebuilds automatically
Provides detailed error messages in the browser

The development server runs the vite command, which starts the Vite dev server with all optimizations for React development.

Build for production

Create an optimized production build:

npm run build

What this does:

Runs the vite build command
Compiles and bundles all source code
Optimizes assets (minification, tree-shaking, code splitting)
Outputs production-ready files to the dist/ directory

Lint code

Run ESLint to check code quality and consistency:

npm run lint

What this does:

Runs eslint . to check all JavaScript/JSX files
Reports code quality issues, potential bugs, and style violations
Uses the ESLint configuration from eslint.config.js
Includes React-specific rules via eslint-plugin-react-hooks and eslint-plugin-react-refresh

Preview production build

Preview the production build locally:

npm run preview

What this does:

Runs vite preview to serve the production build
Starts a local static server for the dist/ directory
Useful for testing the production build before deployment
Typically runs on http://localhost:4173

You must run npm run build before running npm run preview, as it serves the contents of the dist/ directory.

Project structure

Generador QR Pro follows a standard Vite + React project structure:

generador_qr/
├── public/               # Static assets
│   └── vite.svg         # Vite logo
├── src/                 # Source code
│   ├── assets/          # Project assets
│   │   └── react.svg    # React logo
│   ├── components/      # React components
│   │   └── QRGenerator.jsx  # Main QR generator component
│   ├── App.jsx          # Root App component
│   ├── App.css          # App-specific styles
│   ├── index.css        # Global styles
│   └── main.jsx         # Application entry point
├── index.html           # HTML entry point
├── package.json         # Project metadata and dependencies
├── vite.config.js       # Vite configuration
├── eslint.config.js     # ESLint configuration
└── README.md            # Project README

Key files explained

`src/main.jsx`

The application entry point that renders the root React component:

import React from 'react'
import ReactDOM from 'react-dom/client'
import App from './App.jsx'
import './index.css'

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

`src/App.jsx`

The root component that provides the application structure:

import React from 'react';
import QRGenerator from './components/QRGenerator';

function App() {
  return (
    <div className="container animate-fade-in">
      <header className="header">
        <h1 className="title">Generador QR Pro</h1>
        <p className="subtitle">Crea, personaliza y descarga códigos QR con un diseño premium al instante.</p>
      </header>
      
      <main>
        <QRGenerator />
      </main>
    </div>
  );
}

export default App;

`src/components/QRGenerator.jsx`

The main component containing all QR generation logic. Key features:

State management: Uses React hooks (useState, useRef, useEffect) to manage QR data, customization, and active template
Four templates: URL, WiFi, vCard, and Email with dedicated input forms
Real-time generation: useEffect hook updates QR value whenever data or template changes
Dual rendering: Uses both QRCodeSVG (for display and vector export) and QRCodeCanvas (for high-res PNG export)
Logo support: Allows custom logo upload with automatic Level H error correction
Export functions: handleDownloadPNG() and handleDownloadSVG() for different export formats

`vite.config.js`

Vite configuration with React plugin:

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

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

`index.html`

The HTML entry point that loads the Vite/React application:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Generador QR Pro</title>
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/src/main.jsx"></script>
  </body>
</html>

Development workflow

Here’s the recommended workflow for developing with Generador QR Pro:

Start the development server

npm run dev

This starts the Vite dev server with HMR enabled.

Make your changes

Edit files in the src/ directory. Changes will be reflected instantly in the browser thanks to Vite’s HMR.

Component logic: src/components/QRGenerator.jsx
Styles: src/index.css and src/App.css
App structure: src/App.jsx

Check code quality

npm run lint

Fix any ESLint warnings or errors before committing.

Test production build

npm run build
npm run preview

Verify that your changes work correctly in the production build.

Understanding QR code generation

Generador QR Pro uses the qrcode.react library, which provides two components:

QRCodeSVG

Used for display and vector export:

<QRCodeSVG
  value={qrValue}
  size={280}
  level="H"
  bgColor="#ffffff"
  fgColor="#0f172a"
  includeMargin={true}
  imageSettings={{
    src: logoUrl,
    height: 280 * 0.22,
    width: 280 * 0.22,
    excavate: true,
  }}
/>

QRCodeCanvas

Used for high-resolution PNG export:

<QRCodeCanvas
  value={qrValue}
  size={560}  // 2x for high resolution
  level="H"
  bgColor="#ffffff"
  fgColor="#0f172a"
  includeMargin={true}
  imageSettings={{
    src: logoUrl,
    height: 560 * 0.22,
    width: 560 * 0.22,
    excavate: true,
  }}
/>

The excavate: true option removes QR modules behind the logo to ensure the code remains scannable. This is why Level H error correction (30%) is used with logos.

Environment configuration

Generador QR Pro uses Vite’s built-in environment variable support. If you need to add environment-specific configuration:

Create .env files:
- .env - Default environment variables
- .env.local - Local overrides (git-ignored)
- .env.production - Production-specific variables
Prefix variables with VITE_ to expose them to your app:
```
VITE_API_URL=https://api.example.com
```

Access in your code:

const apiUrl = import.meta.env.VITE_API_URL

Troubleshooting

Module not found errors

If you encounter module resolution errors:

rm -rf node_modules package-lock.json
npm install

Vite port already in use

Vite will automatically use the next available port. Check your terminal for the actual URL, or specify a custom port in vite.config.js:

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

ESLint errors

If ESLint reports errors, you can:

Fix them manually based on the error messages
Use auto-fix for some issues: npx eslint . --fix
Temporarily disable specific rules in eslint.config.js (not recommended)

Build fails

If the production build fails:

Ensure all dependencies are installed: npm install
Check for TypeScript errors (if using TypeScript)
Clear Vite cache: rm -rf node_modules/.vite
Try building again: npm run build

Next steps

Customization

Learn how to customize colors, logos, quality settings, and export options

Components

Explore the QRGenerator component architecture and props API

QR Templates

Learn about URL, WiFi, vCard, and Email QR code templates

Examples

See real-world usage examples and integration patterns

Get Started

QR Templates

Customization

Components

Examples

Installation

Installation

Prerequisites

Node.js and npm

Git

Clone the repository

Install dependencies

Available npm scripts

Development server

Build for production

Lint code

Preview production build

Project structure

Key files explained

`src/main.jsx`

`src/App.jsx`

`src/components/QRGenerator.jsx`

`vite.config.js`

`index.html`

Development workflow

Understanding QR code generation

QRCodeSVG

QRCodeCanvas

Environment configuration

Troubleshooting

Module not found errors

Vite port already in use

ESLint errors

Build fails

Next steps

Customization

Components

QR Templates

Examples

Build docs developers (and LLMs) love

Get Started

QR Templates

Customization

Components

Examples

​Installation

​Prerequisites

​Node.js and npm

​Git

​Clone the repository

​Install dependencies

​Available npm scripts

​Development server

​Build for production

​Lint code

​Preview production build

​Project structure

​Key files explained

​src/main.jsx

​src/App.jsx

​src/components/QRGenerator.jsx

​vite.config.js

​index.html

​Development workflow

​Understanding QR code generation

​QRCodeSVG

​QRCodeCanvas

​Environment configuration

​Troubleshooting

​Module not found errors

​Vite port already in use

​ESLint errors

​Build fails

​Next steps

Customization

Components

QR Templates

Examples

Build docs developers (and LLMs) love

Installation

Prerequisites

Node.js and npm

Git

Clone the repository

Install dependencies

Available npm scripts

Development server

Build for production

Lint code

Preview production build

Project structure

Key files explained

`src/main.jsx`

`src/App.jsx`

`src/components/QRGenerator.jsx`

`vite.config.js`

`index.html`

Development workflow

Understanding QR code generation

QRCodeSVG

QRCodeCanvas

Environment configuration

Troubleshooting

Module not found errors

Vite port already in use

ESLint errors

Build fails

Next steps