ankipack

Generate Anki .apkg decks programmatically with full FSRS support. Works in browsers (including extensions), Node.js, and Bun.

ankipack targets the latest Anki version (24.x+) and its modern schema (V18 with protobuf-encoded deck configs). As far as we know, this is the only JavaScript/TypeScript package that supports the latest Anki format, including FSRS scheduler settings baked directly into the generated deck.

Table of Contents

• Features
• Installation
• Quick Start
• Platform Support
• API
  • Package
  • Deck
  • DeckConfig
  • Model
  • Note
• License

Features

• Latest Anki format with V18 schema and protobuf-encoded configuration
• Full FSRS support with desired retention, custom weights, and all scheduler options
• 4 built-in note types: Basic, Basic (and reversed), Basic (type in the answer), Cloze
• Custom note types with arbitrary fields, templates, and CSS
• Media attachments for images, audio, and other files
• Multiple decks in a single .apkg package
• Preset isolation: generated presets never overwrite the user's existing Anki defaults
• Tiny footprint: only 3 runtime dependencies (sql.js, fflate, @bufbuild/protobuf)
• Cross-platform: runs anywhere JavaScript runs

Installation

# bun
bun add ankipack sql.js

# npm
npm install ankipack sql.js

sql.js is a peer-like dependency that you initialize and pass to ankipack. This lets you control how the WASM binary is loaded, which is important in browsers and extensions.

Quick Start

import initSqlJs from "sql.js";
import { Package, Deck, DeckConfig, Model, Note } from "ankipack";

const SQL = await initSqlJs();

// Create a model (note type)
const model = Model.basic();

// Create a deck with FSRS settings
const deck = new Deck({
  name: "My Vocabulary",
  config: new DeckConfig({
    name: "My Preset",
    desiredRetention: 0.9,
    newPerDay: 20,
  }),
});

// Add notes
deck.addNote(new Note({ model, fields: ["bonjour", "hello"] }));
deck.addNote(new Note({ model, fields: ["merci", "thank you"] }));

// Export
const pkg = new Package();
pkg.addDeck(deck);

// Node.js / Bun: write to file
await pkg.writeToFile("vocab.apkg", SQL);

// Browser: get bytes for download
const bytes = await pkg.toUint8Array(SQL);

Platform Support

ankipack works in any JavaScript environment. The only platform-specific part is how you initialize sql.js.

Node.js / Bun

import initSqlJs from "sql.js";
const SQL = await initSqlJs();

sql.js will automatically locate its WASM binary from node_modules.

Browser / Browser Extensions

import initSqlJs from "sql.js";

const SQL = await initSqlJs({
  locateFile: (file) => `https://sql.js.org/dist/${file}`,
});

You can also bundle the WASM file locally and point locateFile to it. In browser extensions, you will typically include sql-wasm.wasm in your extension assets and reference it with chrome.runtime.getURL or a similar API.

Download helper (browser)

const bytes = await pkg.toUint8Array(SQL);
const blob = new Blob([bytes], { type: "application/octet-stream" });
const url = URL.createObjectURL(blob);

const a = document.createElement("a");
a.href = url;
a.download = "deck.apkg";
a.click();
URL.revokeObjectURL(url);

API

Package

A container for decks and media files that produces the final .apkg.

const pkg = new Package();

pkg.addDeck(deck);
pkg.addMedia("photo.jpg", imageBytes);

await pkg.writeToFile("output.apkg", SQL);  // Node.js / Bun
const bytes = await pkg.toUint8Array(SQL);   // Browser

| Method | Description | |---|---| | addDeck(deck) | Add a deck to the package | | addMedia(filename, data) | Attach a media file. Reference it in templates via its filename (e.g. <img src="photo.jpg">) | | toUint8Array(SQL) | Build the .apkg as a Uint8Array | | writeToFile(path, SQL) | Write the .apkg to disk (Node.js / Bun only) |

Deck

A named collection of notes with an associated scheduler preset.

const deck = new Deck({
  name: "French::Vocabulary",  // use :: for subdecks
  description: "Chapter 1 words",
  config: myConfig,
});

deck.addNote(note);

| Option | Type | Default | Description | |---|---|---|---| | name | string | required | Deck name. Use :: for subdecks | | description | string | undefined | Description shown in Anki's deck list (supports HTML) | | config | DeckConfig | auto-generated | Scheduler preset for this deck | | id | number | auto | Custom deck ID |

DeckConfig

Scheduler preset controlling how Anki schedules cards. Supports all FSRS settings.

const config = new DeckConfig({
  name: "Cramming Preset",
  desiredRetention: 0.85,
  learnSteps: [1, 10],
  newPerDay: 100,
  maximumReviewInterval: 7,
  buryNew: false,
});

Generated configs never use id=1, so they will not overwrite the user's existing default preset on import.

Learning

| Option | Type | Default | Description | |---|---|---|---| | learnSteps | number[] | [1, 10] | Learning steps in minutes | | relearnSteps | number[] | [10] | Relearning steps for lapsed cards | | graduatingIntervalGood | number | 1 | Days after graduating with Good | | graduatingIntervalEasy | number | 4 | Days after graduating with Easy |

Daily Limits

| Option | Type | Default | Description | |---|---|---|---| | newPerDay | number | 20 | Maximum new cards per day | | reviewsPerDay | number | 200 | Maximum reviews per day |

Intervals

| Option | Type | Default | Description | |---|---|---|---| | maximumReviewInterval | number | 36500 | Upper bound for intervals (days) | | minimumLapseInterval | number | 1 | Minimum interval for lapsed cards (days) |

FSRS

