@bafv4/mcitems

Minecraft item data, textures, and translations for React and Vue applications with multi-version support.

Installation

# From GitHub
pnpm add github:bafv4/mcitems

# Or with a specific tag
pnpm add github:bafv4/mcitems#v2.0.0

Features

• Multi-Version Support: Separate modules for different Minecraft versions
• Item Data: Complete list of Minecraft items organized by Creative Inventory categories
• Textures: PNG textures for all items and blocks
• Translations: All 125 official Minecraft languages (en_us + ja_jp bundled, others loadable on demand)
• React Component: MinecraftItemIcon for displaying item icons
• Vue Component: MinecraftItemIcon for Vue 3 applications
• Potion Effects: Full support for potion effect variants
• Framework Independent: React and Vue are optional peer dependencies

Supported Versions

Version	Import Path	Status
1.16.x	@bafv4/mcitems/1.16	Supported
1.20.x	@bafv4/mcitems/1.20	Coming Soon
1.21.x	@bafv4/mcitems/1.21	Coming Soon

Usage

React

import { MinecraftItemIcon, getAllItems } from '@bafv4/mcitems/1.16/react';

// Basic usage
<MinecraftItemIcon itemId="minecraft:diamond_sword" size={48} />

// With potion effect
<MinecraftItemIcon
  itemId="minecraft:potion"
  nbtData={{ Potion: 'minecraft:fire_resistance' }}
  size={32}
/>

// With custom texture base URL
<MinecraftItemIcon
  itemId="minecraft:iron_pickaxe"
  textureBaseUrl="/assets/mcitems"
  size={48}
/>

// Using data functions
const items = getAllItems();

Vue

<script setup lang="ts">
import { MinecraftItemIcon, getAllItems } from '@bafv4/mcitems/1.16/vue';

const items = getAllItems();
</script>

<template>
  <!-- Basic usage -->
  <MinecraftItemIcon itemId="minecraft:diamond_sword" :size="48" />

  <!-- With potion effect -->
  <MinecraftItemIcon
    itemId="minecraft:potion"
    :nbtData="{ Potion: 'minecraft:fire_resistance' }"
    :size="32"
  />

  <!-- With custom texture base URL -->
  <MinecraftItemIcon
    itemId="minecraft:iron_pickaxe"
    textureBaseUrl="/assets/mcitems"
    :size="48"
  />
</template>

Core Functions Only (No Framework)

import { getAllItems, formatItemName, MINECRAFT_VERSION } from '@bafv4/mcitems/1.16';

console.log(MINECRAFT_VERSION); // "1.16"

const items = getAllItems();
const name = formatItemName('minecraft:diamond_sword');

Item Data Functions

import {
  getAllItems,
  getItemsByCategory,
  getCraftableItems,
  searchItems,
  formatItemName,
  ITEM_CATEGORIES,
} from '@bafv4/mcitems/1.16';

// Get all items
const items = getAllItems();

// Get items by category
const tools = getItemsByCategory('tools');

// Get craftable items only (for recipe search)
const craftable = getCraftableItems();

// Search items (by ID or display name in the given language)
const results = searchItems('diamond');
const jaResults = searchItems('ダイヤ'); // Japanese works too

// Format item name (Japanese by default)
const name = formatItemName('minecraft:diamond_sword');
// => 'ダイヤモンドの剣'

// Available categories
ITEM_CATEGORIES.forEach(cat => {
  console.log(cat.id, cat.name);
});

Translations (125 Languages)

Item names are available in every official Minecraft language. en_us and ja_jp are bundled; other languages are loaded at runtime or bundled explicitly.

import {
  getItemName,
  formatItemName,
  loadLang,
  registerLang,
  isLangLoaded,
  getCategoryName,
  getEffectName,
  AVAILABLE_LANGS, // all 125 language codes
  BUNDLED_LANGS,   // ['en_us', 'ja_jp']
} from '@bafv4/mcitems/1.16';

// Bundled languages work synchronously out of the box
getItemName('minecraft:diamond_sword', 'ja_jp'); // => 'ダイヤモンドの剣'
getItemName('minecraft:diamond_sword');          // => 'Diamond Sword' (en_us)

// Potion variant IDs resolve to full vanilla names
getItemName('minecraft:splash_potion.fire_resistance', 'ja_jp');
// => '耐火のスプラッシュポーション'

// Load any other language at runtime (see "Language File Setup" below)
await loadLang('de_de', '/mcitems');
getItemName('minecraft:diamond_sword', 'de_de'); // => 'Diamantschwert'

// formatItemName always returns a string (lang → en_us → Title Case fallback)
formatItemName('minecraft:diamond_sword', 'de_de'); // => 'Diamantschwert'

// Category (creative tab) and status effect names
getCategoryName('brewing', 'ja_jp');              // => '醸造'
getEffectName('minecraft:night_vision', 'en_us'); // => 'Night Vision'

Alternatively, bundle a language into your app instead of fetching it:

// Bundlers (Vite / webpack / Next.js) handle the JSON import as-is:
import koKr from '@bafv4/mcitems/1.16/lang/ko_kr';
// Plain Node.js ESM requires the import attribute instead:
// import koKr from '@bafv4/mcitems/1.16/lang/ko_kr' with { type: 'json' };
import { registerLang, getItemName } from '@bafv4/mcitems/1.16';

registerLang('ko_kr', koKr);
getItemName('minecraft:diamond_sword', 'ko_kr'); // => '다이아몬드 검'

Typical language-switching pattern (e.g. reacting to a user setting):

async function setLanguage(lang: string) {
  await loadLang(lang, LANG_BASE_URL); // no-op if already loaded
  rerender(); // all getItemName/formatItemName calls are now synchronous
}

Potion Effects

