Developer Setup
Relevant source files
The following files were used as context for generating this wiki page:This document provides a comprehensive guide for developers to set up, run, test, and build the QR Generator Pro project. The application is a client-side tool built with React and Vite for generating and customizing QR codes. All processing occurs in the browser, and no backend server is required.
The setup process involves cloning the repository, installing dependencies using npm, and running various scripts for development, testing, and production builds. The project is configured with modern development tools like Vite, ESLint, and Vitest to ensure a smooth and efficient development workflow.
Sources: README.md:1-3, 172-174
1. Prerequisites
To build and run this project, your development environment must have the following software installed:
- Node.js: Version
16.xor higher. - npm: (or yarn/pnpm) for package management.
Sources: README.md:46-48
2. Installation and Local Development
Follow these steps to get the development server running on your local machine.
Setup Flow
This diagram illustrates the steps from cloning the repository to running the local development server.
Step-by-Step Instructions
-
Clone the repository:
git clone <repository-url> cd qr-tool-vite -
Install dependencies: This command reads
package.jsonand installs all the required packages listed independenciesanddevDependencies.npm install -
Run the development server: This starts the Vite dev server, which provides features like Hot Module Replacement (HMR).
npm run dev -
Open in browser: Access the application at
http://localhost:5173or the port specified by Vite in your terminal.
Sources: README.md:50-65, package.json:6-7
3. Project Structure
The project follows a standard structure for a Vite-based React application.
qr-tool-vite/
├── public/ # Static assets (e.g., _headers for CSP)
├── src/
│ ├── assets/ # Images, fonts
│ ├── components/ # React components (ExportPanel, QrPreview)
│ ├── hooks/ # Custom React hooks (useTheme, useToast)
│ ├── utils/ # Utility functions (qr-helpers, qr-scanner)
│ ├── App.jsx # Main application component
│ ├── main.jsx # Application entry point
│ └── index.css # Global styles
├── tests/ # Test files (e.g., qr-helpers.test.js)
├── index.html # Main HTML template
├── package.json # Project metadata and dependencies
├── vite.config.js # Vite build configuration
├── tailwind.config.js # Tailwind CSS configuration
└── SECURITY_AUDIT_REPORT.md # Security audit results
Sources: README.md:83-103
4. Technologies and Dependencies
The project is built upon a modern frontend stack.
Core Technologies
| Technology | Version | Description |
|---|---|---|
| React | 19.2.0 | A JavaScript library for building user interfaces. |
| Vite | npm:rolldown-vite@7.2.2 | A next-generation frontend build tool and dev server. |
| Tailwind CSS | 3.4.18 | A utility-first CSS framework for rapid UI development. |
Sources: package.json:15, 29, 32, README.md:106-109
Main Dependencies
These packages are required for the application to function in production.
| Package | Version | Description |
|---|---|---|
@zxing/browser | ^0.1.5 | Library for scanning and decoding QR codes in the browser. |
qrcode.react | ^4.2.0 | React component to generate QR codes. |
react | ^19.2.0 | Core React library. |
react-dom | ^19.2.0 | Serves as the entry point to the DOM and server renderers for React. |
Sources: package.json:14-18
Development Dependencies
These packages are used during development, testing, and building the project.
| Package | Version | Description |
|---|---|---|
@vitejs/plugin-react | ^5.1.0 | Official Vite plugin for React. |
eslint | ^9.39.1 | A tool for identifying and reporting on patterns found in ECMAScript/JavaScript code. |
vitest | ^4.0.8 | A Vite-native testing framework. |
jsdom | ^27.2.0 | A pure-JavaScript implementation of many web standards for use with Node.js. |
tailwindcss | ^3.4.18 | Utility-first CSS framework. |
autoprefixer | ^10.4.22 | PostCSS plugin to parse CSS and add vendor prefixes. |
Sources: package.json:21-32
5. Available Scripts
The package.json file defines several scripts for automating common development tasks.
Development Lifecycle
The following diagram shows the typical workflow using the available npm scripts.
Sources: README.md:162-168, package.json:5-12
Script Details
| Script | Description |
|---|---|
npm run dev | Starts the Vite development server with HMR. |
npm run build | Bundles the application for production into the dist/ directory. |
npm run lint | Runs ESLint to check for code quality and style issues. |
npm run preview | Serves the production build from the dist/ directory for local preview. |
npm run test | Runs all unit tests using Vitest once. |
npm run test:watch | Runs tests in watch mode, re-running them on file changes. |
npm audit | Checks for security vulnerabilities in project dependencies. |
Sources: README.md:162-168, package.json:5-12, SECURITY_AUDIT_REPORT.md:40-41
6. Testing
The project uses Vitest for unit testing. Test files are located in the tests/ directory and alongside source files (e.g., src/App.test.js).
- Unit Tests: The file
tests/qr-helpers.test.jscontains unit tests for utility functions like color manipulation (relLum), input validation (isValidURL,isValidEmail), and ECC level selection (pickECC). - Component Logic Tests: The file
src/App.test.jstests the core logic of QR content generation (generateQRContent) for all supported QR code types.
To run tests, use the following commands:
- Run all tests once:
npm test - Run tests in interactive watch mode:
npm run test:watch
Sources: README.md:77-81, 155-160, package.json:11-12, tests/qr-helpers.test.js, src/App.test.js
7. Security Considerations
Developers should be aware of the project's security practices.
- Dependency Auditing: Regularly run
npm auditto check for vulnerabilities in dependencies. The project aims to maintain 0 vulnerabilities. - Input Validation: All user inputs are strictly validated to prevent malformed QR data. Validation functions can be found in
src/utils/qr-helpers.js. - XSS Protection: The application relies on React's built-in JSX escaping to prevent Cross-Site Scripting (XSS) attacks. No
dangerouslySetInnerHTMLis used. - Content Security Policy (CSP): A strict CSP is defined in
public/_headersto mitigate injection attacks.
For a detailed overview of security measures and audit results, refer to the SECURITY_AUDIT_REPORT.md file.
Sources: SECURITY_AUDIT_REPORT.md:11, 60-63, 89-92, README.md:118-124, src/utils/qr-helpers.js:30-74