QR Code Styling CLI

Command line utility for generating QR codes with customizable styling, based on @liquid-js/qr-code-styling.

Installation

npm install @liquid-js/qr-code-styling-cli

Usage

Command Line

qr-code-styling --config <config.json> --out ./codes

Options:
      --version        Show version number                                                                     [boolean]
      --help           Show help                                                                               [boolean]
  -c, --config         json config file                                                              [string] [required]
  -f, --format         output format             [string] [choices: "svg", "png", "jpg", "webp", "pdf"] [default: "svg"]
  -s, --size           raster output size                                                       [number] [default: 1200]
  -o, --out            output directory                                                              [string] [required]
  -d, --data           qr code data                                                                              [array]
  -t, --template-data  format config using {{ handlebars }}                                                     [string]

🌟 Hint: the best way to prepare the config file is using the Styled QR Generator

Example Configuration

{
    "$schema": "./node_modules/@liquid-js/qr-code-styling-cli/lib/schema.json",
    "data": [
        "https://www.example.com/",
        "https://www.example.com/my-awesome-blog"
    ],
    "image": "./logo.svg",
    "imageOptions": {
        "mode": "center",
        "imageSize": 0.9,
        "margin": 1
    },
    "shape": "circle",
    "qrOptions": {
        "errorCorrectionLevel": "Q"
    },
    "dotsOptions": {
        "type": "square",
        "gradient": {
            "type": "radial",
            "rotation": 0,
            "colorStops": [
                {
                    "offset": 0,
                    "color": "#69548d"
                },
                {
                    "offset": 1,
                    "color": "#b7396b"
                }
            ]
        }
    },
    "cornersSquareOptions": {
        "type": "outpoint"
    },
    "cornersDotOptions": {
        "type": "outpoint"
    },
    "backgroundOptions": {
        "margin": 3,
        "round": 1,
        "color": "#fff"
    },
    "plugins": [
        {
            "plugin": "@liquid-js/qr-code-styling/border-plugin",
            "round": 1,
            "size": 60,
            "color": "#b7396b",
            "text": {
                "font": "./custom-font.ttf",
                "color": "#ffffff",
                "size": 27,
                "top": {
                    "content": "GENERATE YOUR OWN"
                },
                "bottom": {
                    "content": "BEAUTIFUL QR CODE"
                }
            }
        }
    ]
}

Generate codes from a dataset

QR Code Styling CLI offers two ways to generate codes from a dataset. For a simple case where all generated codes are identical except for data, you can either set the data array in the config.json file, or set it on the command line as --data "https://www.example.com/" [--data ...].

To further customize individual codes, create a data.json file, e.g. to create a personalised QR code for each employee, you could have your data as:

[
    {
        "id": "123",
        "name": "Bob",
        "image": "https://example.com/profile/123.png"
    },
    {
        "id": "456",
        "name": "Conny",
        "image": "https://example.com/profile/456.png"
    }
]

Modify config.json to incorporate the data:

{
    "$schema": "./node_modules/@liquid-js/qr-code-styling-cli/lib/schema.json",
    "data": "https://www.example.com/profile?id={{ urlEscape id }}",
    "image": "{{ image }}",
    "imageOptions": {
        "mode": "center",
        "imageSize": 0.9,
        "margin": 1
    },
    "shape": "circle",
    "backgroundOptions": {
        "margin": 3,
        "round": 1,
        "color": "#fff"
    },
    "plugins": [
        {
            "plugin": "@liquid-js/qr-code-styling/border-plugin",
            "round": 1,
            "size": 60,
            "text": {
                "color": "#ffffff",
                "size": 27,
                "top": {
                    "content": "Hi! I'm {{ name }}"
                },
                "bottom": {
                    "content": "See my company profile"
                }
            }
        }
    ]
}

Then generate the codes by running

qr-code-styling --config config.json --out ./codes --template-data data.json

Output file naming

By default, output files are named qr-${hash(data)} - that is, the filename depends solely on the QR code data.

However, in the example above, you may want each QR code to match the colors of the employee's department(s), and some employees might belong to multiple departments. To achieve this, you can add the following to the employee data: "$matrix": { "color": ["#abc", "#def"] } to specify different colors. At the same time, you need to set a custom "outputFilename" pattern in config.json to ensure each file gets a unique name that takes both the employee ID and the chosen color into account, for example: "outputFilename": "qr-{{ hash id color }}". This will prevent filename collisions when the same employee has different color combinations.

Plugins

Plugin objects in a JSON config file should have a "plugin" property defining the plugin source; they can have other properties to define plugin configuration.

Example ./custom-plugin.js:

import { Plugin } from '@liquid-js/qr-code-styling/plugin-utils'

export default class CustomPlugin{
    constructor(options) {
        const { text, position } = options
    }
}

Example config.json:

{
    "plugins": [
        {
            "plugin": "./custom-plugin.js",
            "text": "some text",
            "position": "top center"
        }
    ]
}

JS API

import { writeFile } from 'fs/promises'
import { generateCodes } from '@liquid-js/qr-code-styling-cli'

const codes = await generateCodes({
    data: 'https://www.facebook.com/',
    image: 'https://upload.wikimedia.org/wikipedia/commons/5/51/Facebook_f_logo_%282019%29.svg',
    dotsOptions: {
        color: '#4267b2',
        type: 'rounded',
        size: 10
    },
    backgroundOptions: {
        color: '#e9ebee',
        margin: 1
    },
    imageOptions: {
        crossOrigin: 'anonymous',
        margin: 1,
        imageSize: 0.5
    }
}, 'svg')

for (const [data, buffer] of Object.entries(codes)) {
    await writeFile(slugify(data) + '.svg', buffer)
}

License

AGPL-3.0 License