anki-apkg-export

Server-side ESM module for generating Anki .apkg decks.

Requirements

• Node.js >= 24
• ESM

Install

pnpm add @shbernal/anki-apkg-export

Usage

import fs from "fs";
import AnkiExport from "@shbernal/anki-apkg-export";

const apkg = await AnkiExport("deck-name");

apkg.addMedia("anki.png", fs.readFileSync("anki.png"));

apkg.addCard("card #1 front", "card #1 back");
apkg.addCard("card #2 front", "card #2 back", {
  tags: ["nice", "better card"],
});
apkg.addCard('card #3 with image <img src="anki.png" />', "card #3 back");

fs.writeFileSync("./output.apkg", await apkg.save());

Template customization

AnkiExport(name, templateOverrides?) accepts questionFormat, answerFormat, and css:

const apkg = await AnkiExport("customized", {
  questionFormat: "{{Front}}",
  answerFormat: '{{FrontSide}}<hr id="answer">{{Back}}',
  css: ".card { font-family: Arial; font-size: 20px; }",
});

Reproducible builds

The deck reads the clock exactly once, so saving the same input twice in one process already gives identical bytes. Pin that reading to get the same bytes from any process, on any machine:

const apkg = await AnkiExport("deck-name", undefined, { now: 1_700_000_000_000 });

API

• AnkiExport(name: string, template?: TemplateOptions, options?: { now?: number })
• addCard(front: string, back: string, options?: { tags?: string | readonly string[] })
• addMedia(filename: string, data: Buffer | Uint8Array | ArrayBuffer | string)
• save(options?: ZipOptions): Promise<Buffer>
• close() — releases the sql.js database; also wired to Symbol.dispose, so using apkg = await AnkiExport(…) does it for you. Only a process that builds many decks needs it; a one-shot script can ignore it.

Full signatures and defaults: docs/reference.

Generated decks

Decks are written at schema 11 (package version Legacy1), which every current Anki release imports, with rows written the way Anki writes them for the same content. Identical input and clock produce byte-identical archives; see reproducible builds for what pins the clock.

The field-by-field contract, the deliberate deviations, and the known non-conformances are in docs/reference/deck-format.

Documentation

• Overview
• Architecture
• Reference and deck format
• Tooling and troubleshooting
• Changelog

Development

pnpm install
pnpm run format:check && pnpm run typecheck && pnpm run lint && pnpm test && pnpm run build

See docs/tooling for the full gate sequence and the lint setup.

Examples

• Server example: examples/server/server.js

References

• APKG format documentation