Pokemon TCG Pocket Database

Common errors

• Cannot find module 'pokemon-tcg-pocket-database/dist/cards.json'

  cause Incorrect import path or missing JSON module resolution configuration for CommonJS environments or TypeScript projects.
  fix Ensure you are using an ESM environment with Node.js 16+ or a bundler configured to handle direct JSON imports. For TypeScript, add `"resolveJsonModule": true` and `"esModuleInterop": true` to your `tsconfig.json`.

• Image not found when attempting to load a card asset (e.g., '.../assets/A1/card-1.webp')

  cause The image asset path structure changed significantly in v2.1.0, moving to a `cards-by-set` directory with predictable `set/number.webp` naming.
  fix Update image path generation logic to `cards-by-set/${card.set}/${card.number}.webp`. Verify the base path where the `cards-by-set` directory is located relative to your assets.

Warnings

• breaking Version 2.0.0 introduced significant breaking changes, requiring a migration guide. This includes changes to data structures and file organization from v1.
  Fix: Refer to the `CHANGELOG.md` file in the repository for the migration guide from v1 to v2, specifically the '2.0.0 - Scizor: Reduce and Split' entry.
• breaking The `image` field in `cards.min.json` was removed in v2.1.0. The package also introduced `cards.no-image.min.json` and standardized image paths into a new directory structure.
  Fix: For smaller bundles without card images, use `cards.no-image.min.json`. To programmatically access images, construct paths using `cards-by-set/${card.set}/${card.number}.webp`.
• breaking The `packs` field was removed from card objects in `cards.json` and its variants starting from v2.2.0, as it was often empty or redundant.
  Fix: Update any code relying on the `packs` field on card objects. Review card data structures if migrating from versions prior to 2.2.0.

Install

• npm install pokemon-tcg-pocket-database npm
• yarn add pokemon-tcg-pocket-database yarn
• pnpm add pokemon-tcg-pocket-database pnpm

Imports

• cards
  wrong:

  import { cards } from 'pokemon-tcg-pocket-database';

  correct:

  import cards from 'pokemon-tcg-pocket-database/dist/cards.json';

  JSON files are direct module imports; named imports from the root package are incorrect. Prefer `cards.min.json` for reduced size.
• sets
  wrong:

  const sets = require('pokemon-tcg-pocket-database/dist/sets.json');

  correct:

  import sets from 'pokemon-tcg-pocket-database/dist/sets.json';

  While Node.js 16+ supports 'require' for JSON, ESM `import` is the recommended and future-proof approach for direct JSON file access in modern JavaScript/TypeScript projects.
• rarities
  wrong:

  import rarities from 'pokemon-tcg-pocket-database/rarities.json';

  correct:

  import rarities from 'pokemon-tcg-pocket-database/dist/rarities.json';

  Always specify the full path including `/dist/` as the package entry points for data files are not at the root. Direct JSON imports require proper bundler/TypeScript configuration.

Quickstart

Demonstrates how to import the various JSON data files and access basic information about sets, cards, and rarities, including generating card image paths.

import sets from 'pokemon-tcg-pocket-database/dist/sets.json';
import cards from 'pokemon-tcg-pocket-database/dist/cards.min.json';
import rarities from 'pokemon-tcg-pocket-database/dist/rarities.json';

// Log basic database information
console.log(`Total sets available: ${Object.keys(sets).length}`);
console.log(`Total cards available: ${cards.length}`);
console.log(`Total rarities defined: ${Object.keys(rarities).length}`);

// Example: Find the first set and some of its cards
const firstSeriesKey = Object.keys(sets)[0]; // e.g., 'A'
const firstSetInSeries = sets[firstSeriesKey] ? sets[firstSeriesKey][0] : null;

if (firstSetInSeries) {
  console.log(`\nFirst set in database: ${firstSetInSeries.name} (${firstSetInSeries.id})`);
  const cardsInFirstSet = cards.filter(card => card.set === firstSetInSeries.id);
  console.log(`Cards in ${firstSetInSeries.name}: ${cardsInFirstSet.slice(0, 3).map(c => c.name).join(', ')}...`);

  // Example of calculating an image path (v2.1.0+ structure)
  if (cardsInFirstSet.length > 0) {
    const exampleCard = cardsInFirstSet[0];
    const imagePath = `cards-by-set/${exampleCard.set}/${exampleCard.number}.webp`;
    console.log(`Example image path for '${exampleCard.name}': ${imagePath}`);
  }
}

// Example: Accessing a specific rarity
const commonRarity = rarities['C'];
if (commonRarity) {
  console.log(`\nRarity 'C' details: Name = ${commonRarity.name}, Cost = ${commonRarity.cost}`);
}