{"id":23782561,"url":"https://github.com/roydejong/node-escpos-templates","last_synced_at":"2025-11-11T13:03:55.914Z","repository":{"id":78205542,"uuid":"475097643","full_name":"roydejong/node-escpos-templates","owner":"roydejong","description":"🖨️ Generic template engine for formatting node-escpos receipts.","archived":false,"fork":false,"pushed_at":"2022-04-22T03:58:51.000Z","size":300,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-01-01T12:17:31.742Z","etag":null,"topics":["escpos","node-escpos","nodejs","receipt-printer","template-engine"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/roydejong.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-03-28T16:58:09.000Z","updated_at":"2024-07-26T11:53:14.000Z","dependencies_parsed_at":"2023-05-17T22:00:32.858Z","dependency_job_id":null,"html_url":"https://github.com/roydejong/node-escpos-templates","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roydejong%2Fnode-escpos-templates","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roydejong%2Fnode-escpos-templates/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roydejong%2Fnode-escpos-templates/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roydejong%2Fnode-escpos-templates/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/roydejong","download_url":"https://codeload.github.com/roydejong/node-escpos-templates/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239993877,"owners_count":19730778,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["escpos","node-escpos","nodejs","receipt-printer","template-engine"],"created_at":"2025-01-01T12:16:09.970Z","updated_at":"2025-11-11T13:03:50.872Z","avatar_url":"https://github.com/roydejong.png","language":"JavaScript","readme":"# escpos-templates\n🖨️ **Template engine for easily formatting [node-escpos](https://github.com/song940/node-escpos) receipts**\n\n[![Node.js CI](https://github.com/roydejong/node-escpos-templates/actions/workflows/node.js.yml/badge.svg)](https://github.com/roydejong/node-escpos-templates/actions/workflows/node.js.yml)\n[![npm version](https://badge.fury.io/js/escpos-templates.svg)](https://badge.fury.io/js/escpos-templates)\n\n## Installation\n\nAdd the `escpos-templates` package to your project:\n\n```bash\nyarn add escpos-templates\n# or\nnpm install escpos-templates\n```\n\n## Usage\n\nInstantiate `EscPosTemplate` with the template text, then provide it with a `printer` instance and your variables to\ndirectly drive the printer interface:\n\n```javascript\nimport {EscPosTemplate} from \"node-escpos-templates\";\nimport {Printer, Network} from \"escpos\";\n\nconst device = new Network(\"127.0.0.1\", 1234);\nconst printer = new Printer(device);\n\nconst template = new EscPosTemplate(`print \\\"Hello {{theName}}!\"; feed 2; cut;`);\nconst myVars = {theName: \"Bob\"};\n\ndevice.open((err) =\u003e {\n  // Directly drive printer instructions from the template, with optional variables\n  template.print(printer, myVars);\n  printer.close();\n});\n```\n\n## Creating templates\n\nThis project uses a simple custom syntax to define print templates.\n\nEach print instruction must be placed on separate line, and/or seperated with a semicolon `;`.\n\n### \"Hello world\" example\n\nA very simple template that prints some text, beeps once, then cuts the paper:\n\n*Template text*:\n```\nprint \"Hello world!\";\nbeep 1 1;\ncut;\n```\n\n### Working with variables \n\nWhen calling `print()` you can provide an object of template variables.\n\nYou can refer to these anywhere in a template string by using the `{{variableName}}` syntax. You can also refer to\nvariables directly as arguments to template functions.\n\n*Template text*:\n```\n# Print \"Bob\" \nprint name;\n\n# Print \"Hello Bob!\"\nprint \"Hello {{name}}!\";\n\n# Print \"Hello Bob Smith!\"\nprint \"Hello {{person.firstName}} {{person.lastName}}!\";\n```\n\n*Code*:\n```javascript\ntemplate.print(printer, {name: \"Bob\", person: {firstName: \"Bob\", lastName: \"Smith\"}});\n```\n\nMost functions expect integers or string values, but some special functions like images and tables may need special input (refer to the function list below for details).\n\n### Printing special elements\n\n#### Images\nTo print an image, you'll need to prepare an `escpos.Image` instance in advance and pass it as a variable:\n\n*Code and template text*:\n```javascript\nimport {Image} from \"escpos\";\n\nImage.load(\"hippopotamus.png\", function (hippoImg) {\n  const template = new EscPosTemplate(\"init; align center; image hippoImg; feed 5; cut\");\n\n  device.open((err) =\u003e {\n    template.print(printer, { hippoImg });\n    printer.close();\n  });\n});\n```\n\n#### Barcodes\nSupported barcodes (depending on printer model) are `UPC_A`, `UPC_E`, `EAN13`, `EAN8`, `CODE39`, `ITF`, `NW7`, `CODE93`, and `CODE128`.\n\n*Template text*:\n```\n# Print EAN-13 barcode\nbarcode \"EAN13\" \"ABCDEF123456\" 2 50\n```\n\nThe arguments for the `barcode` function are: type, code, width (optional, range 2 - 6), height (optional, range 1-255), text position (optional, defaults to \"below\") and barcode font (\"A\" or \"B\").\n\nText position options are: `off` (no text), `above` (text above barcode), `below` (text below barcode), `both` (text above and below barcode).\n\n### Iterating through data\nWhen you pass an array as a variable, you can iterate through it using a `loop` statement. This can be useful for line items.\n\n*Template text:*\n```\nloop myArray\n  # In the iteration context, each array item is available as \"item\"\n  # You can access keys on variables as well for more flexibility\n  print item.label\nendloop \n```\n\n*Code*:\n```javascript\ntemplate.print(printer, {myArray: [{label: \"One\"}, {label: \"Two\"}, {label: \"Three\"}]});\n// Prints \"One\", \"Two\" and \"Three\" each on a seperate line\n```\n\nBegin iterating over an array variable with the `loop` statement. Each following statement, until `endloop` the statement, will be executed for each item in the array, with `item` as variable for each array element.\n\n### If-statements\nThe template syntax has limited support for if-statements. They allow you to make a set of instructions conditional on whether a variable is truthy or not.\n\n*Template text:*\n```\nif varOne\n\n  # If varOne is truthy, this instruction will execute...\n  print \"One!\"\n  \n  # You can also nest statements!\n  if varTwo\n    print \"Also, two?\"\n  endif\n  \nendif\n```\n\n*Code*:\n```javascript\ntemplate.print(printer, {varOne: \"This is truthy\", varTwo: 0});\n// Prints \"One!\"\n```\n\n## Function list\n\nThese are the functions that are currently implemented for use in the templates.\n\nArguments are listed in `[brackets]`, with optional arguments denoted with a `?`.\n\n### Core\n\n| Syntax            | Details                                                                                                                                               |\n|-------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `init`            | Reset (initialize) printer                                                                                                                            |\n| `print [t] [e?]`  | Prints text `[t]` with linebreak, in encoding `e` (CP437?)                                                                                            |\n| `iprint [t] [e?]` | Prints inline text `[t]` without linebreak, in encoding `e` (CP437?)                                                                                  |\n| `oprint [text]`   | Optionally prints one line of `text`, if it's not falsy, with linebreak                                                                               |\n| `send [..args]`   | Sends all args as raw, un-encoded text to the printer without linebreak                                                                               |\n| `feed [n?]`       | Feed `[n]` (1?) amount of lines.                                                                                                                      |\n| `beep [n?] [t?]`  | Beep `[n]` (1?) times for `[t]` (1?) × 100 ms duration                                                                                                |\n| `cut [m?] [n?]`   | Performs a cut in mode `[m]` (0?), with optional parameter `[n]` ([docs](https://reference.epson-biz.com/modules/ref_escpos/index.php?content_id=87)) |\n| `cashdraw [p]`    | Pulses the cash drawer kick on pin `[p]` (2?)                                                                                                         |\n\n### Text formatting\n\n| Syntax             | Details                                                       |\n|--------------------|---------------------------------------------------------------|\n| `linespacing [n?]` | Sets line spacing to `n` (default?, 1-255) × motion unit      |\n| `invert [t]`       | Sets inverted mode (white on black printing) to `off` or `on` |\n| `align [a]`        | Align text `left`, `center` or `right`                        | \n| `bold [t]`         | Set bold / emphasis to `off` or `on`                          | \n| `underline [t]`    | Set underline mode to `off`, `on` or `double`                 |\n| `font [f]`         | Set font to `a`, `b`, or `c`                                  | \n| `fontsize [w] [h]` | Sets character width × `[w]` and height × `[h]`  (1-8)        | \n| `reset`            | Resets all formatting options to their defaults               |\n\n### Special elements\n\n| Syntax                                       | Details                                                                                                                      |\n|----------------------------------------------|------------------------------------------------------------------------------------------------------------------------------|\n| `image [image] [density?]`                   | Prints a rasterized `[image]` (`escpos.Image` instance)                                                                      | \n| `barcode [type] [code] [w?] [h?] [tp?] [f?]` | Prints `[code]` of `[type]` with height `[h]` (?), width `[w]` (?) and text position `[tp]` (`below`?) and font `[f]` (`a`?) |\n| `qr [code] [size?] [version?] [level?] `     | Prints QR `[code]` in `[size]` (12?, 1 - 24) with a `[version]` (3?, 1 - 16) and error correction `[level]` (L?, M, Q, H).   |\n\n## Additional information\n\n### Template syntax\nSome details about the template syntax this library uses:\n- Each line is evaluated separately;\n  - Empty lines are ignored\n  - Lines that start with a hash `#` are ignored (comment)\n- Each line is parsed for instructions;\n  - Multiple instructions can be split using a semicolon `;`\n  - Each instruction starts with an alphanumeric opcode (e.g. `print`)\n  - Each instruction can have any amount of arguments, split by a space or tab\n- Each argument can be passed as a string literal or variable;\n  - Double quotes should `\"` wrap around a string literal\n  - Backslash ` \\ ` can be used as an escape character anywhere\n  - Any argument that isn't a string literal must be an integer or variable reference\n  - Some variables are predefined (e.g. `true`, `false` and options listed in the table above)\n  - If hexadecimal notation (`0x`) is used in place of a variable, it is automatically resolved to the corresponding character\n- When using a `loop`, all instructions are buffered and will not be evaluated until the `endloop` statement is evaluated;\n- When using an `if`, the argument is evaluated to check whether it is Truthy or not; if it's not, all statements following it until the `endif` will be skipped (but must still have valid syntax);\n  - Nested if-statements are supported \n\n### Special settings\n\n#### Parity bit (barcodes)\nYou can globally control whether a parity bit is included for certain barcode types. It is enabled by default but may not be supported by some printers:\n\n```javascript\nEscPosTemplate.setEnableBarcodeParityBit(false); // turn parity bit OFF for all barcodes \n```","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froydejong%2Fnode-escpos-templates","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Froydejong%2Fnode-escpos-templates","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froydejong%2Fnode-escpos-templates/lists"}