qr-code-generator

name	qr-code-generator
description	Generate QR codes via the web UI or REST API. Supports URL, WiFi, vCard, and plain text. Outputs SVG and PNG. Includes logo embedding and bulk CSV generation.
triggers	["generate qr","create qr code","qr code for","bulk qr","qr with logo","wifi qr","vcard qr"]

qr-code-generator Skill

When to use

Use this skill when you need to:

• Generate a QR code for a URL, WiFi network, contact card, or arbitrary text
• Embed a brand logo into a QR code
• Generate dozens or hundreds of QR codes from a CSV in one batch
• Download QR codes as SVG (for print) or PNG (for digital)
• Integrate QR generation into a pipeline via the REST API

Prerequisites

Server running at http://localhost:3000. Start with:

pnpm --filter server dev

Or via Docker:

docker compose up -d

Health check:

curl http://localhost:3000/api/health

Quick start

Generate a URL QR code (SVG):

curl -s -X POST http://localhost:3000/api/generate \
  -H 'Content-Type: application/json' \
  -d '{"type":"url","data":{"url":"https://example.com"},"format":"svg"}' \
  | jq -r '.svg' > qrcode.svg

Usage patterns

URL QR code

curl -s -X POST http://localhost:3000/api/generate \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "url",
    "data": { "url": "https://example.com" },
    "style": {
      "fgColor": "#000000",
      "bgColor": "#ffffff",
      "errorCorrection": "M",
      "margin": 4,
      "width": 400
    },
    "format": "svg"
  }' | jq -r '.svg' > url.svg

WiFi QR code

curl -s -X POST http://localhost:3000/api/generate \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "wifi",
    "data": {
      "ssid": "OfficeNetwork",
      "password": "supersecret",
      "security": "WPA",
      "hidden": false
    },
    "format": "svg"
  }' | jq -r '.svg' > wifi.svg

Encoded string produced: WIFI:T:WPA;S:OfficeNetwork;P:supersecret;H:false;;

vCard QR code

curl -s -X POST http://localhost:3000/api/generate \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "vcard",
    "data": {
      "firstName": "Jane",
      "lastName": "Smith",
      "org": "Acme Corp",
      "title": "Product Manager",
      "phone": "[phone]",
      "email": "[e-mail]",
      "url": "https://acme.com"
    },
    "style": { "errorCorrection": "Q" },
    "format": "svg"
  }' | jq -r '.svg' > vcard.svg

PNG output

curl -s -X POST http://localhost:3000/api/generate \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "url",
    "data": { "url": "https://example.com" },
    "style": { "width": 512 },
    "format": "png"
  }' | jq -r '.dataUrl' | sed 's/data:image\/png;base64,//' | base64 -d > qrcode.png

Logo embedding

LOGO_B64=$(base64 -i logo.png)

curl -s -X POST http://localhost:3000/api/generate \
  -H 'Content-Type: application/json' \
  -d "{
    \"type\": \"url\",
    \"data\": { \"url\": \"https://example.com\" },
    \"style\": { \"errorCorrection\": \"H\" },
    \"logo\": \"data:image/png;base64,$LOGO_B64\",
    \"format\": \"svg\"
  }" | jq -r '.svg' > branded.svg

Logo is auto-centered at 20% of QR width. Error correction is forced to H when a logo is present.

Bulk generation from CSV

# codes.csv:
# data,filename,fgColor
# https://example.com,homepage,#000000
# https://example.com/about,about,#1d4ed8

curl -X POST http://localhost:3000/api/bulk \
  -F "csv=@codes.csv" \
  --output qrcodes.zip

unzip qrcodes.zip -d ./qrcodes/

Bulk generation from JSON

curl -X POST http://localhost:3000/api/bulk \
  -H 'Content-Type: application/json' \
  -d '{
    "codes": [
      {"data": "https://a.com", "filename": "a"},
      {"data": "https://b.com", "filename": "b", "fgColor": "#1d4ed8"}
    ],
    "format": "svg"
  }' --output qrcodes.zip

API reference

Method	Path	Description
POST	/api/generate	Generate a single QR code
POST	/api/bulk	Batch generate from CSV or JSON array, returns ZIP
GET	/api/templates	List saved style templates
POST	/api/templates	Save a style template
DELETE	/api/templates/:id	Delete a template
GET	/api/health	Server health check

POST /api/generate request body

Field	Type	Default	Description
type	string	required	url, text, wifi, vcard
data	object	required	Type-specific payload
style.fgColor	string	#000000	Foreground hex color
style.bgColor	string	#ffffff	Background hex color
style.errorCorrection	string	M	L, M, Q, or H
style.margin	number	4	Quiet zone in modules
style.width	number	400	Output size in pixels
logo	string	null	null
format	string	svg	svg or png

POST /api/generate response

Field	Type	Description
svg	string	SVG markup (format=svg only)
dataUrl	string	data:image/... base64 URL
size	number	Rendered pixel size

Error correction guide

Level	Recovery	When to use
L	7%	Clean print environments, smallest code
M	15%	Default, general purpose
Q	25%	Outdoor/industrial, long URLs
H	30%	Required when embedding a logo

Behavior notes

• Logo embedding always upgrades error correction to H, regardless of the style setting
• Transparent background is only supported in SVG output; PNG always has a background
• Bulk endpoint rejects requests over MAX_BULK_CODES (default 500)
• All hex colors must be in #rrggbb format
• vCard data over ~300 characters: use error correction Q or H for reliability
• History is stored in browser localStorage only; the server is stateless

Troubleshooting

QR code does not scan

• Check foreground/background contrast (minimum 4:1 ratio recommended)
• With logo: ensure error correction is H and logo size is below 30%
• Inverted codes (light on dark) may not scan on all devices

Bulk job returns 400

• CSV has more than MAX_BULK_CODES rows
• Required columns data and filename are missing

Logo not appearing in SVG

• Logo must be provided as a base64 data URL (data:image/png;base64,... or data:image/svg+xml;base64,...)
• Maximum logo size: 500 KB before encoding