brand logo

ドキュメント

Version 33.17Version 44.10

コンテキスト

Nuxt Kit は、コンテキストを扱うためのユーティリティを提供します。

Nuxt モジュールは、Nuxt の機能を強化することができます。これにより、コードを整理し、モジュール化するための構造化された方法が提供されます。モジュールをより小さなコンポーネントに分割したい場合、Nuxt は useNuxt と tryUseNuxt 関数を提供します。これらの関数を使用すると、引数として渡すことなく、コンテキストから Nuxt インスタンスに便利にアクセスできます。

Nuxt モジュールで setup 関数を使用する場合、Nuxt はすでに第二引数として提供されています。つまり、useNuxt() を呼び出すことなく直接アクセスできます。

useNuxt

コンテキストから Nuxt インスタンスを取得します。Nuxt が利用できない場合はエラーをスローします。

使用法

import { useNuxt } from '@nuxt/kit'

const setupSomeFeature = () => {
  const nuxt = useNuxt()

  // ここで nuxt インスタンスを使用できます
  console.log(nuxt.options)
}

型

// @errors: 2391
import type { Nuxt } from '@nuxt/schema'
// ---cut---
function useNuxt(): Nuxt

戻り値

useNuxt 関数は Nuxt インスタンスを返します。このインスタンスには、Nuxt で利用可能なすべてのオプションとメソッドが含まれています。

プロパティ型説明
optionsNuxtOptions解決された Nuxt の設定。
hooksHookable<NuxtHooks>Nuxt のフックシステム。ライフサイクルイベントの登録とリスニングを可能にします。
hook(name: string, (...args: any[]) => Promise<void> | void) => () => void特定のライフサイクルフックに対して単一のコールバックを登録するためのショートカット。
callHook(name: string, ...args: any[]) => Promise<any>ライフサイクルフックを手動でトリガーし、登録されたすべてのコールバックを実行するためのショートカット。
addHooks(configHooks: NestedHooks) => () => void複数のフックを一度に登録するためのショートカット。

例

import { useNuxt } from '@nuxt/kit'

export const setupTranspilation = () => {
  const nuxt = useNuxt()

  if (nuxt.options.builder === '@nuxt/webpack-builder') {
    nuxt.options.build.transpile ||= []
    nuxt.options.build.transpile.push('xstate')
  }
}

tryUseNuxt

コンテキストから Nuxt インスタンスを取得します。Nuxt が利用できない場合は null を返します。

使用法

import { tryUseNuxt } from '@nuxt/kit'

function setupSomething () {
  const nuxt = tryUseNuxt()

  if (nuxt) {
    // ここで nuxt インスタンスを使用できます
    console.log(nuxt.options)
  } else {
    console.log('Nuxt は利用できません')
  }
}

型

// @errors: 2391
import type { Nuxt } from '@nuxt/schema'
// ---cut---
function tryUseNuxt(): Nuxt | null

戻り値

tryUseNuxt 関数は、利用可能な場合は Nuxt インスタンスを返し、Nuxt が利用できない場合は null を返します。

Nuxt インスタンスは useNuxt セクションで説明されている通りです。

例

declare module '@nuxt/schema' {
  interface NuxtOptions {
    siteConfig: SiteConfig
  }
}
// ---cut---
import { tryUseNuxt } from '@nuxt/kit'

interface SiteConfig {
  title?: string
}

export const requireSiteConfig = (): SiteConfig => {
  const nuxt = tryUseNuxt()
  if (!nuxt) {
    return {}
  }
  return nuxt.options.siteConfig
}

tips

このセクションは公式ドキュメントの翻訳ではなく、本サイト独自の補足記事です。

NuxtのuseNuxtとtryUseNuxtとは？〜イントロダクション〜

Nuxtのモジュール開発において、Nuxtの内部状態や設定にアクセスすることは非常に重要です。useNuxt と tryUseNuxt は、こうしたニーズに応えるために提供されている関数で、NuxtのコンテキストからNuxtインスタンスを簡単に取得できます。これにより、モジュールの機能拡張や設定の動的変更が容易になり、コードの整理や再利用性の向上にもつながります。

特に、複雑なプロジェクトや複数のモジュールを組み合わせる場合、Nuxtインスタンスへのアクセスを統一的に行うことで、開発効率が大幅にアップします。しかし、使い方を誤るとエラーやパフォーマンス問題の原因にもなるため、正しい理解が不可欠です。

