bp-svelte

Stars0

Forks0

UpdatedJuly 2, 2026 at 12:36

Svelte 5 / SvelteKit / TypeScript ベストプラクティス(moka-web 向け)。Runes ベースのコンポーネント設計、SvelteKit データフロー、型安全性の規約。

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Source

Kaikei-e

Kaikei-e/moka-1

View GitHub Repository View Creator Repositories

Download

Related occupationsSOC

Based on SOC occupation classification

Web DevelopersComputer and Mathematical Occupations·SOC 15-1254

SKILL.md

readonly

name	bp-svelte
description	Svelte 5 / SvelteKit / TypeScript ベストプラクティス(moka-web 向け)。Runes ベースのコンポーネント設計、SvelteKit データフロー、型安全性の規約。

Svelte 5 & SvelteKit & TypeScript Best Practices (moka-web)

Svelte 5 Runes

Runes のみ: $state / $derived / $effect。レガシー $: リアクティブ宣言・export let は禁止

Props は $props() + 型:

<script lang="ts">
  import type { Snippet } from 'svelte';
  let { article, onRead, children }: {
    article: Article; onRead?: (id: string) => void; children?: Snippet;
  } = $props();
</script>

導出は $derived / $derived.by、副作用だけ $effect。$effect 内で状態を組み立て始めたら $derived.by に書き直す
$effect は cleanup を返す: EventSource / IntersectionObserver / タイマーは return で解放。DOM 要素に紐づくものは {@attach ...}(attachments、use: アクションの後継)を優先
大きく置換されるデータは $state.raw: 記事リスト・検索結果は要素単位の deep reactivity が不要。proxy コストを避け、更新は再代入で。シリアライズは $state.snapshot()
合成は snippet: {#snippet row(item)} + {@render row(x)}。slot は非推奨
$app/state を使う($app/stores は非推奨): page.url 等は $app/state から

SvelteKit データフロー

初期データは load 関数: +page.server.ts の load で moka-core から取得。コンポーネント内 fetch で初期データを組むと waterfall になる
更新系は form actions + use:enhance(既読化・フィード購読・Q&A 送信)。JS 無効でも動く progressive enhancement を既定に
remote functions(2.27+)は当面使わない: 実験フラグ(kit.experimental.remoteFunctions + compilerOptions.experimental.async)が要る段階。再検討トリガー: 実験フラグが外れて安定化したら、クライアント起点の再取得(ハイライト再生成ボタン等)を query/command に置き換える価値を評価
moka-core へのアクセスはサーバー側に寄せる: +page.server.ts / +server.ts 経由。ブラウザ→moka-core 直行のパスを作る場合は plecto/manifest.toml のルーティングと必ず整合させる
エージェントの進行通知は SSE: 濃縮・ハイライト生成の進捗は +server.ts から text/event-stream。WebSocket は入れない(ミニマリズム)
ストリーミング load: 重い付加データ(関連記事等)は load から Promise のまま返して {#await} で受ける。ページ骨格を先に出す

TypeScript

strict: true + noUncheckedIndexedAccess + verbatimModuleSyntax: 必須。弱めない。型のみインポートは import type
境界では unknown → Zod: moka-core レスポンスは Zod スキーマ(単一の lib/api/schemas.ts に集約)で parse してから使う。as キャスト・! 非 null アサーション禁止
判別共用体 + 網羅性: enrichment_status のような状態は tagged union にし、switch の default で satisfies never
satisfies でリテラル推論保持: ルート表・設定オブジェクトは satisfies Record<...> で検査しつつ推論を殺さない
型ガード > アサーション: value is T の predicate を書く。Zod があるので手書きガードは境界の外側だけ

テスト

コンポーネントは vitest-browser-svelte(実ブラウザ実行)。jsdom でのコンポーネントテストは書かない
純ロジック(日付整形・RRF スコア表示等)は node 環境の vitest に分離。コンポーネントに埋めずに lib/ へ抽出してからテスト
E2E(Playwright)の規約は tdd-workflow スキル参照

moka-1 固有

ミニマル UI 原則: 「読む」体験が主。3D 可視化・アニメーションライブラリ・重い UI キットは tenets §3.4 で不採用決定済み。新規依存はまず疑い、追加するなら bundle への影響を報告
LLM 由来テキストの表示規約: 要約・ハイライト理由には「AI 生成」の視覚的区別を付ける。</think> が漏れて表示されたらそれは moka-core 側のバグ(internal/llm の一元除去に違反)— UI 側で握りつぶさず報告する

参照

docs/tenets/moka-tenets.md — 本スキルの「tenets §N」参照はこの文書の節番号

More from this repository

same repository

bp-rust-wasm

Kaikei-e/moka-1

Rust ベストプラクティス(Plecto WASM フィルタ向け、Edition 2024)。plecto:filter WIT コントラクトを実装する WASM Component Model フィルタの規約とツールチェーン。

2026-07-210

grill-with-docs

Kaikei-e/moka-1

Grilling session that challenges your plan against moka-1's documented design decisions (tenets, ADRs) and domain model, sharpens terminology, and updates documentation (CONTEXT.md, ADRs) inline as decisions crystallise. Use when the user wants to stress-test a plan against the project's language and documented decisions, or says 「設計を詰めて」「用語を固めて」「ドキュメントと突き合わせて」.

2026-07-030

clean-architecture

Kaikei-e/moka-1

クリーンアーキテクチャの依存ルールを moka-1 のミニマリズム制約下で適用する指針。レイヤ分割・interface 設計・依存方向の判断基準と、過剰抽象化を避けるガードレールを提供する。

2026-07-030

web-research

Kaikei-e/moka-1

Web調査の方法論。一次ソース(RFC・公式仕様・公式ドキュメント・原論文・ソースコード)を最優先し、検索クエリの多角化・横断的検証(lateral reading)・独立ソースでの三角測量を経て、出典付きで報告する手順。

2026-07-030

docker-compose

Kaikei-e/moka-1

moka-1 スタックの Docker Compose 操作と compose.yaml の書き方。ワンキック起動・開発ループ・ヘルスチェック・開発機(iGPU/Vulkan)固有設定・トラブルシュート。

2026-07-020

bp-go

Kaikei-e/moka-1

Go ベストプラクティス(moka-core 向け、Go 1.26+)。常駐エージェントループ・LLM クライアント・フィード取得を含む moka-core の実装規約。

2026-07-020

Svelte 5 & SvelteKit & TypeScript Best Practices (moka-web)

Svelte 5 Runes

Runes のみ: $state / $derived / $effect。レガシー $: リアクティブ宣言・export let は禁止

Props は $props() + 型:

<script lang="ts">
  import type { Snippet } from 'svelte';
  let { article, onRead, children }: {
    article: Article; onRead?: (id: string) => void; children?: Snippet;
  } = $props();
</script>

導出は $derived / $derived.by、副作用だけ $effect。$effect 内で状態を組み立て始めたら $derived.by に書き直す

$effect は cleanup を返す: EventSource / IntersectionObserver / タイマーは return で解放。DOM 要素に紐づくものは {@attach ...}(attachments、use: アクションの後継)を優先

大きく置換されるデータは $state.raw: 記事リスト・検索結果は要素単位の deep reactivity が不要。proxy コストを避け、更新は再代入で。シリアライズは $state.snapshot()

合成は snippet: {#snippet row(item)} + {@render row(x)}。slot は非推奨

$app/state を使う($app/stores は非推奨): page.url 等は $app/state から

SvelteKit データフロー

初期データは load 関数: +page.server.ts の load で moka-core から取得。コンポーネント内 fetch で初期データを組むと waterfall になる

更新系は form actions + use:enhance(既読化・フィード購読・Q&A 送信)。JS 無効でも動く progressive enhancement を既定に

remote functions(2.27+)は当面使わない: 実験フラグ(kit.experimental.remoteFunctions + compilerOptions.experimental.async)が要る段階。再検討トリガー: 実験フラグが外れて安定化したら、クライアント起点の再取得(ハイライト再生成ボタン等)を query/command に置き換える価値を評価

moka-core へのアクセスはサーバー側に寄せる: +page.server.ts / +server.ts 経由。ブラウザ→moka-core 直行のパスを作る場合は plecto/manifest.toml のルーティングと必ず整合させる

エージェントの進行通知は SSE: 濃縮・ハイライト生成の進捗は +server.ts から text/event-stream。WebSocket は入れない(ミニマリズム)

ストリーミング load: 重い付加データ(関連記事等)は load から Promise のまま返して {#await} で受ける。ページ骨格を先に出す

TypeScript

strict: true + noUncheckedIndexedAccess + verbatimModuleSyntax: 必須。弱めない。型のみインポートは import type

境界では unknown → Zod: moka-core レスポンスは Zod スキーマ(単一の lib/api/schemas.ts に集約)で parse してから使う。as キャスト・! 非 null アサーション禁止

判別共用体 + 網羅性: enrichment_status のような状態は tagged union にし、switch の default で satisfies never

satisfies でリテラル推論保持: ルート表・設定オブジェクトは satisfies Record<...> で検査しつつ推論を殺さない

型ガード > アサーション: value is T の predicate を書く。Zod があるので手書きガードは境界の外側だけ

テスト

コンポーネントは vitest-browser-svelte(実ブラウザ実行)。jsdom でのコンポーネントテストは書かない

純ロジック(日付整形・RRF スコア表示等)は node 環境の vitest に分離。コンポーネントに埋めずに lib/ へ抽出してからテスト

E2E(Playwright)の規約は tdd-workflow スキル参照

moka-1 固有

ミニマル UI 原則: 「読む」体験が主。3D 可視化・アニメーションライブラリ・重い UI キットは tenets §3.4 で不採用決定済み。新規依存はまず疑い、追加するなら bundle への影響を報告

LLM 由来テキストの表示規約: 要約・ハイライト理由には「AI 生成」の視覚的区別を付ける。</think> が漏れて表示されたらそれは moka-core 側のバグ(internal/llm の一元除去に違反)— UI 側で握りつぶさず報告する

参照

docs/tenets/moka-tenets.md — 本スキルの「tenets §N」参照はこの文書の節番号