JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 4
  • Score
    100M100P100Q64667F
  • License MIT

A professional Node.js QR code generator library with advanced styling options including gradients, rounded modules, logo support, specialized QR types (vCard, WiFi, Email, SMS, Geo), SVG export, eye customization, and circular eyes

Package Exports

  • @qr-styled/node
  • @qr-styled/node/package.json

Readme

๐ŸŽจ @qr-styled/node

Professional QR Code Generator for Node.js

A powerful Node.js/TypeScript library for generating QR codes with advanced styling options including gradients, rounded modules, and logo support.

๐Ÿ’ก Looking for browser support? Check out @qr-styled/browser for frontend/React/Vue applications.

License: MIT Node.js Version TypeScript

โœจ Features

  • ๐ŸŽจ Customizable Styles: Solid colors or multi-color gradients
  • ๐Ÿ”ท Rounded Modules: Smooth, modern edges with radius control
  • ๐Ÿ–ผ๏ธ Logo Support: Add logos with circular or square backgrounds
  • ๏ฟฝ Specialized QR Types: vCard, WiFi, Email, SMS, Geo location
  • ๐Ÿ“„ SVG Export: Vector format for perfect scalability
  • ๐Ÿ‘๏ธ Eye Customization: Custom colors and shapes (square, rounded, or circular) โœจ
  • ๐Ÿ“ Proper Margins: Standard QR quiet zone support
  • ๐Ÿ“ฆ Multiple Output Formats: PNG, JPEG, SVG, Buffer, Data URL, or Canvas
  • ๐Ÿงฉ Dual Module Support: Works with both ESM (import) and CommonJS (require)
  • ๐Ÿ› ๏ธ CLI & API: Use from command line or programmatically
  • โœ… Built-in Validation: Options validated automatically
  • ๐ŸŽฏ Full TypeScript Support: Complete type definitions included
  • ๐Ÿ”ง Modular Architecture: Clean, maintainable code

๏ฟฝ๏ธ Visual Examples

Advanced Features

vCard Contact QR
vCard Contact
Purple gradient with custom eyes
WiFi Network QR
WiFi Network
Green gradient with rounded modules
Email Contact QR
Email Contact
Pink gradient with eye customization
Custom Eyes QR
Custom Eyes
Red eye accents (square modules)

Basic Styles

Classic Black & White QR
Classic
Traditional black & white
Professional Blue QR
Professional
Blue rounded design
Eco Green QR
Eco
Green with custom eyes
Alert Red QR
Alert
Red attention-grabbing
Creative Purple QR
Creative
Purple artistic

With Logos

Corporate QR with Logo
Corporate
Circle logo, professional blue
Eco Brand QR with Logo
Eco Brand
Square logo, green gradient
Tech Startup QR with Logo
Tech Startup
Circle logo, purple gradient
Restaurant QR with Logo
Restaurant
Square logo, red gradient
### Circular Eyes โœจ NEW

Experience modern QR codes with perfectly smooth circular finder patterns instead of traditional squares.

Simple Circular Eyes QR
Simple Circular
Blue circular eyes with rounded modules
Gradient Circular Eyes QR
Gradient Circular
Pink gradient with circular eyes
High Contrast Circular Eyes QR
High Contrast
Pink circular eyes on dark modules
// Simple circular eyes
const qr = new QRGenerator({
  url: 'https://example.com',
  eyeColor: '#1e40af',
  eyeShape: 'circle', // โœจ NEW: 'square' | 'rounded' | 'circle'
  rounded: true
});

// Gradient with circular eyes
const gradientQR = new QRGenerator({
  url: 'https://example.com',
  gradient: true,
  gradientColors: '#f093fb, #f5576c',
  eyeColor: '#c2185b',
  eyeShape: 'circle',
  rounded: true
});

๐Ÿ’ก Tip: All examples shown above were generated with this library! Check the examples/ directory for source code.

๏ฟฝ๐Ÿ“ฆ Installation

npm install @qr-styled/node

Or for global CLI usage:

npm install -g @qr-styled/node

๐Ÿš€ Quick Start

CLI Usage

# Basic QR code
qr-styled --url "https://github.com"

# QR with gradient
qr-styled --url "https://github.com" --gradient

# QR with logo
qr-styled --url "https://github.com" --logo ./my-logo.png --out my-qr.png

Library Usage

import { QRGenerator, generateQRToFile } from '@qr-styled/node';

// Basic URL QR code
const generator = new QRGenerator({
  url: 'https://github.com',
  gradient: true,
  gradientColors: '#667eea,#764ba2'
});

await generator.generateToFile('qr-output.png');

// vCard contact QR code
const vCardGenerator = new QRGenerator({
  type: 'vcard',
  data: {
    firstName: 'John',
    lastName: 'Doe',
    phone: '+1234567890',
    email: 'john@example.com',
    organization: 'Tech Corp'
  }
});

await vCardGenerator.generateToFile('contact-qr.png');

// WiFi QR code
const wifiGenerator = new QRGenerator({
  type: 'wifi',
  data: {
    ssid: 'MyNetwork',
    password: 'SecurePassword123',
    encryption: 'WPA'
  }
});

