Build and Deployment
Relevant source files
The following files were used as context for generating this wiki page:
This document outlines the build system, dependencies, and deployment process for the QR-Tool project. The application is a client-side single-page application built with React and Vite, designed to be deployed as a set of static files. No backend server is required for the application to function, as all processing occurs in the user's browser.
The build process is managed through NPM scripts, leveraging Vite for development and production bundling. The final output is an optimized set of static HTML, CSS, and JavaScript files located in the dist/ directory, ready for hosting on any static web host.
Sources: README.md:1-5, 203-205, package.json
Core Technologies
The project's build and development toolchain is centered around modern JavaScript technologies.
| Technology | Version | Description |
|---|---|---|
| React | 19.2.0 | The core UI framework for building the user interface. |
| Vite | npm:rolldown-vite@7.2.2 | The build tool and development server, providing fast bundling and hot module replacement (HMR). The project specifically uses the rolldown-vite fork. |
| Tailwind CSS | 3.4.18 | A utility-first CSS framework used for styling the application. |
| Vitest | 4.0.8 | The testing framework used for running unit tests. |
| ESLint | 9.39.1 | A tool for identifying and reporting on patterns found in ECMAScript/JavaScript code. |
Sources: package.json:13-29, README.md:92-99
NPM Scripts
The project's lifecycle (development, building, testing, and linting) is managed through a set of predefined NPM scripts in package.json.
| Script | Command | Description |
|---|---|---|
dev | vite | Starts the Vite development server on http://localhost:5173 with HMR. |
build | vite build | Creates a production-ready build in the dist/ directory. |
preview | vite preview | Serves the production build from the dist/ directory for local preview. |
lint | eslint . | Runs ESLint to analyze the codebase for potential errors and style issues. |
test | vitest run | Executes all unit tests once using Vitest. |
test:watch | vitest | Runs tests in watch mode, re-running them on file changes. |
Sources: package.json:6-11, README.md:46-65, 160-165
Code Snippet: scripts in package.json
"scripts": {
"dev": "vite",
"build": "vite build",
"lint": "eslint .",
"preview": "vite preview",
"test": "vitest run",
"test:watch": "vitest"
},
Sources: package.json:6-12
Development Environment
To run the application in a development environment, clone the repository, install the dependencies, and run the dev script.
- Clone repository:
git clone <repository-url> - Install dependencies:
npm install - Run development server:
npm run dev
This process starts the Vite development server, which provides features like Hot Module Replacement (HMR) for a fast and efficient development workflow. The application will be accessible at http://localhost:5173 by default.
Sources: README.md:37-50
The diagram below illustrates the local development flow.
This diagram shows how the Vite development server facilitates a rapid development cycle with Hot Module Replacement.
Sources: package.json:7, README.md:46-48
Production Build Process
Executing npm run build triggers Vite to create an optimized production build. The process involves transpiling JSX, bundling JavaScript modules, processing and purging CSS with Tailwind CSS, and minifying all assets.
The entry point for the application is index.html, which references the main JavaScript module at /src/main.jsx. Vite uses this entry point to build the dependency graph and generate the final assets.
The output is placed in the dist/ directory, which contains the static files ready for deployment.
Sources: README.md:52-55, index.html:21, package.json:8
The following diagram visualizes the production build process.
This diagram shows how Vite processes source files and static assets to generate the optimized dist directory for production.
Sources: README.md:52-55, 68-85, package.json:8
Deployment
The QR-Tool is a client-side application and can be deployed to any static hosting provider (e.g., Netlify, Vercel, GitHub Pages). The deployment process consists of serving the contents of the dist/ directory generated by the npm run build command.
Security Headers
For a production deployment, it is critical to configure security headers. The project includes a public/_headers file, which is intended for platforms like Netlify that automatically apply headers based on this file's content. This file configures the Content Security Policy (CSP) and other security-related HTTP headers to enhance the application's security posture.
The configured CSP is strict, allowing resources only from 'self', with specific exceptions for images (blob: data:) and inline styles ('unsafe-inline'), which are necessary for the QR code generation library.
Sources: README.md:70, 107-109, SECURITY_AUDIT_REPORT.md:100-110
Code Snippet: public/_headers
Content-Security-Policy: default-src 'self'; img-src 'self' blob: data:; style-src 'self' 'unsafe-inline'; script-src 'self'; connect-src 'self'
Referrer-Policy: strict-origin-when-cross-origin
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
Permissions-Policy: camera=(), microphone=(), geolocation=(), payment=()
X-XSS-Protection: 1; mode=block
This configuration helps mitigate risks such as Cross-Site Scripting (XSS) by restricting where content can be loaded from.
Sources: SECURITY_AUDIT_REPORT.md:101-107
Testing
The project uses Vitest for unit testing. Tests are located in the tests/ directory and alongside source files. They can be run via the npm test or npm run test:watch commands. The testing environment is configured to use jsdom to simulate a browser environment for component testing.