QR Code Styling CLI
Effortlessly generate customised QR codes from the command line
Installation
> npm install @liquid-js/qr-code-styling-cliUsage
> npx qr-code-styling --config ./qr-config.json --out ./qr-codesCommand line options
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"]
-s, --size raster output size [number]
-o, --out output directory [string] [required]
-d, --data qr code data [array]
-t, --template-data format config using {{ handlebars }} [string]
-v, --validate validate generated QR codes [string] [choices: "off", "info", "error"]
The qr-code-styling command has two required parameters: a JSON configuration file and the output directory where the generated files will be placed.
The configuration file has a structure which matches that of the QRCodeStyling options, with extra options to set output format, size, and validation. If you've already designed a QR code using the Styled QR Generator, you can download your configuration file from the Download button context menu or the JSON config section of the editor. Image, fonts, and other resources needed to generate the QR code can be included in the configuration as file paths (resolved relative to the configuration file location).
Output format and size
Output format is set either as --format svg CLI option, or using "format": "svg" in the config file. When using raster output formats (png, jpg, webp), the generated image width is set to the provided --size value (1200 by default) and image height is calculated based on the aspect ratio. In most cases, the aspect ratio is 1:1 since the generated QR codes are square, but a plugin could change that by adding asymmetric decorations. Since svg and pdf formats produce vector images, the --size option is ignored for those formats.
Command line output
On a successful run, the qr-code-styling command prints a JSON list with the summary of the generated QR codes. Each entry contains the QR code data, output path, validation info, and template context.
Validation
By default, each generated QR code is validated to check whether it can be easily detected by QR code readers. Each entry in the console output contains a "isValid" property, which tells you whether the code can be easily recognised by a QR code reader or not. However, keep in mind that mobile devices use much more advanced QR code detection algorithms than simple embedded readers and can usually recognise even QR codes with "isValid": false.
The default validation behaviour (info) is to check generated QR codes and report validation status, but keep the generated codes. Set validation to error to skip generating potentially unrecognisable QR codes, or off to skip validation entirely.
Datasets and templates
When using the --template-data option to specify a JSON dataset, the data can be merged into the configuration using Handlebars syntax to generate parametrised QR codes. As shown in the example dataset below, an entry can have a special "$matrix" field in the form of key: [values]; such entries will be expanded to all possible combinations of matrix values (in this case, one entry with "color": "#fedcba" and one with "color": "#abcdef").
[
{
"id": "123",
"name": "Bob",
"image": "https://example.com/profile/123.png",
"$matrix": {
"color": [
"#fedcba",
"#abcdef"
]
}
},
{
"id": "456",
"name": "Conny",
"image": "https://example.com/profile/456.png",
"color": "#bfffca"
}
]
Each entry's fields can then be merged into the configuration file as shown below, where we generate a personalised QR code for each employee in the dataset using their company profile image and id for the QR code, and their name and colour to add a custom border. Since some employees receive multiple QR codes with different-coloured borders, "outputFilename": "qr-{{ hash id color }}" property is added to the configuration to ensure unique filenames.
{
"$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": 0.15,
"color": "{{ color }}",
"proportional": true,
"text": {
"color": "#000",
"size": 0.7,
"top": {
"content": "Hi! I'm {{ name }}"
},
"bottom": {
"content": "See my company profile"
}
}
}
],
"outputFilename": "qr-{{ hash id color }}"
}
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:
export default class CustomPlugin {
constructor(options = { text: '', position: 'top' }) {
const { text, position } = options
}
}
Example qr-config.json:
{
"plugins": [
{
"plugin": "./custom-plugin.js",
"text": "some text",
"position": "top center"
}
]
}