| Option | Type | Default | Description | |---|---|---|---| | desiredRetention | number | 0.9 | Target recall probability (0 to 1) | | fsrsParams | number[] | [] | Custom FSRS model weights | | historicalRetention | number | 0.9 | Historical retention for FSRS optimization | | ignoreRevlogsBeforeDate | string | "" | Ignore review logs before this date (YYYY-MM-DD) |

Card Ordering

| Option | Type | Default | Description | |---|---|---|---| | newCardInsertOrder | string | "due" | "due" or "random" | | newCardGatherPriority | string | "deck" | "deck", "deckThenRandom", "lowestPosition", "highestPosition", "randomNotes", "randomCards" | | newCardSortOrder | string | "template" | "template", "noSort", "templateThenRandom", "randomNoteThenTemplate", "randomCard" | | reviewOrder | string | "day" | "day", "dayThenDeck", "deckThenDay", "intervalsAscending", "intervalsDescending", "easeAscending", "easeDescending", "retrievabilityAscending", "retrievabilityDescending", "relativeOverdueness", "random", "added", "reverseAdded" | | newMix | string | "mixWithReviews" | "mixWithReviews", "afterReviews", "beforeReviews" | | interdayLearningMix | string | "mixWithReviews" | Same as newMix |

Burying

| Option | Type | Default | Description | |---|---|---|---| | buryNew | boolean | false | Bury new sibling cards until next day | | buryReviews | boolean | false | Bury review sibling cards until next day | | buryInterdayLearning | boolean | false | Bury interday learning siblings |

Leech

| Option | Type | Default | Description | |---|---|---|---| | leechAction | string | "tagOnly" | "suspend" or "tagOnly" | | leechThreshold | number | 8 | Lapses before flagging as leech |

Timer / Audio

| Option | Type | Default | Description | |---|---|---|---| | disableAutoplay | boolean | false | Disable automatic audio playback | | capAnswerTimeToSecs | number | 60 | Cap answer time recording | | showTimer | boolean | false | Show timer on review screen | | stopTimerOnAnswer | boolean | false | Stop timer when answer is shown | | secondsToShowQuestion | number | 0 | Auto-advance: seconds on question (0 = off) | | secondsToShowAnswer | number | 0 | Auto-advance: seconds on answer (0 = off) | | waitForAudio | boolean | true | Wait for audio before showing answer button | | skipQuestionWhenReplayingAnswer | boolean | false | Skip question audio on answer replay |

SM-2 Fallback

These are only used when FSRS is not enabled.

| Option | Type | Default | |---|---|---| | initialEase | number | 2.5 | | easyMultiplier | number | 1.3 | | hardMultiplier | number | 1.2 | | lapseMultiplier | number | 0.0 | | intervalMultiplier | number | 1.0 |

Easy Days

| Option | Type | Default | Description | |---|---|---|---| | easyDaysPercentages | number[] | [] | Per-weekday review load percentages |

Model

A note type defining fields and card templates. Use the built-in presets or create custom ones.

Built-in Presets

Model.basic()               // Front/Back, 1 card per note
Model.basicAndReversed()     // Front/Back + reversed, 2 cards per note
Model.basicTyping()          // Front/Back with type-in answer
Model.cloze()                // Cloze deletions ({{c1::text}})

All presets accept optional { name?: string, css?: string }.

Custom Model

const model = new Model({
  name: "Vocab (type answer)",
  css: `.card { font-size: 24px; text-align: center; }`,
  fields: [
    { name: "Question" },
    { name: "Answer" },
    { name: "Notes", description: "Optional extra context" },
  ],
  templates: [
    {
      name: "Card 1",
      questionFormat: "{{Question}}\n\n{{type:Answer}}",
      answerFormat: '{{Question}}<hr id="answer">{{type:Answer}}<br>{{Notes}}',
    },
  ],
});

ModelOptions

| Option | Type | Default | Description | |---|---|---|---| | name | string | required | Note type name | | fields | FieldDef[] | required | Field definitions | | templates | TemplateDef[] | required | Card templates | | type | string | "normal" | "normal" or "cloze" | | css | string | Anki default | CSS applied to all cards of this type | | sortFieldIndex | number | 0 | Field index used for browser sorting | | latexPre | string | Anki default | LaTeX preamble | | latexPost | string | \end{document} | LaTeX postamble | | latexSvg | boolean | false | Render LaTeX as SVG | | id | number | auto | Custom model ID |

FieldDef

| Option | Type | Default | Description | |---|---|---|---| | name | string | required | Field name (unique within the model) | | sticky | boolean | false | Keep value when adding new notes | | rtl | boolean | false | Right-to-left text | | fontName | string | "Arial" | Editor font | | fontSize | number | 20 | Editor font size | | description | string | "" | Placeholder text | | plainText | boolean | false | Treat as plain text (no HTML) |

TemplateDef

| Option | Type | Default | Description | |---|---|---|---| | name | string | required | Template name | | questionFormat | string | required | Question side HTML (use {{FieldName}} for substitutions) | | answerFormat | string | required | Answer side HTML (use {{FrontSide}} to include the question) | | questionFormatBrowser | string | "" | Alternative question template for browser view | | answerFormatBrowser | string | "" | Alternative answer template for browser view | | browserFontName | string | "" | Browser column font | | browserFontSize | number | 0 | Browser column font size | | targetDeckId | number | 0 | Override deck for this template's cards |

Note

A single note containing field values. Generates one or more cards based on its model.

const note = new Note({
  model: Model.basic(),
  fields: ["What is 2+2?", "4"],
  tags: ["math", "easy"],
});

deck.addNote(note);

| Option | Type | Default | Description | |---|---|---|---| | model | Model | required | Note type for this note | | fields | string[] | required | Field values (must match model's field count) | | tags | string[] | [] | Tags for this note | | guid | string | auto | Custom GUID (auto-generated base91 if omitted) |

License

MIT License. See LICENSE for details.