await wifiGenerator.generateToFile('wifi-qr.png');

// SVG export for scalability
const svgGenerator = new QRGenerator({
  url: 'https://example.com',
  foregroundColor: '#2196F3',
  eyeColor: '#FF5722',
  eyeRadius: 0.4
});

const svg = await svgGenerator.generateToSVG();
await svgGenerator.generateToSVGFile('qr.svg');

// Helper function
await generateQRToFile(
  {
    url: 'https://github.com',
    foregroundColor: '#2d3748'
  },
  'qr-output.png'
);

CommonJS is also supported:

const { QRGenerator, generateQRToFile } = require('@qr-styled/node');

๐Ÿ“– Documentation

Configuration Options

Basic Options

Option Type Default Description
url string optional URL or text content
type QRDataType 'text' QR data type (url, text, vcard, wifi, email, sms, geo)
data object optional Structured data for specialized types
size number 600 Canvas size in pixels
margin number 4 Quiet zone margin (4 modules standard)
padding number 40 Canvas padding in pixels
foregroundColor string '#000000' QR code color (hex format)
color string deprecated Use foregroundColor instead
rounded boolean true Use rounded module corners
moduleRadius number 0.35 Corner radius (0.0 - 0.5)
cornerRadius number 60 Background corner radius
backgroundColor string '#ffffff' Background color

Eye Customization

Option Type Default Description
eyeColor string '' Custom eye (finder pattern) color
eyeRadius number 0 Eye corner radius (0.0 - 0.5)
eyeShape string 'square' Eye shape: 'square', 'rounded', or 'circle' โœจ

Gradient Options

Option Type Default Description
gradient boolean false Enable gradient
gradientColors string '#FEDA75,#FA7E1E,...' Comma-separated colors
gradientAngle number 45 Angle in degrees (0-360)

Logo Options

Option Type Default Description
logo string '' Logo image path or URL
logoSize number 120 Logo size in pixels
logoPadding number 10 Padding around logo
logoShape 'circle'|'square' 'circle' Logo background shape
logoBackgroundColor string '#ffffff' Logo background color
logoRadius number 20 Corner radius for square logos

Specialized QR Codes

vCard (Contact Card)

{
  type: 'vcard',
  data: {
    firstName: 'John',
    lastName: 'Doe',
    organization: 'Tech Corp',
    title: 'CEO',
    phone: '+1234567890',
    email: 'john@example.com',
    url: 'https://example.com',
    address: '123 Main St',
    city: 'New York',
    state: 'NY',
    zip: '10001',
    country: 'USA'
  }
}

WiFi Network

{
  type: 'wifi',
  data: {
    ssid: 'MyNetwork',
    password: 'SecurePassword123',
    encryption: 'WPA', // 'WPA' | 'WEP' | 'nopass'
    hidden: false      // optional
  }
}

Email

{
  type: 'email',
  data: {
    email: 'contact@example.com',
    subject: 'Hello',    // optional
    body: 'Message text' // optional
  }
}

SMS

{
  type: 'sms',
  data: {
    phone: '+1234567890',
    message: 'Hello!'  // optional
  }
}

Geo Location

{
  type: 'geo',
  data: {
    latitude: 40.7128,
    longitude: -74.0060
  }
}

| logoRadius | number | 20 | Corner radius (for square) |

API Reference

QRGenerator

Main class for generating QR codes.

import { QRGenerator } from '@qr-styled/node';

const generator = new QRGenerator(options);
Methods
generate()

Generates QR code and returns the canvas.

const canvas = await generator.generate();
generateToFile(outputPath)

Generates and saves QR code to file.

await generator.generateToFile('output.png');
generateToBuffer(format)

Generates and returns a Buffer (useful for APIs/servers).

const buffer = await generator.generateToBuffer('png');
// In Express: res.type('png').send(buffer)
generateToDataURL(format)

Generates and returns a Data URL (useful for HTML).

const dataURL = await generator.generateToDataURL('png');
// In HTML: <img src="${dataURL}" />
updateOptions(options)

Updates generator options.

generator.updateOptions({ gradient: true });
await generator.generateToFile('updated.png');

Helper Functions

generateQR(options)

Quickly generate a QR code and return the canvas.

import { generateQR } from '@qr-styled/node';

const canvas = await generateQR({ url: 'https://example.com' });
generateQRToFile(options, outputPath)

Generate and save a QR code to file.

import { generateQRToFile } from '@qr-styled/node';

await generateQRToFile(
  { url: 'https://example.com', gradient: true },
  'output.png'
);

๐Ÿ’ป Usage Examples

Example 1: Instagram Gradient QR

const generator = new QRGenerator({
  url: 'https://instagram.com/your-profile',
  gradient: true,
  gradientColors: '#FEDA75,#FA7E1E,#D62976,#962FBF,#4F5BD5',
  gradientAngle: 45,
  rounded: true
});

