How to Use the TypeWords Vocabulary Libraries (CET‑4, IELTS, TOEFL, and More)

TypeWords ships with more than 50 pre‑packaged word libraries covering exams from elementary school through GRE and GMAT, requiring no setup—just select a library and start practicing.

TypeWords is an open‑source typing trainer with built‑in vocabulary libraries for major English proficiency exams. This guide explains how to access, select, and practice with these word sets using the application's core APIs and composables. All vocabulary data is bundled under public/list/, making offline study possible without external downloads.

How TypeWords Organizes Its Vocabulary Libraries

The vocabulary library system in TypeWords follows a three‑layer architecture: a central manifest, a selection UI, and practice session management.

The Library Manifest: public/list/word.json

Every available vocabulary set is declared in public/list/word.json. This JSON file contains metadata for each library including:

• id – unique numeric identifier
• enName – machine‑friendly code (e.g., cet4, ielts, toefl)
• name – human‑readable display name
• url – relative path to the word data file (e.g., CET4_T.json)
• language – target language code
• description – brief summary of contents

Here is a representative excerpt from the manifest:

[
  {
    "id": 1,
    "enName": "cet4",
    "name": "CET-4",
    "url": "list/CET4_T.json",
    "language": "en",
    "description": "College English Test Band 4"
  },
  {
    "id": 2,
    "enName": "cet6",
    "name": "CET-6",
    "url": "list/CET6_T.json",
    "language": "en",
    "description": "College English Test Band 6"
  },
  {
    "id": 3,
    "enName": "ielts",
    "name": "IELTS",
    "url": "list/IELTS_T.json",
    "language": "en",
    "description": "International English Language Testing System"
  },
  {
    "id": 4,
    "enName": "toefl",
    "name": "TOEFL",
    "url": "list/TOEFL_T.json",
    "language": "en",
    "description": "Test of English as a Foreign Language"
  }
]

The actual word data files (like CET4_T.json) contain arrays of word objects with definitions, pronunciations, and example sentences.

The Words API: app/core/apis/words.ts

The server exposes the library catalogue through a single endpoint. In app/core/apis/words.ts, the GET /api/words/list route returns the parsed public/list/word.json array:

// app/core/apis/words.ts (conceptual structure)
import wordList from '~/public/list/word.json'

export default defineEventHandler(() => {
  return wordList.map(item => ({
    id: item.id,
    enName: item.enName,
    name: item.name,
    url: item.url,
    language: item.language,
    description: item.description
  }))
})

This API normalizes the manifest data before sending it to the client, ensuring consistent field names and filtering any internal properties.

Selecting and Loading a Vocabulary Library

Step 1: Fetch Available Libraries

