formkit-core-skilld

@formkit/core 2.1.2

FormKit のフレームワーク非依存のコアです。すべての入力、グループ、リスト、フォームは、ツリー内の FormKitNode です。Vue と React のアダプター（@formkit/vue、@formkit/react）がこれらのノードをレンダリングします。入力タイプ、バリデーション、i18n はここではなく、関連パッケージに含まれています。この Skill の対象は @formkit/core のインポートだけに限定してください。

• パッケージ：@formkit/[email protected]。ESM（"type": "module"）と CJS フォールバックに加えて、development 条件のビルドもあります（package.json:8-21）。
• 唯一の依存関係：@formkit/utils@^2.1.2（package.json:38-40）。
• ドキュメント：https://formkit.com/essentials/architecture
• API リファレンス：https://formkit.com/api-reference/core

別のパッケージを使用する場面

必要なもの	パッケージ
<FormKit> コンポーネント、defaultConfig、createInput	@formkit/vue / @formkit/react
入力タイプの定義（text、select…）	@formkit/inputs
バリデーションルール	@formkit/validation
ロケールメッセージ	@formkit/i18n
スキーマのレンダリング	@formkit/vue（型とコンパイラーはこちらにあります）

公開 API

実行時エクスポート（dist/index.mjs:1919）：bfs、clearErrors、compile、createClasses、createConfig、createMessage、createNode、createPlaceholder、createValue、deregister、error、errorHandler、generateClassList、getNode、isComponent、isConditional、isDOM、isList、isNode、isPlaceholder、isSugar、names、register、reset、resetCount、resetRegistry、setErrors、stopWatch、submitForm、sugar、use、useIndex、valueInserted、valueMoved、valueRemoved、warn、warningHandler、watchRegistry、FORMKIT_VERSION — さらに約70の公開型があります（dist/index.d.mts:2329）。

よくあるタスク

ノードツリーを作成する

import { createNode } from '@formkit/core'

const email = createNode({ name: 'email' })
const form = createNode({
  type: 'group',            // 'input' (default) | 'group' | 'list'
  children: [email, createNode({ name: 'password' })],
})
form.at('email')            // → the email node

グループの値は、子の name をキーとするオブジェクトです。リストの値は、子のインデックスをキーとする配列です（dist/index.mjs:714-723）。オプションの全一覧は、ノード APIを参照してください。

値を設定して、確定を待つ

await email.input('[email protected]')  // debounced, async commit
email.value                            // committed value

node.value = x を直接代入しないでください。input() はデバウンスを行い（入力ノードではデフォルトで20 ms、dist/index.mjs:1255-1267）、その後 commit フックを通じて確定します（dist/index.mjs:759-765）。await node.settled は、サブツリー全体の確定が完了すると解決します（dist/index.d.mts:1856-1860）。

イベントをリッスンする（およびクリーンアップする）

const receipt = form.on('commit.deep', ({ payload }) => { ... })
// later:
form.off(receipt)

.deep は、子孫からバブリングするイベントを捕捉します（dist/index.mjs:47-53）。on() はレシートを返すため、必ず off() に渡してください。コアイベント一覧は、イベントとフックを参照してください。

フックミドルウェアを登録する

node.hook.commit((value, next) => next(transform(value)))

ミドルウェアのシグネチャは (payload, next) => next(payload) です。フックは classes、commit、error、setErrors、init、input、message、prop、text、schema です（dist/index.d.mts:579-600）。再利用する場合は、プラグイン内で登録してください。

プラグインを作成する

import { createNode } from '@formkit/core'
import type { FormKitPlugin } from '@formkit/core'

const colorize: FormKitPlugin = (node) => {
  node.props.color = node.type === 'group' ? 'yellow' : 'teal'
  // return false to stop inheritance by children
}
createNode({ type: 'group', plugins: [colorize], children: [createNode()] })

プラグインは子孫に継承され、ノードごとに一度実行されます。plugin.library を設定すると、node.define() を通じてカスタム入力タイプを定義できます。

メッセージを保存する。台帳で数を管理する

import { createMessage, createNode } from '@formkit/core'

