diff --git a/docs/3.api/4.advanced/2.kit.md b/docs/3.api/4.advanced/2.kit.md index a3c5fd10e4..e06e1b4e29 100644 --- a/docs/3.api/4.advanced/2.kit.md +++ b/docs/3.api/4.advanced/2.kit.md @@ -989,7 +989,124 @@ An object with the following properties: [source code](https://github.com/nuxt/nuxt/blob/main/packages/kit/src/context.ts) -- `useNuxt()` +::alert{type=info} +Keep in mind, Nuxt already pass itself as the second argument to the `setup` function, so you can use it instead of `useNuxt()` call. `useNuxt()` and `tryUseNuxt()` calls are useful when you want to access Nuxt in separate functions. You can look at [Nuxt Site Config](https://github.com/harlan-zw/nuxt-site-config) as a reference. +:: + +### `useNuxt()` + +Get the Nuxt instance from the context. It will throw an error if Nuxt is not available. + +#### Type + +```ts +function useNuxt(): Nuxt + +interface Nuxt { + options: NuxtOptions + hooks: Hookable + hook: Nuxt['hooks']['hook'] + callHook: Nuxt['hooks']['callHook'] + addHooks: Nuxt['hooks']['addHooks'] + ready: () => Promise + close: () => Promise + server?: any + vfs: Record + apps: Record +} +``` + +#### Examples + +::code-group + +```ts [setupTranspilation.ts] +// https://github.com/Lexpeartha/nuxt-xstate/blob/main/src/parts/transpile.ts +import { useNuxt } from '@nuxt/kit' + +export const setupTranspilation = () => { + const nuxt = useNuxt() + + nuxt.options.build.transpile = nuxt.options.build.transpile || [] + + if (nuxt.options.builder === '@nuxt/webpack-builder') { + nuxt.options.build.transpile.push( + 'xstate', + ) + } +} +``` + +```ts [module.ts] +import { useNuxt } from '@nuxt/kit' +import { setupTranspilation } from './setupTranspilation' + +export default defineNuxtModule({ + setup() { + setupTranspilation() + } +}) +``` + +:: + +## `tryUseNuxt()` + +Get the Nuxt instance from the context. It will return `null` if Nuxt is not available. + +#### Type + +```ts +function tryUseNuxt(): Nuxt | null + +interface Nuxt { + options: NuxtOptions + hooks: Hookable + hook: Nuxt['hooks']['hook'] + callHook: Nuxt['hooks']['callHook'] + addHooks: Nuxt['hooks']['addHooks'] + ready: () => Promise + close: () => Promise + server?: any + vfs: Record + apps: Record +} +``` + +#### Examples + +::code-group + +```ts [requireSiteConfig.ts] +// https://github.com/harlan-zw/nuxt-site-config/blob/main/test/assertions.test.ts +import { tryUseNuxt } from '@nuxt/kit' + +interface SiteConfig { + title: string +} + +export const requireSiteConfig = (): SiteConfig => { + const nuxt = tryUseNuxt() + if (!nuxt) { + return { title: null } + } + return nuxt.options.siteConfig +} +``` + +```ts [module.ts] +import { useNuxt } from '@nuxt/kit' +import { requireSiteConfig } from './requireSiteConfig' + +export default defineNuxtModule({ + setup(_, nuxt) { + const config = requireSiteConfig() + nuxt.options.app.head.title = config.title + } +}) +``` + +:: ## Pages