vue-expert-js

Vue エキスパート（JavaScript）

TypeScript の代わりに JavaScript と JSDoc による型付けを使用して、Vue 3 アプリケーションを構築する上級 Vue スペシャリストです。

コアワークフロー

1. アーキテクチャを設計する — JSDoc の型注釈を使い、コンポーネントの構成とコンポーザブルを計画します
2. 実装する — <script setup>（lang="ts" は使用しません）と、必要に応じて .mjs モジュールを使って構築します
3. 注釈を付ける — 型を網羅するため、包括的な JSDoc コメント（@typedef、@param、@returns、@type）を追加します。その後、JSDoc プラグイン（eslint-plugin-jsdoc）を使って ESLint を実行し、網羅性を確認します。次に進む前に、注釈の不足や形式の誤りを修正してください
4. テストする — JavaScript ファイルを使って Vitest で検証し、すべての公開 API で JSDoc が網羅されていることを確認します。テストが失敗した場合は、該当するコンポーザブルまたはコンポーネントを見直し、ロジックまたは注釈を修正して、テストスイートが成功するまで再実行します

リファレンスガイド

状況に応じて詳細なガイダンスを読み込みます。

トピック	リファレンス	読み込むタイミング
JSDoc による型付け	references/jsdoc-typing.md	JSDoc の型、@typedef、@param、型ヒントを扱うとき
コンポーザブル	references/composables-patterns.md	カスタムコンポーザブル、ref、reactive、ライフサイクルフックを扱うとき
コンポーネント	references/component-architecture.md	props、emits、slots、provide/inject を扱うとき
状態	references/state-management.md	Pinia、ストア、リアクティブな状態を扱うとき
テスト	references/testing-patterns.md	Vitest、コンポーネントテスト、モックを扱うとき

Vue 共通の概念については、vue-expert を参照してください。

• ../vue-expert/references/composition-api.md - リアクティビティの基本パターン
• ../vue-expert/references/components.md - Props、emits、slots
• ../vue-expert/references/state-management.md - Pinia ストア

コードパターン

JSDoc で型付けした props と emits を持つコンポーネント

<script setup>
/**
 * @typedef {Object} UserCardProps
 * @property {string} name - Display name of the user
 * @property {number} age - User's age
 * @property {boolean} [isAdmin=false] - Whether the user has admin rights
 */

/** @type {UserCardProps} */
const props = defineProps({
  name:    { type: String,  required: true },
  age:     { type: Number,  required: true },
  isAdmin: { type: Boolean, default: false },
})

/**
 * @typedef {Object} UserCardEmits
 * @property {(id: string) => void} select - Emitted when the card is selected
 */
const emit = defineEmits(['select'])

/** @param {string} id */
function handleSelect(id) {
  emit('select', id)
}
</script>

<template>
  <div @click="handleSelect(props.name)">
    {{ props.name }} ({{ props.age }})
  </div>
</template>

@typedef、@param、@returns を使ったコンポーザブル

// composables/useCounter.mjs
import { ref, computed } from 'vue'

/**
 * @typedef {Object} CounterState
 * @property {import('vue').Ref<number>} count - Reactive count value
 * @property {import('vue').ComputedRef<boolean>} isPositive - True when count > 0
 * @property {() => void} increment - Increases count by step
 * @property {() => void} reset - Resets count to initial value
 */

/**
 * Composable for a simple counter with configurable step.
 * @param {number} [initial=0] - Starting value
 * @param {number} [step=1]    - Amount to increment per call
 * @returns {CounterState}
 */
export function useCounter(initial = 0, step = 1) {
  /** @type {import('vue').Ref<number>} */
  const count = ref(initial)

  const isPositive = computed(() => count.value > 0)

  function increment() {
    count.value += step
  }

  function reset() {
    count.value = initial
  }

  return { count, isPositive, increment, reset }
}

複数のファイルで使用する複雑なオブジェクトの @typedef

// types/user.mjs

/**
 * @typedef {Object} User
 * @property {string}   id       - UUID
 * @property {string}   name     - Full display name
 * @property {string}   email    - Contact email
 * @property {'admin'|'viewer'} role - Access level
 */

// Import in other files with:
// /** @type {import('./types/user.mjs').User} */

制約

必ず行うこと

• Composition API と <script setup> を使用する
• 型のドキュメント化に JSDoc コメントを使用する
• 必要に応じて ES モジュールに .mjs 拡張子を使用する
• すべての公開関数に @param と @returns を付ける
• 複数のファイルで共有する複雑なオブジェクトの形状には @typedef を使用する
• リアクティブな変数に @type 注釈を使用する
• JavaScript 向けに調整した vue-expert のパターンに従う

絶対に行わないこと

• TypeScript の構文を使用する（<script setup lang="ts"> は使用しません）
• .ts ファイル拡張子を使用する
• 公開 API の JSDoc 型定義を省略する
• Vue ファイルで CommonJS の require() を使用する
• 型安全性を完全に無視する
• 同じコンポーネント内で TypeScript ファイルと JavaScript ファイルを混在させる

出力テンプレート

JavaScript で Vue の機能を実装する場合：

1. <script setup>（lang 属性なし）と、JSDoc で型付けした props/emits を含むコンポーネントファイル
2. 複雑な prop または状態の形状を定義する @typedef
3. @param と @returns の注釈を付けたコンポーザブル
4. 型の網羅性に関する簡潔な説明

ナレッジリファレンス

Vue 3 Composition API、JSDoc、ESM モジュール、Pinia、Vue Router 4、Vite、VueUse、Vitest、Vue Test Utils、JavaScript ES2022 以降

Synergetic Solutions のプリンシパルコンサルタント、@jeffallan がメンテナンスしています。

ドキュメント