const node = createNode()
node.store.set(createMessage({ key: 'limit', value: 'Too many!' }))
node.store.limit.value                       // 'Too many!'
node.ledger.count('visible', (m) => m.visible)
node.on('count:visible', ({ payload }) => console.log(payload))

詳細は、ストアと台帳を参照してください。

ID でノードを取得する

import { createNode, getNode, watchRegistry, stopWatch } from '@formkit/core'

const node = createNode({ props: { id: 'manufacturer' } }) // root nodes register
getNode('manufacturer')                    // FormKitNode | undefined
const receipt = watchRegistry('manufacturer', (e) => { ... })
stopWatch(receipt)

ルートノード（または props.alias を持つノード）は自動的に登録されます（dist/index.d.mts:2220-2228）。詳細は、レジストリとヘルパーを参照してください。

エラーを設定し、リセットし、送信する

import { setErrors, clearErrors, reset, submitForm } from '@formkit/core'

setErrors('myForm', 'Server rejected', { email: ['Already taken'] })
reset('myForm', { email: '' })   // resetTo becomes the new initial value
clearErrors('myForm', true)      // true clears children too
submitForm('myForm')             // dispatches a submit DOM event

スキーマ式をコンパイルする

import { compile } from '@formkit/core'

const condition = compile("$name == 'bob'").provide((tokens) => {
  return { name: () => nameRef.value }   // each token must return a function
})
condition()  // false

演算子：&& || == != === !== > < >= <= + - * / %（dist/index.mjs:1574-1598）。スキーマのノードタイプとガードについては、スキーマとコンパイラーを参照してください。

バグを防ぐための動作ルール

• 設定は node.config ではなく node.props を通じて読み取ってください。明示的な props と親の設定は props にマージされます（dist/index.d.mts:729-792）。
• ルートの設定プロパティを設定すると、起点のノードで config:{prop} が発行され、そのプロパティを上書きしない継承先の各ノードで prop / prop:{prop} が発行されます（dist/index.mjs:1283-1289）。
• group ノードにはオブジェクト値、list ノードには配列が必要です。違反するとエラー 107 / 108 がスローされます（dist/index.mjs:745-757）。
• メッセージは不変です（Readonly<FormKitMessageProps>、dist/index.d.mts:70-75）。変更する場合は store.set() で置き換え、決して直接変更しないでください。
• node.walk() はノード自身を含めずにサブツリーを走査し、処理コストも高いため、まれなライフサイクルのタイミングに限って使用してください（dist/index.d.mts:1885-1890）。
• 1 つの親の下に同じ name を持つ兄弟ノードを 2 つ置かないでください。避けられない場合は、config.mergeStrategy = { fieldName: 'synced' } で同期してください（dist/index.d.mts:721-725）。
• node.root は読み取るたびに走査するため、ホットパスでは呼び出さないでください（dist/index.d.mts:1840-1843）。
• コアのエラー処理を置き換えるには、エクスポートされた errorHandler / warningHandler ディスパッチャーにミドルウェアを登録してください（dist/index.d.mts:2151-2157）。

バージョンの制限

• @formkit/[email protected]（2026-07-24 公開）を対象に記述しています。
• 2.0.0 以降の 2.x の変更は、リセット、レジストリのクリーンアップ、コンパイラーに関するバグ修正です。コア API の破壊的変更はありません。API の変更を参照してください。
• FORMKIT_VERSION は、準備済みソース内のビルド時プレースホルダー（"__FKV__"）です。これを基に条件分岐しないでください（dist/index.d.mts:2321-2327）。

参考資料

• ノード API — 作成、型、トラップ、値のフロー、確定、走査
• イベントとフック — エミッター、レシート、.deep、イベントテーブル、フックミドルウェア
• ストアと台帳 — メッセージ、createMessage、カウンター
• 設定、props、プラグイン — 継承、createConfig、mergeStrategy、ライブラリ
• スキーマとコンパイラー — スキーマノードの型、ガード、sugar()、compile()
• レジストリとヘルパー — getNode、setErrors、reset、submitForm、エラーコード
• API の変更 — 2.0.0 → 2.1.2