mirror of
https://github.com/hanzoai/next.js.git
synced 2026-09-24 17:00:51 +00:00
92b4d6737c
- Fetch logging configuration is no longer experimental - Add `unstable_noStore` reference - Add `unstable_cache` reference - Add codemod docs for `next/og` import changes - Update docs around stable Server Actions - Add example of revalidating the entire data cache - Update static export docs for `next export` command removal - Update minimum required Node.js version - Add `viewport` and `generateViewport` reference Co-authored-by: Balázs Orbán <[email protected]> Co-authored-by: Delba de Oliveira <[email protected]>
285 lines
10 KiB
Plaintext
285 lines
10 KiB
Plaintext
---
|
|
title: favicon, icon, and apple-icon
|
|
description: API Reference for the Favicon, Icon and Apple Icon file conventions.
|
|
---
|
|
|
|
The `favicon`, `icon`, or `apple-icon` file conventions allow you to set icons for your application.
|
|
|
|
They are useful for adding app icons that appear in places like web browser tabs, phone home screens, and search engine results.
|
|
|
|
There are two ways to set app icons:
|
|
|
|
- [Using image files (.ico, .jpg, .png)](#image-files-ico-jpg-png)
|
|
- [Using code to generate an icon (.js, .ts, .tsx)](#generate-icons-using-code-js-ts-tsx)
|
|
|
|
## Image files (.ico, .jpg, .png)
|
|
|
|
Use an image file to set an app icon by placing a `favicon`, `icon`, or `apple-icon` image file within your `/app` directory.
|
|
The `favicon` image can only be located in the top level of `app/`.
|
|
|
|
Next.js will evaluate the file and automatically add the appropriate tags to your app's `<head>` element.
|
|
|
|
| File convention | Supported file types | Valid locations |
|
|
| --------------------------- | --------------------------------------- | --------------- |
|
|
| [`favicon`](#favicon) | `.ico` | `app/` |
|
|
| [`icon`](#icon) | `.ico`, `.jpg`, `.jpeg`, `.png`, `.svg` | `app/**/*` |
|
|
| [`apple-icon`](#apple-icon) | `.jpg`, `.jpeg`, `.png` | `app/**/*` |
|
|
|
|
### `favicon`
|
|
|
|
Add a `favicon.ico` image file to the root `/app` route segment.
|
|
|
|
```html filename="<head> output"
|
|
<link rel="icon" href="/favicon.ico" sizes="any" />
|
|
```
|
|
|
|
### `icon`
|
|
|
|
Add an `icon.(ico|jpg|jpeg|png|svg)` image file.
|
|
|
|
```html filename="<head> output"
|
|
<link
|
|
rel="icon"
|
|
href="/icon?<generated>"
|
|
type="image/<generated>"
|
|
sizes="<generated>"
|
|
/>
|
|
```
|
|
|
|
### `apple-icon`
|
|
|
|
Add an `apple-icon.(jpg|jpeg|png)` image file.
|
|
|
|
```html filename="<head> output"
|
|
<link
|
|
rel="apple-touch-icon"
|
|
href="/apple-icon?<generated>"
|
|
type="image/<generated>"
|
|
sizes="<generated>"
|
|
/>
|
|
```
|
|
|
|
> **Good to know**
|
|
>
|
|
> - You can set multiple icons by adding a number suffix to the file name. For example, `icon1.png`, `icon2.png`, etc. Numbered files will sort lexically.
|
|
> - Favicons can only be set in the root `/app` segment. If you need more granularity, you can use [`icon`](#icon).
|
|
> - The appropriate `<link>` tags and attributes such as `rel`, `href`, `type`, and `sizes` are determined by the icon type and metadata of the evaluated file.
|
|
> - For example, a 32 by 32px `.png` file will have `type="image/png"` and `sizes="32x32"` attributes.
|
|
> - `sizes="any"` is added to `favicon.ico` output to [avoid a browser bug](https://evilmartians.com/chronicles/how-to-favicon-in-2021-six-files-that-fit-most-needs) where an `.ico` icon is favored over `.svg`.
|
|
|
|
## Generate icons using code (.js, .ts, .tsx)
|
|
|
|
In addition to using [literal image files](#image-files-ico-jpg-png), you can programmatically **generate** icons using code.
|
|
|
|
Generate an app icon by creating an `icon` or `apple-icon` route that default exports a function.
|
|
|
|
| File convention | Supported file types |
|
|
| --------------- | -------------------- |
|
|
| `icon` | `.js`, `.ts`, `.tsx` |
|
|
| `apple-icon` | `.js`, `.ts`, `.tsx` |
|
|
|
|
The easiest way to generate an icon is to use the [`ImageResponse`](/docs/app/api-reference/functions/image-response) API from `next/og`.
|
|
|
|
```tsx filename="app/icon.tsx" switcher
|
|
import { ImageResponse } from 'next/og'
|
|
|
|
// Route segment config
|
|
export const runtime = 'edge'
|
|
|
|
// Image metadata
|
|
export const size = {
|
|
width: 32,
|
|
height: 32,
|
|
}
|
|
export const contentType = 'image/png'
|
|
|
|
// Image generation
|
|
export default function Icon() {
|
|
return new ImageResponse(
|
|
(
|
|
// ImageResponse JSX element
|
|
<div
|
|
style={{
|
|
fontSize: 24,
|
|
background: 'black',
|
|
width: '100%',
|
|
height: '100%',
|
|
display: 'flex',
|
|
alignItems: 'center',
|
|
justifyContent: 'center',
|
|
color: 'white',
|
|
}}
|
|
>
|
|
A
|
|
</div>
|
|
),
|
|
// ImageResponse options
|
|
{
|
|
// For convenience, we can re-use the exported icons size metadata
|
|
// config to also set the ImageResponse's width and height.
|
|
...size,
|
|
}
|
|
)
|
|
}
|
|
```
|
|
|
|
```jsx filename="app/icon.js" switcher
|
|
import { ImageResponse } from 'next/og'
|
|
|
|
// Route segment config
|
|
export const runtime = 'edge'
|
|
|
|
// Image metadata
|
|
export const size = {
|
|
width: 32,
|
|
height: 32,
|
|
}
|
|
export const contentType = 'image/png'
|
|
|
|
// Image generation
|
|
export default function Icon() {
|
|
return new ImageResponse(
|
|
(
|
|
// ImageResponse JSX element
|
|
<div
|
|
style={{
|
|
fontSize: 24,
|
|
background: 'black',
|
|
width: '100%',
|
|
height: '100%',
|
|
display: 'flex',
|
|
alignItems: 'center',
|
|
justifyContent: 'center',
|
|
color: 'white',
|
|
}}
|
|
>
|
|
A
|
|
</div>
|
|
),
|
|
// ImageResponse options
|
|
{
|
|
// For convenience, we can re-use the exported icons size metadata
|
|
// config to also set the ImageResponse's width and height.
|
|
...size,
|
|
}
|
|
)
|
|
}
|
|
```
|
|
|
|
```html filename="<head> output"
|
|
<link rel="icon" href="/icon?<generated>" type="image/png" sizes="32x32" />
|
|
```
|
|
|
|
> **Good to know**
|
|
>
|
|
> - By default, generated icons are [**statically optimized**](/docs/app/building-your-application/rendering/server-components#static-rendering-default) (generated at build time and cached) unless they use [dynamic functions](/docs/app/building-your-application/rendering/server-components#server-rendering-strategies#dynamic-functions) or uncached data.
|
|
> - You can generate multiple icons in the same file using [`generateImageMetadata`](/docs/app/api-reference/functions/generate-image-metadata).
|
|
> - You cannot generate a `favicon` icon. Use [`icon`](#icon) or a [favicon.ico](#favicon) file instead.
|
|
|
|
### Props
|
|
|
|
The default export function receives the following props:
|
|
|
|
#### `params` (optional)
|
|
|
|
An object containing the [dynamic route parameters](/docs/app/building-your-application/routing/dynamic-routes) object from the root segment down to the segment `icon` or `apple-icon` is colocated in.
|
|
|
|
```tsx filename="app/shop/[slug]/icon.tsx" switcher
|
|
export default function Icon({ params }: { params: { slug: string } }) {
|
|
// ...
|
|
}
|
|
```
|
|
|
|
```jsx filename="app/shop/[slug]/icon.js" switcher
|
|
export default function Icon({ params }) {
|
|
// ...
|
|
}
|
|
```
|
|
|
|
| Route | URL | `params` |
|
|
| ------------------------------- | ----------- | ------------------------- |
|
|
| `app/shop/icon.js` | `/shop` | `undefined` |
|
|
| `app/shop/[slug]/icon.js` | `/shop/1` | `{ slug: '1' }` |
|
|
| `app/shop/[tag]/[item]/icon.js` | `/shop/1/2` | `{ tag: '1', item: '2' }` |
|
|
| `app/shop/[...slug]/icon.js` | `/shop/1/2` | `{ slug: ['1', '2'] }` |
|
|
|
|
### Returns
|
|
|
|
The default export function should return a `Blob` | `ArrayBuffer` | `TypedArray` | `DataView` | `ReadableStream` | `Response`.
|
|
|
|
> **Good to know**: `ImageResponse` satisfies this return type.
|
|
|
|
### Config exports
|
|
|
|
You can optionally configure the icon's metadata by exporting `size` and `contentType` variables from the `icon` or `apple-icon` route.
|
|
|
|
| Option | Type |
|
|
| ----------------------------- | --------------------------------------------------------------------------------------------------------------- |
|
|
| [`size`](#size) | `{ width: number; height: number }` |
|
|
| [`contentType`](#contenttype) | `string` - [image MIME type](https://developer.mozilla.org/docs/Web/HTTP/Basics_of_HTTP/MIME_types#image_types) |
|
|
|
|
#### `size`
|
|
|
|
```tsx filename="icon.tsx | apple-icon.tsx" switcher
|
|
export const size = { width: 32, height: 32 }
|
|
|
|
export default function Icon() {}
|
|
```
|
|
|
|
```jsx filename="icon.js | apple-icon.js" switcher
|
|
export const size = { width: 32, height: 32 }
|
|
|
|
export default function Icon() {}
|
|
```
|
|
|
|
```html filename="<head> output"
|
|
<link rel="icon" sizes="32x32" />
|
|
```
|
|
|
|
#### `contentType`
|
|
|
|
```tsx filename="icon.tsx | apple-icon.tsx" switcher
|
|
export const contentType = 'image/png'
|
|
|
|
export default function Icon() {}
|
|
```
|
|
|
|
```jsx filename="icon.js | apple-icon.js" switcher
|
|
export const contentType = 'image/png'
|
|
|
|
export default function Icon() {}
|
|
```
|
|
|
|
```html filename="<head> output"
|
|
<link rel="icon" type="image/png" />
|
|
```
|
|
|
|
#### Route Segment Config
|
|
|
|
`icon` and `apple-icon` are specialized [Route Handlers](/docs/app/building-your-application/routing/route-handlers) that can use the same [route segment configuration](/docs/app/api-reference/file-conventions/route-segment-config) options as Pages and Layouts.
|
|
|
|
| Option | Type | Default |
|
|
| -------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | ---------- |
|
|
| [`dynamic`](/docs/app/api-reference/file-conventions/route-segment-config#dynamic) | `'auto' \| 'force-dynamic' \| 'error' \| 'force-static'` | `'auto'` |
|
|
| [`revalidate`](/docs/app/api-reference/file-conventions/route-segment-config#revalidate) | `false \| 'force-cache' \| 0 \| number` | `false` |
|
|
| [`runtime`](/docs/app/api-reference/file-conventions/route-segment-config#runtime) | `'nodejs' \| 'edge'` | `'nodejs'` |
|
|
| [`preferredRegion`](/docs/app/api-reference/file-conventions/route-segment-config#preferredregion) | `'auto' \| 'global' \| 'home' \| string \| string[]` | `'auto'` |
|
|
|
|
```tsx filename="app/icon.tsx" switcher
|
|
export const runtime = 'edge'
|
|
|
|
export default function Icon() {}
|
|
```
|
|
|
|
```jsx filename="app/icon.js" switcher
|
|
export const runtime = 'edge'
|
|
|
|
export default function Icon() {}
|
|
```
|
|
|
|
## Version History
|
|
|
|
| Version | Changes |
|
|
| --------- | -------------------------------------------- |
|
|
| `v13.3.0` | `favicon` `icon` and `apple-icon` introduced |
|