まず結論：useNuxtとtryUseNuxtのポイント

  • useNuxt は必ずNuxtインスタンスを返し、利用できない場合はエラーをスローする
  • tryUseNuxt はNuxtインスタンスを返すか、利用できなければ null を返すため安全に使える
  • モジュールの setup 関数内では第二引数としてNuxtインスタンスが渡されるため、基本的にこれを使うのが推奨される
  • Nuxtインスタンスには設定オプションやフック登録機能など、モジュール開発に必要な情報が集約されている
  • 使いどころを誤ると、SSR/CSRの違いやHydration問題で不具合が起きる可能性がある

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

使うべきケース

  • モジュールの内部でNuxtの設定やフックにアクセスしたいとき
    例：ビルド設定の動的変更、カスタムフックの登録など
  • モジュールの外部関数やユーティリティからNuxtインスタンスを取得したいとき
    直接 setup 関数外でNuxtインスタンスを使いたい場合に便利
  • Nuxtの状態に依存した処理を行うが、必ずNuxtが存在する環境であることが保証されている場合
    この場合は useNuxt が適している

使わない方がよいケース

  • Nuxtインスタンスが存在しない可能性がある環境（例：純粋なNode.jsスクリプトやテスト環境）で使う場合
    この場合は tryUseNuxt を使い、nullチェックを行うべき
  • モジュールの setup 関数内で既にNuxtインスタンスが引数として渡されている場合
    重複して useNuxt を呼び出す必要はない
  • クライアントサイドのコードやVueコンポーネント内で直接使うのは推奨されない
    これらはNuxtのビルド時やサーバーサイドの処理に関わるため

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

1. ビルド時に特定のパッケージをトランスパイル対象に追加する

import { useNuxt } from '@nuxt/kit'

export const setupTranspilePackage = () => {
  const nuxt = useNuxt()

  if (!nuxt.options.build.transpile) {
    nuxt.options.build.transpile = []
  }
  nuxt.options.build.transpile.push('some-es6-package')
}

このように、ビルド設定を動的に変更することで、ES6パッケージのトランスパイル漏れを防げます。

2. モジュール外のユーティリティ関数でNuxtのカスタム設定を取得する

import { tryUseNuxt } from '@nuxt/kit'

export const getCustomConfig = () => {
  const nuxt = tryUseNuxt()
  if (!nuxt) {
    return null
  }
  return nuxt.options.customConfig ?? {}
}

Nuxtが存在しない環境でも安全に呼び出せるため、テストや外部ツールとの連携に便利です。

3. フックを登録してビルドプロセスに割り込む

import { useNuxt } from '@nuxt/kit'

export const registerBuildHook = () => {
  const nuxt = useNuxt()

  nuxt.hook('build:before', () => {
    console.log('ビルド開始前の処理を実行')
  })
}

Nuxtのライフサイクルにフックを登録し、柔軟に処理を挟み込めます。

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

1. SSRとCSRの違いによる影響

useNuxt や tryUseNuxt は主にビルド時やサーバーサイドでの処理を想定しています。クライアントサイドでこれらを使うと、Nuxtインスタンスが存在しない場合があり、エラーや意図しない挙動を招くことがあります。

2. Hydrationエラーの原因になることも

Nuxtインスタンスの状態をクライアントとサーバーで不整合に扱うと、Hydrationエラーが発生します。特に動的に設定を変更する場合は、変更がビルド時に反映されているか注意が必要です。

3. パフォーマンスへの影響

頻繁に useNuxt を呼び出して重い処理を行うと、ビルド時間や実行時間が増加します。必要なときだけ呼び出し、処理はできるだけ軽量に保つことが望ましいです。

4. setup 関数の第二引数を活用する

モジュールの setup 関数ではNuxtインスタンスが第二引数として渡されるため、無理に useNuxt を使わずにこちらを利用するほうが安全で効率的です。

まとめ

useNuxt と tryUseNuxt はNuxtモジュール開発における強力なツールであり、Nuxtインスタンスへのアクセスを簡単にします。使い分けのポイントは、Nuxtインスタンスの存在が保証されているかどうかです。実務ではビルド設定の動的変更やフック登録、カスタム設定の取得などに活用されますが、SSR/CSRの違いやHydration問題に注意し、適切な場面で使うことが重要です。モジュールの setup 関数内では第二引数のNuxtインスタンスを優先的に使うことをおすすめします。

Nuxtモジュール開発の効率化と安定性向上のために、これらの関数の正しい理解と使い分けを心がけましょう。

© 2016–PRESENT Nuxt Labs https://nuxt.com

※このページは Nuxt.js 公式ドキュメントの翻訳ページです。

公式ドキュメントの該当ページはこちら：
https://nuxt.com/docs/3.x/api/kit/context