await generator.generateToFile('instagram-qr.png');
const generator = new QRGenerator({
  url: 'https://your-company.com',
  foregroundColor: '#1a365d',
  logo: './company-logo.png',
  logoShape: 'square',
  logoRadius: 15,
  backgroundColor: '#f7fafc'
});

await generator.generateToFile('company-qr.png');

Example 3: QR for HTTP API

import express from 'express';
import { QRGenerator } from '@qr-styled/node';

const app = express();

app.get('/qr', async (req, res) => {
  const generator = new QRGenerator({
    url: req.query.url,
    gradient: true,
    gradientColors: '#667eea,#764ba2'
  });

  const buffer = await generator.generateToBuffer('png');
  res.type('png').send(buffer);
});

app.listen(3000);

Example 4: Dynamic QR in Frontend

// In your Node.js server
app.get('/api/qr-data', async (req, res) => {
  const generator = new QRGenerator({
    url: 'https://example.com',
    gradient: true
  });

  const dataURL = await generator.generateToDataURL('png');
  res.json({ qrCode: dataURL });
});

// In your frontend (React, Vue, etc.)
fetch('/api/qr-data')
  .then(res => res.json())
  .then(data => {
    document.getElementById('qr').src = data.qrCode;
  });

๐Ÿ”ง CLI

Global Installation

npm install -g @qr-styled/node

Available Commands

# Available commands
qr-styled [options]
qrgen [options]  # Short alias

CLI Examples

# Basic QR
qr-styled --url "https://github.com"

# Custom filename
qr-styled --url "https://github.com" --out my-code.png

# QR with gradient
qr-styled --url "https://github.com" --gradient --gradientColors "#ff6b6b,#ee5a6f"

# QR with logo
qr-styled --url "https://github.com" --logo ./logo.png --logoShape square

# QR with all options
qr-styled \
  --url "https://github.com" \
  --size 800 \
  --gradient \
  --gradientColors "#667eea,#764ba2" \
  --gradientAngle 90 \
  --logo ./logo.png \
  --logoShape circle \
  --out custom-qr.png

Help

qr-styled --help

๐Ÿ—๏ธ Architecture

src/
โ”œโ”€โ”€ index.ts                    # Main entry point
โ”œโ”€โ”€ lib/
โ”‚   โ”œโ”€โ”€ QRGenerator.ts         # Main class
โ”‚   โ”œโ”€โ”€ renderers/             # Rendering modules
โ”‚   โ”‚   โ”œโ”€โ”€ BackgroundRenderer.ts
โ”‚   โ”‚   โ”œโ”€โ”€ GradientRenderer.ts
โ”‚   โ”‚   โ”œโ”€โ”€ ModuleRenderer.ts
โ”‚   โ”‚   โ””โ”€โ”€ LogoRenderer.ts
โ”‚   โ””โ”€โ”€ utils/                 # Utilities
โ”‚       โ”œโ”€โ”€ types.ts
โ”‚       โ””โ”€โ”€ validators.ts
โ””โ”€โ”€ cli/
    โ””โ”€โ”€ index.ts               # Command line interface

Design Principles

  • Separation of Concerns: Each renderer handles a specific function
  • Composition over Inheritance: Renderers are composed in QRGenerator
  • Input Validation: All options validated before processing
  • Flexible API: Supports multiple output formats
  • Clean Code: Complete TypeScript types and documentation

๐Ÿงช Included Examples

The project includes complete examples you can run:

# Basic examples
npm run example:basic

# Programmatic usage examples
npm run example:programmatic

Examples will generate files in examples/output/ for you to review.

๐Ÿค Framework Integration

Express.js

app.get('/qr/:text', async (req, res) => {
  const generator = new QRGenerator({ url: req.params.text });
  const buffer = await generator.generateToBuffer();
  res.type('png').send(buffer);
});

Next.js (API Route)

// pages/api/qr.ts
import { QRGenerator } from '@qr-styled/node';

export default async function handler(req, res) {
  const { url } = req.query;
  const generator = new QRGenerator({ url });
  const buffer = await generator.generateToBuffer();

  res.setHeader('Content-Type', 'image/png');
  res.send(buffer);
}

Fastify

fastify.get('/qr', async (request, reply) => {
  const generator = new QRGenerator({ url: request.query.url });
  const buffer = await generator.generateToBuffer();

  reply.type('image/png').send(buffer);
});

๐Ÿ› ๏ธ Development

Build

npm run build

Development Mode

npm run dev -- --url "https://example.com"

Run Examples

npm run example:basic
npm run example:programmatic

๐Ÿ“„ License

MIT ยฉ Luis Manuel Yerena Sosa

๐Ÿ™ Contributing

Contributions are welcome! Please:

  1. Fork the project
  2. Create a feature branch (git checkout -b feature/AmazingFeature)
  3. Commit your changes (git commit -m 'Add some AmazingFeature')
  4. Push to the branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

See CONTRIBUTING.md for more details.

๐Ÿ› Report Issues

If you find a bug or have a suggestion, please open an issue.

๐Ÿ“š Resources


โญ If you find this project useful, consider giving it a star on GitHub!