Skip to content

Commit

Permalink
docs: mention <DevOnly> component in api section (#26029)
Browse files Browse the repository at this point in the history
  • Loading branch information
@trdln
trdln committed Mar 18, 2024
1 parent 70b2986 commit ac54031
Show file tree
Hide file tree
Showing 4 changed files with 86 additions and 86 deletions.
87 changes: 7 additions & 80 deletions docs/2.guide/2.directory-structure/1.components.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -244,6 +244,10 @@ This feature only works with Nuxt auto-imports and `#components` imports. Explic
`.client` components are rendered only after being mounted. To access the rendered template using `onMounted()`, add `await nextTick()` in the callback of the `onMounted()` hook.
::

::read-more{to="/docs/api/components/client-only"}
You can also achieve a similar result with the `<ClientOnly>` component.
::

## Server Components

Server components allow server-rendering individual components within your client-side apps. It's possible to use server components within Nuxt, even if you are generating a static site. That makes it possible to build complex sites that mix dynamic components, server-rendered HTML and even static chunks of markup.
Expand Down Expand Up @@ -357,89 +361,12 @@ In this case, the `.server` + `.client` components are two 'halves' of a compone
</template>
```

## `<ClientOnly>` Component

Nuxt provides the [`<ClientOnly>`](/docs/api/components/client-only) component for purposely rendering a component only on client side.

```vue [pages/example.vue]
<template>
<div>
<Sidebar />
<ClientOnly>
<!-- this component will only be rendered on client-side -->
<Comments />
</ClientOnly>
</div>
</template>
```
## Built-In Nuxt Components

Use a slot as fallback until `<ClientOnly>` is mounted on client side.
There are a number of components that Nuxt provides, including `<ClientOnly>` and `<DevOnly>`. You can read more about them in the API documentation.

```vue [pages/example.vue]
<template>
<div>
<Sidebar />
<!-- This renders the "span" element on the server side -->
<ClientOnly fallbackTag="span">
<!-- this component will only be rendered on client side -->
<Comments />
<template #fallback>
<!-- this will be rendered on server side -->
<p>Loading comments...</p>
</template>
</ClientOnly>
</div>
</template>
```

<!-- TODO: Add back after passing treeshakeClientOnly experiment -->
<!--
::note
Make sure not to _nest_ `<ClientOnly>` components or other client-only components. Nuxt performs an optimization to remove the contents of these components from the server-side render, which can break in this case.
::read-more{to="/docs/api"}
::
-->

## `<DevOnly>` Component

Nuxt provides the `<DevOnly>` component to render a component only during development.

The content will not be included in production builds and tree-shaken.

```vue [pages/example.vue]
<template>
<div>
<Sidebar />
<DevOnly>
<!-- this component will only be rendered during development -->
<LazyDebugBar />
<!-- if you ever require to have a replacement during production -->
<!-- be sure to test these using `nuxt preview` -->
<template #fallback>
<div><!-- empty div for flex.justify-between --></div>
</template>
</DevOnly>
</div>
</template>
```

## `<NuxtClientFallback>` Component

Nuxt provides the `<NuxtClientFallback>` component to render its content on the client if any of its children trigger an error in SSR.
You can specify a `fallbackTag` to make it render a specific tag if it fails to render on the server.

```vue [pages/example.vue]
<template>
<div>
<Sidebar />
<!-- this component will be rendered on client-side -->
<NuxtClientFallback fallback-tag="span">
<Comments />
<BrokeInSSR />
</NuxtClientFallback>
</div>
</template>
```

## Library Authors

Expand Down
17 changes: 12 additions & 5 deletions docs/3.api/1.components/1.client-only.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,11 @@ links:
size: xs
---

The `<ClientOnly>` component renders its slot only in client-side. To import a component only on the client, register the component in a client-side only plugin.
The `<ClientOnly>` component is used for purposely rendering a component only on client side.

::note
The content of the default slot will be tree-shaken out of the server build. (This does mean that any CSS used by components within it may not be inlined when rendering the initial HTML.)
::

## Props

Expand All @@ -19,6 +23,7 @@ The `<ClientOnly>` component renders its slot only in client-side. To import a c
<template>
<div>
<Sidebar />
<!-- The <Comment> component will only be rendered on client-side -->
<ClientOnly fallback-tag="span" fallback="Loading comments...">
<Comment />
</ClientOnly>
Expand All @@ -28,14 +33,16 @@ The `<ClientOnly>` component renders its slot only in client-side. To import a c

## Slots

- `#fallback`: specify a content to be displayed server-side.
- `#fallback`: specify a content to be rendered on the server and displayed until `<ClientOnly>` is mounted in the browser.

```vue
```vue [pages/example.vue]
<template>
<div>
<Sidebar />
<ClientOnly>
<!-- ... -->
<!-- This renders the "span" element on the server side -->
<ClientOnly fallbackTag="span">
<!-- this component will only be rendered on client side -->
<Comments />
<template #fallback>
<!-- this will be rendered on server side -->
<p>Loading comments...</p>
Expand Down
51 changes: 51 additions & 0 deletions docs/3.api/1.components/1.dev-only.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
---
title: '<DevOnly>'
description: Render components only during development with the <DevOnly> component.
links:
- label: Source
icon: i-simple-icons-github
to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/components/dev-only.ts
size: xs
---

Nuxt provides the `<DevOnly>` component to render a component only during development.

The content will not be included in production builds.

```vue [pages/example.vue]
<template>
<div>
<Sidebar />
<DevOnly>
<!-- this component will only be rendered during development -->
<LazyDebugBar />
<!-- if you ever require to have a replacement during production -->
<!-- be sure to test these using `nuxt preview` -->
<template #fallback>
<div><!-- empty div for flex.justify-between --></div>
</template>
</DevOnly>
</div>
</template>
```

## Slots

- `#fallback`: if you ever require to have a replacement during production.

```vue
<template>
<div>
<Sidebar />
<DevOnly>
<!-- this component will only be rendered during development -->
<LazyDebugBar />
<!-- be sure to test these using `nuxt preview` -->
<template #fallback>
<div><!-- empty div for flex.justify-between --></div>
</template>
</DevOnly>
</div>
</template>
```
17 changes: 16 additions & 1 deletion docs/3.api/1.components/1.nuxt-client-fallback.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,10 +12,25 @@ links:
size: xs
---

Nuxt provides the `<NuxtClientFallback>` component to render its content on the client if any of its children trigger an error in SSR.

::note{to="/docs/guide/going-further/experimental-features#clientfallback"}
This component is experimental and in order to use it you must enable the `experimental.clientFallback` option in your `nuxt.config`.
::

```vue [pages/example.vue]
<template>
<div>
<Sidebar />
<!-- this component will be rendered on client-side -->
<NuxtClientFallback fallback-tag="span">
<Comments />
<BrokeInSSR />
</NuxtClientFallback>
</div>
</template>
```

## Events

- `@ssr-error`: Event emitted when a child triggers an error in SSR. Note that this will only be triggered on the server.
Expand All @@ -30,7 +45,7 @@ This component is experimental and in order to use it you must enable the `exper

## Props

- `placeholderTag` | `fallbackTag`: Specify a fallback tag to be rendered if the slot fails to render.
- `placeholderTag` | `fallbackTag`: Specify a fallback tag to be rendered if the slot fails to render on the server.
- **type**: `string`
- **default**: `div`
- `placeholder` | `fallback`: Specify fallback content to be rendered if the slot fails to render.
Expand Down

0 comments on commit ac54031

Please sign in to comment.