Nuxtのutilsディレクトリとは？〜開発効率を高めるユーティリティ管理〜

Nuxt 3では、utils/ディレクトリを使うことで、アプリケーション全体で使うユーティリティ関数を簡単に管理・自動インポートできます。
この仕組みを活用すると、コードの重複を減らし、保守性を向上させることが可能です。特に複数のコンポーネントやページで共通処理を使いたい場合に便利で、開発効率の大幅な改善につながります。

まず結論：utilsディレクトリのポイント

• utils/内の関数はVueコンポーネントやページで自動的にインポートされる
• 名前付きエクスポートとデフォルトエクスポートの両方に対応
• ファイル名のキャメルケースが自動的に関数名になる（例：randomEntry.ts → randomEntry()）
• utils/はVue部分専用。サーバー側ユーティリティはserver/utils/に配置する
• composables/と同様の自動インポートスキャンが行われるため、使い勝手が統一されている

いつ使うべきか？使わない方がよいケースは？

使うべきケース

• 複数のVueコンポーネントやページで共通の処理を使いたいとき
• 汎用的なフォーマット関数や計算ロジックをまとめて管理したいとき
• 依存関係が少なく、純粋なユーティリティ関数を分離したいとき

避けたほうがよいケース

• サーバー専用の処理やNode.jsのAPIを使うユーティリティ（server/utils/に置くべき）
• 状態管理やVueのリアクティブな機能に依存する処理（composables/のほうが適切）
• 大規模なライブラリや外部パッケージのラッパーとして使う場合は、明示的なインポートのほうが分かりやすいこともある

実務でよくあるユースケースとサンプルコード

1. 数値や日付のフォーマット関数

複数の画面で同じフォーマット処理を使いたい場合に便利です。

// utils/formatNumber.ts
export const formatNumber = (num: number): string => {
  return new Intl.NumberFormat('ja-JP', {
    notation: 'compact',
    maximumFractionDigits: 1
  }).format(num)
}

Vueコンポーネント内で自動インポートされているので、明示的なimportは不要です。

<template>
  <p>売上: {{ formatNumber(1234567) }}</p>
</template>

2. 配列からランダムに要素を取得する関数

ゲームやUIのランダム表示などでよく使います。

// utils/randomEntry.ts
export default function randomEntry<T>(arr: T[]): T {
  return arr[Math.floor(Math.random() * arr.length)]
}

<template>
  <p>今日のおすすめ: {{ randomEntry(items) }}</p>
</template>

<script setup lang="ts">
const items = ['りんご', 'みかん', 'バナナ']
</script>

3. 文字列のトリミングや正規化処理

フォーム入力のバリデーション前処理などで共通化できます。

// utils/normalizeString.ts
export function normalizeString(str: string): string {
  return str.trim().toLowerCase()
}

よくある落とし穴・注意点

SSRとCSRの違いに注意

utils/の関数はVueのレンダリング部分で使われるため、サーバーサイドレンダリング（SSR）とクライアントサイドレンダリング（CSR）の両方で動作します。
そのため、ブラウザ固有のAPI（windowやdocumentなど）を使う場合は、実行環境を判別して安全に処理する必要があります。

export function isBrowser(): boolean {
  return typeof window !== 'undefined'
}

Hydrationエラーの原因になりやすい

ユーティリティ関数の結果がSSRとCSRで異なると、Hydrationエラーが発生することがあります。
例えば、日時のフォーマットや乱数生成は実行タイミングによって差異が出やすいので注意してください。

パフォーマンス面の配慮

頻繁に呼び出すユーティリティ関数は、処理が重いとパフォーマンスに影響します。
可能な限り純粋関数にして副作用を避け、必要に応じてキャッシュやメモ化を検討しましょう。

まとめ

Nuxtのutils/ディレクトリは、Vueコンポーネントやページで使う汎用的なユーティリティ関数を効率的に管理・自動インポートできる便利な仕組みです。
適切に使うことでコードの再利用性が高まり、開発効率や保守性が向上します。
ただし、SSR/CSRの違いや実行環境の違いによる挙動の差異には注意が必要です。
サーバー専用の処理はserver/utils/に分けるなど、役割を明確にして使い分けることが重要です。