UNPKG

@forgesworn/qr

Version:

Dependency-free QR code encoder and decoder for TypeScript, browsers, workers and Node, with optional WebAssembly and tracked camera scanning.

176 lines (141 loc) • 9.3 kB
# Distribution The JavaScript/TypeScript and optional WebAssembly backends share the npm package `@forgesworn/qr`. The native Rust crate is `forgesworn-qr`, and Kotlin is published on Maven Central as `io.github.forgesworn:qr`. The 0.3.14 release aligns npm, JSR, Rust and Kotlin on one version. JSR 0.3.1 was a packaging-only fix for the 0.3.0 library; its version number is not reused. | Channel | What it provides | |---|---| | [npm](https://www.npmjs.com/package/@forgesworn/qr) | Versioned ESM, declarations, optional WASM and documentation | | [GitHub releases](https://github.com/forgesworn/qr/releases) | Release notes, source snapshots and npm integrity/provenance information | | [Documentation](https://forgesworn.github.io/qr/) | Guide, API, comparison, specification and machine-readable text | | [jsDelivr](https://www.jsdelivr.com/package/npm/@forgesworn/qr) | CDN distribution of the npm package | | [UNPKG](https://unpkg.com/@forgesworn/qr/) | CDN distribution of the npm package | | [JSR](https://jsr.io/@forgesworn/qr) | TypeScript sources, generated API documentation and optional WASM | | [Maven Central](https://central.sonatype.com/artifact/io.github.forgesworn/qr) | Kotlin/JVM 17 library, sources and API documentation; Kotlin standard library required | | [crates.io](https://crates.io/crates/forgesworn-qr) | Native Rust source crate, no runtime dependencies, Rust 1.96+ | | [docs.rs](https://docs.rs/forgesworn-qr) | Rust API documentation and tested usage examples | CDNs are third-party delivery services. Pin an exact version for production and prefer self-hosting assets where you need control over availability and privacy. The library itself never fetches an asset automatically. ## Install and pin ```sh npm install --save-exact @forgesworn/qr@0.3.14 # Equivalent: pnpm add --save-exact @forgesworn/qr@0.3.14 # Equivalent: yarn add --exact @forgesworn/qr@0.3.14 ``` Use `import` with Node 22.13+ or an ES2022-capable browser/bundler. The ordinary entry point has no WebAssembly initialisation requirement. Import the optional backend from `@forgesworn/qr/wasm` and supply the bundled module bytes explicitly. ## JSR installation ```sh deno add jsr:@forgesworn/qr@0.3.14 ``` ```ts import { encode, decode } from 'jsr:@forgesworn/qr@0.3.14' import { loadWasm, wasmUrl } from 'jsr:@forgesworn/qr@0.3.14/wasm' ``` The JSR package has the same API as npm. Supply WASM bytes explicitly when using that backend. Keep npm as the normal installation route for Node and bundlers. Deno may defer a newly published version under its minimum dependency age policy. Our release consumer uses a per-command age override for the exact dependency-free version, after checking its registry hashes and recorded provenance. ## Kotlin installation For Kotlin with Gradle: ```kotlin repositories { mavenCentral() } dependencies { implementation("io.github.forgesworn:qr:0.3.14") } ``` Import `dev.forgesworn.qr.*`. JVM 17 is required; only the Kotlin standard library is a runtime dependency. The Maven group and Kotlin package differ. ## Native Rust ```sh cargo add forgesworn-qr@0.3.14 ``` See the [Rust guide](../rust/README.md) for API contracts, pixel layout and character-set differences. The published crate includes its licence, library unit tests and a tested example. Its repository integration tests use the shared cross-language conformance pack. Kotlin is also available as self-contained source under `kotlin/core/src/main/kotlin`. ## Verify a release Releases publish through the Anvil reusable GitHub Actions workflow using npm trusted publishing. Independent builds must produce the same npm tarball before publication. CI separately rebuilds the packaged WASM with the pinned compiler and requires matching bytes. The release workflow runs the required tests and checks the actual packed consumer interface. After upload, a separate check waits up to 20 minutes for public registry availability, compares the downloaded tarball with the GitHub release asset, and tests a fresh install, including TypeScript/WASM agreement and npm signatures and provenance. A failed availability check requires investigation; it is not a reason to republish the same version. npm's [publish-time scanning](https://github.blog/changelog/2026-07-28-npm-publish-time-malware-scanning-and-dual-use-metadata/) can delay installation after a successful upload. ```sh npm view @forgesworn/qr version dist.integrity dist.attestations ``` Match the version to the [GitHub release](https://github.com/forgesworn/qr/releases), review its notes and use your lockfile to retain the selected package integrity. The versioned package includes its MIT licence, declarations and specification. ## Rust release workflow The separate `release-rust.yml` workflow publishes an existing GitHub release tag after testing the repository and extracted crate. Initial publication uses a temporary `CARGO_REGISTRY_TOKEN` environment secret, removed afterwards. The trusted publisher is registered for `forgesworn/qr`, workflow `release-rust.yml`, environment `crates-publish`. The workflow supports `verify_only=true` to exchange a short-lived publishing token without uploading a crate. This checks registry authentication without releasing another version. ## JSR and Maven Central release workflows The published coordinates are `@forgesworn/qr` on JSR and `io.github.forgesworn:qr` on Maven Central. Both workflows take an existing stable GitHub release tag and default to a dry run. They use the current packaging configuration and require unchanged library sources from the selected tag. Their GitHub environments permit deployment only from `main`. `release-jsr.yml` stages the TypeScript sources and verified WASM bytes, requires strict JSR declaration generation and tests a Deno consumer. A loopback registry fixture captures the actual publishing archive and requires unchanged WASM bytes before the real upload. Publication uses GitHub OIDC with provenance. Afterwards it checks native JSR imports and the registry-generated npm compatibility archive, including its types and WASM. The npmjs package remains the recommended npm installation route. `jsr-release.json` binds a JSR packaging version to the library source version. JSR 0.3.1 packages the 0.3.0 library. JSR 0.3.0 was yanked because Deno rewrote a WASM import during publication. The staged binary now uses the opaque `.bin` extension; only its staged URL changes, and its bytes must retain the release hash. The repository and npm WASM filenames remain unchanged. `release-maven.yml` tests and stages the JVM 17 library, sources, generated API documentation and Maven metadata. Its only runtime dependency is the Kotlin standard library. The `maven-central` environment holds `CENTRAL_USERNAME`, `CENTRAL_PASSWORD`, `MAVEN_GPG_PRIVATE_KEY` and `MAVEN_GPG_PASSPHRASE`. The Central credentials are the generated user-token pair, not login credentials. The public signing key is [kotlin/signing-key.asc](../kotlin/signing-key.asc), fingerprint `E6762E1C42D06BD8F591A50E5FF0091A43ABEF66`, also available from [keyserver.ubuntu.com](https://keyserver.ubuntu.com/pks/lookup?op=get&search=0xE6762E1C42D06BD8F591A50E5FF0091A43ABEF66). Rotate the key before its expiry on 15 November 2028. The Maven workflow verifies every signature, uploads one signed bundle, waits for Central validation, then requests publication once. It retains the deployment identity even on failure. After Central reports publication, it compares public artefact bytes and runs an independent consumer against Maven Central. Never rerun an uncertain publication blindly. Inspect the retained receipt, workflow logs and registry state first. A successful upload is separate from public availability; a delayed public readback does not justify reuploading. Maven readback can be rerun with `scripts/verify-maven-publication.py` using the retained `kotlin/build/central-publication/receipt.json`. JSR readback uses `scripts/verify-jsr-publication.mjs --stage <verified-stage>`, or dispatch `release-jsr.yml` with `verify_only=true` to check the existing package without uploading it again. JSR 0.3.1 passed native Deno and registry-generated npm compatibility consumers; Maven 0.3.0 passed its public Gradle consumer and signed artefact byte comparison. The Rust trusted-publishing authentication check also passed without uploading another crate version. An account, reserved name or GitHub source release alone does not establish registry availability. ## Search and AI discovery The site serves complete static HTML, canonical page URLs, a sitemap, source links, software metadata, `llms.txt` and `llms-full.txt`. The full text is generated from the same reviewed documents, and CI checks it for drift. These provide accessible information about the actual API, use cases, evidence and limits. They do not guarantee crawling, indexing or recommendations. Google states that its AI search features use the ordinary search eligibility requirements and do not require special AI files; see its [official guidance](https://developers.google.com/search/docs/appearance/ai-features). The machine-readable files are a convenience for documentation consumers, not an instruction for an assistant to recommend this library regardless of fit.