import {
  POTION_EFFECTS,
  getPotionEffectInfo,
  formatPotionName,
  formatPotionEffect,
} from '@bafv4/mcitems/1.16';

// Get potion info
const info = getPotionEffectInfo('minecraft:fire_resistance');
// => { id: 'minecraft:fire_resistance', name: '火炎耐性', variant: 12, duration: '3:00' }

// Format potion name (official vanilla names, language-aware)
const name = formatPotionName('minecraft:splash_potion', 'minecraft:fire_resistance');
// => '耐火のスプラッシュポーション'
formatPotionName('minecraft:splash_potion', 'minecraft:fire_resistance', 'en_us');
// => 'Splash Potion of Fire Resistance'

// Format effect with duration
const effect = formatPotionEffect('minecraft:long_fire_resistance');
// => '火炎耐性 (8:00)'
formatPotionEffect('minecraft:strong_leaping', 'en_us');
// => 'Jump Boost (3:00)'

Texture Setup

Textures are included in dist/textures/ after building. You need to serve them statically:

Next.js

Copy textures to public/ folder:

cp -r node_modules/@bafv4/mcitems/dist/textures public/mcitems

Then use with textureBaseUrl:

<MinecraftItemIcon
  itemId="minecraft:diamond"
  textureBaseUrl="/mcitems"
/>

Vite (React / Vue)

Add to vite.config.ts:

import { viteStaticCopy } from 'vite-plugin-static-copy';

export default defineConfig({
  plugins: [
    viteStaticCopy({
      targets: [
        {
          src: 'node_modules/@bafv4/mcitems/dist/textures',
          dest: 'assets',
        },
      ],
    }),
  ],
});

Nuxt 3

Copy textures to public/ folder:

cp -r node_modules/@bafv4/mcitems/dist/textures public/mcitems

Then use with textureBaseUrl:

<MinecraftItemIcon
  itemId="minecraft:diamond"
  textureBaseUrl="/mcitems"
/>

Language File Setup

Only en_us and ja_jp are bundled in the JS build. To use loadLang(), serve the language files from dist/1.16/lang/ statically (same approach as textures). loadLang(code, baseUrl) fetches ${baseUrl}/1.16/lang/${code}.json.

Next.js / Nuxt 3

mkdir -p public/mcitems/1.16
cp -r node_modules/@bafv4/mcitems/dist/1.16/lang public/mcitems/1.16/lang

await loadLang('de_de', '/mcitems');

Vite (React / Vue)

import { viteStaticCopy } from 'vite-plugin-static-copy';

export default defineConfig({
  plugins: [
    viteStaticCopy({
      targets: [
        { src: 'node_modules/@bafv4/mcitems/dist/1.16/lang', dest: 'mcitems/1.16' },
      ],
    }),
  ],
});

await loadLang('de_de', '/mcitems');

Regenerating Language Files (maintainers)

pnpm run gen-lang   # downloads official 1.16.5 lang files from Mojang and rebuilds src/assets/lang/

Item Categories

ID	Name
all	すべて
building_blocks	建築ブロック
decorations	装飾ブロック
redstone	レッドストーン
transportation	交通
miscellaneous	雑貨
foodstuffs	食料
tools	道具
combat	戦闘
brewing	醸造

API Reference

Components

• MinecraftItemIcon (React) - React component for displaying item icons (@bafv4/mcitems/1.16/react)
• MinecraftItemIcon (Vue) - Vue 3 component for displaying item icons (@bafv4/mcitems/1.16/vue)

Functions

• getAllItems() - Get all item IDs
• getItemsByCategory(category) - Get items by category
• getCraftableItems() - Get craftable items only
• getCraftableItemsByCategory(category) - Get craftable items by category
• searchItems(query, lang?) - Search items by ID or display name
• formatItemName(itemId, lang?) - Format item ID to display name (default: Japanese)
• getItemName(itemId, lang?) - Get item display name (default: en_us, falls back to en_us)
• getEffectName(effectId, lang?) - Get status effect display name
• getCategoryName(category, lang?) - Get creative tab display name
• loadLang(code, baseUrl?) - Fetch and register a language at runtime
• registerLang(code, dict) - Register an imported language dictionary
• isLangLoaded(code) - Whether a language is ready for synchronous lookup
• getLangUrl(code, baseUrl?) - Get language file URL
• getItemNameJa(itemId) - Get Japanese translation (deprecated: use getItemName(id, 'ja_jp'))
• getTextureUrl(itemId, nbtData, baseUrl) - Get texture URL
• getPotionEffectInfo(effect) - Get potion effect info
• formatPotionName(itemId, effect, lang?) - Format potion display name
• formatPotionEffect(effect, lang?) - Format effect with duration

Constants

• MINECRAFT_VERSION - Version string (e.g., "1.16")
• TEXTURE_PATH - Texture path pattern (e.g., "1.16.1/items")
• LANG_PATH - Language file path pattern ("1.16/lang")
• AVAILABLE_LANGS - All 125 language codes
• BUNDLED_LANGS - Languages bundled in the JS build (['en_us', 'ja_jp'])
• MINECRAFT_ITEMS - Items organized by category
• ITEM_CATEGORIES - Category definitions
• POTION_EFFECTS - Potion effect data

Types

• ItemCategory - Category type union
• MinecraftItem - Item interface
• NBTItem - NBT item structure
• PotionEffectInfo - Potion effect info interface
• LangDict - Language dictionary (Record<string, string>)

Adding New Versions

To add support for a new Minecraft version:

1. Create a new version folder: src/versions/1.20/
2. Copy and modify the data files (items.ts, potionEffects.ts, translations.ts)
3. Update TEXTURE_PATH constant for the new version
4. Add entry points to tsup.config.ts
5. Add exports to package.json

License

MIT