Client‑side code retrieves the catalogue using the words API. The recommended pattern uses $fetch from ofetch (Nuxt's HTTP client):

// Fetch all available vocabulary libraries
import { $fetch } from 'ofetch'

interface WordLibrary {
  id: number
  enName: string
  name: string
  url: string
  language: string
  description: string
}

async function fetchWordLibraries(): Promise<WordLibrary[]> {
  const libraries = await $fetch<WordLibrary[]>('/api/words/list')
  return libraries
}

Step 2: Select and Load a Specific Library

Once you have the catalogue, locate your target library by enName and fetch its word data. The url field points to a static JSON file served from public/.

// Load the CET-4 vocabulary specifically
async function loadCET4Words(): Promise<any[]> {
  const libraries = await fetchWordLibraries()
  
  const cet4 = libraries.find(lib => lib.enName === 'cet4')
  if (!cet4) {
    throw new Error('CET-4 library not found in manifest')
  }
  
  // Fetches /list/CET4_T.json from public directory
  const words = await $fetch<any[]>('/' + cet4.url)
  return words
}

// Similarly for IELTS, TOEFL, GRE, etc.
async function loadIELTSWords(): Promise<any[]> {
  const libraries = await fetchWordLibraries()
  const ielts = libraries.find(lib => lib.enName === 'ielts')
  if (!ielts) throw new Error('IELTS library not found')
  return $fetch<any[]>('/' + ielts.url)
}

The file structure follows a predictable pattern: exam codes map to URL fields like CET4_T.json, CET6_T.json, IELTS_T.json, TOEFL_T.json, GRE_T.json, GMAT_T.json, SAT_T.json, TEM4_T.json, TEM8_T.json, and so on for all 50+ bundled collections.

Step 3: The Selection UI in words.vue

The app/pages/(words)/words.vue component renders the library picker. It:

1. Calls fetchWordLibraries() on mount
2. Displays each library's name and description
3. Emits the selected library's metadata to trigger word loading

<!-- Simplified structure of words.vue -->
<script setup lang="ts">
const { data: libraries } = await useFetch('/api/words/list')

function selectLibrary(lib: WordLibrary) {
  navigateTo(`/?library=${lib.enName}`)
}
</script>

<template>
  <div class="library-grid">
    <div 
      v-for="lib in libraries" 
      :key="lib.id"
      class="library-card"
      @click="selectLibrary(lib)"
    >
      <h3>{{ lib.name }}</h3>
      <p>{{ lib.description }}</p>
      <span class="word-count">{{ lib.language }}</span>
    </div>
  </div>
</template>

Starting a Practice Session

Initialize with usePracticeWordSession

After loading words, pass them to the practice session composable at app/core/composables/practice-words/usePracticeWordSession.ts. This composable initializes the FSRS‑based spaced repetition system and manages review scheduling.

import { loadCET4Words } from './vocabulary-loader'
import { usePracticeWordSession } from '@/app/core/composables/practice-words/usePracticeWordSession'

async function startCET4Practice() {
  // 1. Load vocabulary data
  const words = await loadCET4Words()
  
  // 2. Initialize practice session
  const session = usePracticeWordSession({ words })
  
  // 3. Start the learning cycle
  session.start()
  
  return session
}

The usePracticeWordSession composable accepts configuration including:

• words – the array of vocabulary items to study
• Optional settings for daily word limits and review ratios

Navigate Exercises with usePracticeWordNavigator

Individual word exercises are handled by app/core/composables/practice-words/usePracticeWordNavigator.ts. This composable:

• Tracks current word index
• Manages input state and accuracy scoring
• Handles audio pronunciation playback via useWordPracticeAudio

import { usePracticeWordNavigator } from '@/app/core/composables/practice-words/usePracticeWordNavigator'

function setupWordNavigation(session: PracticeSession) {
  const navigator = usePracticeWordNavigator(session)
  
  // Advance to next word after successful typing
  navigator.next()
  
  // Replay pronunciation
  navigator.playAudio()
}

Complete Working Example

Here is a consolidated script demonstrating the full workflow from library selection to active practice:

// complete-vocabulary-practice.ts
import { $fetch } from 'ofetch'
import { usePracticeWordSession } from '@/app/core/composables/practice-words/usePracticeWordSession'

interface WordLibrary {
  id: number
  enName: string
  name: string
  url: string
  language: string
  description: string
}

class VocabularyPractice {
  private libraries: WordLibrary[] = []
  
  async initialize() {
    this.libraries = await $fetch<WordLibrary[]>('/api/words/list')
    console.log(`Loaded ${this.libraries.length} vocabulary libraries`)
    return this.libraries
  }
  
  findLibrary(enName: string): WordLibrary | undefined {
    return this.libraries.find(lib => lib.enName === enName)
  }
  
  async loadWords(enName: string): Promise<any[]> {
    const lib = this.findLibrary(enName)
    if (!lib) throw new Error(`Library "${enName}" not found`)
    
    const words = await $fetch<any[]>('/' + lib.url)
    console.log(`Loaded ${words.length} words from ${lib.name}`)
    return words
  }
  
  async startPractice(enName: string) {
    const words = await this.loadWords(enName)
    const session = usePracticeWordSession({ words })
    session.start()
    return session
  }
}

// Usage
const practice = new VocabularyPractice()
await practice.initialize()

// Start any supported exam vocabulary
await practice.startPractice('cet4')   // CET-4
await practice.startPractice('cet6')   // CET-6
await practice.startPractice('ielts')  // IELTS
await practice.startPractice('toefl')  // TOEFL
await practice.startPractice('gre')    // GRE
await practice.startPractice('gmat')   // GMAT
await practice.startPractice('sat')    // SAT

Library Identifiers Reference

Exam/Library	enName Code	File Name
CET‑4	cet4	CET4_T.json
CET‑6	cet6	CET6_T.json
IELTS	ielts	IELTS_T.json
TOEFL	toefl	TOEFL_T.json
GRE	gre	GRE_T.json
GMAT	gmat	GMAT_T.json
SAT	sat	SAT_T.json
TEM‑4	tem4	TEM4_T.json
TEM‑8	tem8	TEM8_T.json

Additional libraries for elementary, middle, and high school vocabularies use corresponding enName codes defined in public/list/word.json.

Summary

• TypeWords bundles 50+ vocabulary libraries for major exams and study levels, all declared in public/list/word.json
• The words API (app/core/apis/words.ts) serves this manifest at GET /api/words/list
• Users select libraries through the words.vue interface, which fetches word data from static JSON files
• Practice sessions initialize via usePracticeWordSession with FSRS‑powered scheduling
• No external setup required—all data is packaged with the application for offline use

Frequently Asked Questions

Where are the vocabulary word lists stored in TypeWords?

All vocabulary data resides in public/list/ as individual JSON files (e.g., CET4_T.json, IELTS_T.json). The master catalogue at public/list/word.json maps library identifiers to these file paths. Because files are in the public/ directory, they are served as static assets without requiring a database.

Can I add custom vocabulary libraries to TypeWords?

Yes. Create a JSON file following the existing word format (array of objects with word, definition, pronunciation, example fields), place it in public/list/, and add an entry to public/list/word.json with a unique enName and url pointing to your file. The existing words.ts API and words.vue UI will automatically include your library.

How does TypeWords handle progress tracking across different vocabularies?

Each practice session maintains independent FSRS scheduling state keyed by word ID. The usePracticeWordSession composable persists review intervals and difficulty ratings to local storage or a backend (depending on configuration), ensuring that switching between CET‑4 and IELTS vocabularies preserves separate learning progress for each word set.

What is the difference between usePracticeWordSession and usePracticeWordNavigator?

usePracticeWordSession (in usePracticeWordSession.ts) manages the learning lifecycle: spaced‑repetition scheduling, daily review queues, and progress statistics. usePracticeWordNavigator (in usePracticeWordNavigator.ts) handles exercise‑level interaction: advancing between words, validating typed input, and triggering audio pronunciation. The session composable owns the data; the navigator composable owns the UI flow.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}