anki-ts Examples

This repository contains examples demonstrating how to use anki-ts to programmatically create Anki flashcard decks.

Installation

bun install

Examples

1. Minimal Example

The simplest way to create an Anki deck.

bun examples/minimal/index.ts

What it covers:

• Creating a basic note type (model) with fields and a template
• Creating a deck
• Adding notes and cards
• Exporting to an .apkg file

Key concepts:

• Model - Defines the structure of your flashcards (fields and templates)
• Deck - A container for your cards
• Note - A piece of content with field values
• Card - The schedulable unit that Anki tracks

2. Single Deck Example

A more complete example with custom templates and card states.

bun examples/single-deck/index.ts

What it covers:

• Loading HTML/CSS templates from files
• Multiple card templates per note type (bidirectional cards)
• Adding tags to notes
• Card states: new, learning, review, suspended, buried
• Card flags (colors)
• Custom deck configuration (learning steps, review intervals, etc.)

Key concepts:

• Templates - HTML files defining how cards appear (question/answer sides)
• Tags - Labels for organizing notes
• Card states - Where a card is in the learning process
• Deck config - Settings that control scheduling behavior

Core Concepts

Model (Note Type)

A model defines the blueprint for your flashcards:

const basicModel = model()
  .name('Basic')
  .fields(['Front', 'Back'])                    // What data fields exist
  .template('Card 1', '{{Front}}', '{{Back}}')  // How cards are rendered
  .build();

Deck

A deck is a container for cards:

const myDeck = deck()
  .name('My Deck')
  .description('Optional description')
  .build();

Note

A note holds the actual content:

const myNote = note()
  .modelId(basicModel.id)
  .fields(['What is 2+2?', '4'])
  .tags(['math', 'basic'])
  .build();

Card

A card is what Anki schedules for review:

const myCard = card()
  .noteId(note.id)
  .deckId(deck.id)
  .ordinal(0)           // Which template (0-indexed)
  .build();

Card States

Cards can be in different states:

// New card (default)
card().noteId(id).deckId(id).ordinal(0).build()

// Learning card (with due timestamp)
card().noteId(id).deckId(id).ordinal(0).asLearning().due(timestamp).build()

// Review card (with interval and ease factor)
card().noteId(id).deckId(id).ordinal(0).asReview().due(10).interval(7).factor(2500).build()

// Suspended card (hidden from reviews)
card().noteId(id).deckId(id).ordinal(0).suspend().build()

// Buried card (hidden until next day)
card().noteId(id).deckId(id).ordinal(0).bury().build()

Card Flags

Mark cards with colors for visual organization:

import { CardFlag } from 'anki-ts';

card().flags(CardFlag.Red).build()     // Red flag
card().flags(CardFlag.Orange).build()  // Orange flag
card().flags(CardFlag.Green).build()   // Green flag
card().flags(CardFlag.Blue).build()    // Blue flag

Building the APKG

const data = collection()
  .addModel(basicModel)
  .addDeck(basicDeck)
  .addNotes(notes)
  .addCards(cards)
  .build();

buildApkg(data, 'output/deck.apkg');

Importing into Anki

1. Open Anki
2. File → Import
3. Select the .apkg file
4. The deck and all cards will be imported

Requirements

• Bun runtime
• anki-ts library

License

MIT