@simtabi/printcraft

Client-side printing you can aim: real paginated sheets with numbers and borders, a region tool that prints what you drew, redaction that is verified rather than hoped for, and a right-click menu, command palette and keyboard commands that are there the moment the script loads.

Runs in any browser with afterprint and document.fonts: Chrome, Edge, Firefox and Safari, current and two back. TypeScript source, two runtime dependencies (both leaf), ESM + UMD builds, and a command line for CI.

Try the demo: every job, the interaction layer and the inspector, with nothing to install.

Install

npm install @simtabi/printcraft

3.0.0 is on npm. Releases after it are published to GitHub Packages while npm's trusted publishing cannot take a publish from this repository (npm/cli#9969). GitHub Packages asks for a token even for a public package, so to install one, add a GitHub token with read:packages to the project's .npmrc first:

@simtabi:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

See npm or GitHub Packages.

import Printcraft from '@simtabi/printcraft'; // esm
const Printcraft = require('@simtabi/printcraft'); // cjs (umd build)

Or a script tag. The UMD build sets a Printcraft global and boots the declarative layer automatically:

<script src="printcraft.umd.js"></script>
<button data-printcraft="#invoice">Print</button>

Quick start guide and usage

Getting started

Nothing to configure: once the module is imported (or the UMD script is loaded), Printcraft is ready to print. Two optional script-tag attributes control the UMD auto-boot:

1. data-auto-init="false" skips the auto-boot entirely.
2. data-config="/printcraft.config.json" fetches page-wide defaults from a file.

Usage

const job = await Printcraft.print('#invoice');
console.log(job.status, job.duration + 'ms');

await Printcraft.print({
  target: '#invoice',
  excludeSelectorList: ['.ads', 'nav'],
  headerText: 'ACME CO',
  setPrintSize: 'A4 portrait',
  pageMargin: '18mm'
});

await Printcraft.job('#invoice').exclude('.ads').redact('.ssn').watermark('DRAFT', 0.15).print();

The full walkthrough is in Getting started; everything else is in the documentation index.

Documentation

Full documentation: https://opensource.simtabi.com/documentation/simtabi/printcraft-js/

Guides

• Installation — package, script tag, and build output
• Demo — where to run it, and how its assets are built
• Getting started — your first job, in each of the three surfaces
• Surfaces — imperative, declarative, and JSON config
• Configuration — page defaults, config files, content annotations
• Architecture — the pipeline, the module layout, and why it is shaped this way
• Pagination — real sheets, page numbers, borders and running bands
• The proof sheet — see the assembled document before it prints
• Cover and notes pages — the title at the front, every mark listed at the back
• Security — the threat model, and what redaction guarantees
• Print backends — sending a job to a server or a companion service
• Comparison — lineage from ezPrintJS, and what changed
• Release — versioning and the publish process

Reference

• Options — every option, grouped by concern
• Events — the job lifecycle, hooks, and cancellation
• Redaction — destructive, declassified-file bars
• Privacy — the PII scanner
• Printer marks — crop marks and bleed
• Annotations — note chips in the print copy
• Drawn annotations — pen, highlighter, arrows, boxes and text
• Clip printing — printing an exact rectangle
• Watermarks — text and image watermarks
• The interaction layer — actions, menu, command palette, keyboard, theming
• The component kit — modals, menus, forms, toasts, tooltips, popovers
• Sharing — screenshots, clipboard and email
• Memory — remembering marks, options and activity between visits
• Errors and logging — codes, levels, sinks and events
• The command line — print, doctor and init, for CI
• Devtools — the inspector, the debug log, job records

Recipes

• Print an invoice
• Redact before printing
• Draw a print area
• Crop marks for press
• Page defaults from JSON
• Override Ctrl+P

Community

Questions and ideas belong in GitHub Discussions; bugs in Issues.

Contributing & security

See CONTRIBUTING.md for local setup and conventions, and SECURITY.md to report a vulnerability privately.

License

MIT. A clean-room reimplementation and extension of the public API of ezPrintJS v1.1.0 (2017); no code from that commercial library was used. Icon artwork from Tabler Icons (MIT).