BaziKit 八字工具箱

From the team behind AskingMing — AI-powered Bazi (八字) readings.

简体中文 | 繁體中文 | 日本語 | 한국어 | English

Open-source building blocks for Bazi / Four Pillars of Destiny (八字·四柱) on the web. Three packages, each usable independently:

• bazi-engine — computation layer: pass a birth date, time, location and gender; get a complete chart
• bazi-terms — bilingual terminology database (天干、地支、十神、纳音、神煞…)
• bazi-chart — <BaziChart /> React component that renders any chart data

import { computeBazi } from 'bazi-engine';
import { BaziChart } from 'bazi-chart';

const result = computeBazi({
  solar: '1990-03-24 09:54',
  gender: 'male',
  location: { city: '广州' },
});

// BaziResult extends NormalizedChart — drop it straight into the renderer.
<BaziChart data={result} lang="both" theme="light" />

Packages

Package	Description	Dependencies
bazi-engine	Computation layer — four pillars, ten gods, hidden stems, na yin, growth stages, self-sitting, luck pillars, true solar time (Meeus EOT), 88-city table with IANA timezone + historical DST. Pure function, no global state.	lunar-typescript, bazi-terms
bazi-terms	Bilingual terminology database — Heavenly Stems, Earthly Branches, Ten Gods, Shen Sha, Na Yin, Growth Stages, interactions and general chart vocabulary. Framework-agnostic.	zero
bazi-chart	<BaziChart /> React component + adapters that normalize raw chart data into one model. Inline styles, SSR-safe, light/dark, zh / en / both.	react (peer), bazi-terms

Dependency direction is strictly one-way: bazi-terms ← bazi-engine / bazi-chart. The renderer never depends on the engine — bring your own or use ours.

Quick start

Full stack: compute + render

npm install bazi-engine bazi-chart

import { computeBazi } from 'bazi-engine';
import { BaziChart } from 'bazi-chart';

export default function Page() {
  const result = computeBazi({
    solar: '1990-03-24 09:54',
    gender: 'male',
    location: { city: '广州' },
  });
  return <BaziChart data={result} lang="both" theme="light" />;
}

Render only: bring your own engine

npm install bazi-chart

<BaziChart /> auto-detects the two most common community output shapes (a top-level Chinese 八字 object, or a pillars map keyed by year/month/day/hour). For anything else, build a NormalizedChart:

import { BaziChart } from 'bazi-chart';
import type { NormalizedChart } from 'bazi-chart';

const chart: NormalizedChart = {
  meta: { engine: 'normalized' },
  dayMaster: { char: '戊' },
  pillars: [
    { position: 'year',  ganZhi: '庚午', stem: '庚', branch: '午', hiddenStems: [] },
    { position: 'month', ganZhi: '己卯', stem: '己', branch: '卯', hiddenStems: [] },
    { position: 'day',   ganZhi: '戊子', stem: '戊', branch: '子', hiddenStems: [] },
    { position: 'hour',  ganZhi: '丁巳', stem: '丁', branch: '巳', hiddenStems: [] },
  ],
  daYun: [],
  interactions: [],
};

export default () => <BaziChart chart={chart} lang="en" />;

Terminology only

npm install bazi-terms

import { t, translate, tenGodByZh, naYinOf, stemByChar } from 'bazi-terms';

t('dayMaster');            // 'Day Master'
translate('元男');          // 'Day Master'   (engine alias → canonical term)
translate('海中金');         // 'Sea Gold'
naYinOf('甲子')?.en;        // 'Sea Gold'
tenGodByZh('偏官')?.en;      // 'Seven Killings'  (alias of 七杀)
stemByChar('庚')?.element;  // 'metal'

What bazi-engine computes (v1)

Feature	Detail
Four Pillars 四柱	stems, branches, hidden stems with ten gods
Ten Gods 十神	stem-level + hidden-stem-level
Na Yin 纳音	all four pillars
Xun / Kong 旬 / 空亡	per pillar
Growth Stages 十二长生	星运 (Day Master vs branch) + 自坐 (pillar stem vs own branch)
Luck Pillars 大运	direction, onset, ten gods, na yin, isCurrent
Auxiliary Palaces	胎元 · 胎息 · 命宫 · 身宫
True Solar Time 真太阳时	Meeus & approx EOT, IANA timezone, historical DST
City Table	88 cities across 🇨🇳🇭🇰🇲🇴🇹🇼🇯🇵🇰🇷🇸🇬🇲🇾🇹🇭🇮🇩🇻🇳🇵🇭🇺🇸🇨🇦🇦🇺🇬🇧🇫🇷🇩🇪

v2 roadmap: interactions (刑冲合会), shen sha (神煞), five-element scores (五行分值).

Design principles

• Computation + presentation + terminology. Three layers, each independently useful.
• Pure function engine. computeBazi() has no IO, no Date.now(), no global state. Same input → byte-identical output.
• Zero-dependency core. bazi-terms is pure data, usable in any framework or on the server.
• Normalize once, render anywhere. Adapters convert supported input shapes into a single NormalizedChart; raw Chinese values are preserved and translated at render time.
• SSR-safe, no CSS build step. The component uses inline styles only — works in Next.js, Remix, Astro or plain React.

Local development

pnpm install
pnpm -r build      # tsup: ESM + CJS + .d.ts for every package
pnpm -r test       # vitest (172 tests across terms + engine)
pnpm -r typecheck  # tsc --noEmit
cd playground && pnpm dev   # live preview at http://localhost:5180

The playground consumes workspace packages straight from src/ — edits hot-reload instantly, no build needed.

Scope

BaziKit intentionally stops at the chart. It does not provide interpretation, scoring or AI reading text — that judgment layer is the craft we keep in our own product.

License

MIT © 2026 AskingMing.

---

Want an interpretation, not just a chart? → Get a full AI-powered Bazi reading on AskingMing.