QR Code Generator

A secure, TypeScript-based web application that generates QR codes from URLs or vCard contact information, with optional logo embedding. Features a modern web interface for easy use and a RESTful API for integration. Designed for easy self-hosting and open-source usage.

Features

• Generate QR codes from valid URLs
• Create vCard QR codes with comprehensive contact information
• Optional PNG/SVG logo embedding in QR codes
• Multiple phone numbers, emails, and websites support
• Profile saving and loading with local browser storage
• Responsive web interface with collapsible sections
• RESTful API with comprehensive validation
• Security hardened with rate limiting, input validation, and security headers
• Docker support for easy deployment

Quick Start

Local Development

# Clone the repository
git clone https://github.com/yourusername/qr-code-generator.git
cd qr-code-generator

# Install dependencies
npm install

# Start development server
npm run dev

# Or build and run
npm run build
npm start

The server will start on http://localhost:3000

Docker Deployment

# Build the Docker image
docker build -t qr-code-generator .

# Run the container
docker run -p 3000:3000 qr-code-generator

Environment Variables

• PORT: Server port (default: 3000)

API Documentation

POST /generate-qr

Generate a QR code from a URL with optional logo embedding.

Request:

• Content-Type: multipart/form-data
• Body:
  • url (required): Valid HTTP/HTTPS URL (max 2048 characters)
  • logo (optional): PNG, JPEG, or SVG image file (max 5MB)

Response:

• Content-Type: image/png
• Body: QR code image data

Rate Limit: 100 requests per 15 minutes per IP

Examples:

Using curl:

curl -X POST http://localhost:3000/generate-qr \
  -F "url=https://example.com" \
  -o qr-code.png

With logo:

curl -X POST http://localhost:3000/generate-qr \
  -F "url=https://example.com" \
  -F "[email protected]" \
  -o qr-code-with-logo.png

Using JavaScript/fetch:

const formData = new FormData();
formData.append('url', 'https://example.com');

(async () => {
  const response = await fetch('/generate-qr', {
    method: 'POST',
    body: formData
  });
  const blob = await response.blob();
  // Handle the QR code image
})();

Error Responses:

• 400 Bad Request: Invalid URL or file format/size
• 429 Too Many Requests: Rate limit exceeded
• 500 Internal Server Error: Server error

POST /generate-vcard-qr

Generate a QR code from vCard contact information with optional logo embedding.

Request:

• Content-Type: multipart/form-data
• Body:
  • name (required): Full name
  • contact[] (optional): Phone numbers (multiple allowed)
  • email[] (optional): Email addresses (multiple allowed)
  • company (optional): Company name
  • street (optional): Street address
  • city (optional): City
  • country (optional): Country
  • website[] (optional): Websites (multiple allowed)
  • note (optional): Additional notes
  • title (optional): Job title
  • role (optional): Professional role
  • nickname (optional): Nickname
  • birthday (optional): Date of birth
  • logo (optional): PNG, JPEG, or SVG image file (max 5MB)

Response:

• Content-Type: image/png
• Body: vCard QR code image data

Rate Limit: 100 requests per 15 minutes per IP

Examples:

Using curl:

curl -X POST http://localhost:3000/generate-vcard-qr \
  -F "name=John Doe" \
  -F "contact[]=123-456-7890" \
  -F "email[][email protected]" \
  -o vcard-qr.png

Using JavaScript/fetch:

const formData = new FormData();
formData.append('name', 'John Doe');
formData.append('contact[]', '123-456-7890');
formData.append('email[]', '[email protected]');

(async () => {
  const response = await fetch('/generate-vcard-qr', {
    method: 'POST',
    body: formData
  });
  const blob = await response.blob();
  // Handle the QR code image
})();

Error Responses:

• 400 Bad Request: Invalid input data or file format/size
• 429 Too Many Requests: Rate limit exceeded
• 500 Internal Server Error: Server error

Security Features

• Rate Limiting: 100 requests per 15 minutes per IP
• Input Validation: URL format and length validation
• File Upload Security: Type and size restrictions (PNG/JPEG/SVG, 5MB max)
• Security Headers: Helmet.js with CSP, HSTS, etc.
• Error Handling: Comprehensive error responses without information leakage

Deployment

Using Docker (Recommended)

1. Build the image:

   docker build -t qr-code-generator .

2. Run with environment variables:

   docker run -p 8080:3000 -e PORT=3000 qr-code-generator

Manual Deployment

1. Install Node.js 18+
2. Clone and install dependencies
3. Build the project: npm run build
4. Start with PM2 or similar: pm2 start dist/index.js

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - see LICENSE file for details.