Anki TS

A TypeScript library for programmatically creating Anki decks and exporting them as .apkg files.

Installation

bun add anki-ts

Quick Start

You can see the following example in src/example/quick-start.ts. You can run it with bun run src/example/quick-start.ts.

Example templates are available in this repo.

import { model, note, card, deck, collection, buildApkg } from "anki-ts";

// 1. Define a model (note type) with fields and template
const basicModel = model()
  .name("Basic")
  .fields(["Front", "Back"])
  .template("Card 1", "{{Front}}", "{{FrontSide}}<hr id=answer>{{Back}}")
  .build();

// 2. Create a deck
const myDeck = deck()
  .name("My Deck")
  .description("A simple deck")
  .build();

// 3. Create a note with content
const myNote = note()
  .modelId(basicModel.id)  // link to model
  .field("What is 2 + 2?")
  .field("4")
  .tag("math")
  .build();

// 4. Create a card linking note to deck
const myCard = card()
  .noteId(myNote.id)   // link to note
  .deckId(myDeck.id)   // link to deck
  .asNew()             // set as new card
  .build();

// 5. Build collection and export
const col = collection()
  .addModel(basicModel)
  .addDeck(myDeck)
  .addNotes([myNote])
  .addCards([myCard])
  .build();

buildApkg(col, "output.apkg");

Core Concepts

Anki has a hierarchical data model. Understanding these relationships is key:

Model (Note Type) ──defines──> Fields & Templates
        │
        └─────────referenced by──> Note (content)
                                        │
                                        └──linked to──> Card
                                                          │
Deck <────────────────────────────────────────────────────┘

• Model: Defines the structure (fields) and appearance (templates) of notes
• Note: The actual content (field values) for one flashcard entry
• Card: A specific instance of a note that belongs to a deck
• Deck: A container for cards

Requirements

This library uses Bun's SQLite module. It requires Bun runtime.

Development

bun run build    # Compile TypeScript to dist/
bun run check    # Type check without emitting

License

MIT