Unverified Commit 84cac15d authored by Delba de Oliveira's avatar Delba de Oliveira Committed by GitHub

docs: Getting Started guide on images and fonts (#73470)

parent 14a5fd84
...@@ -31,7 +31,7 @@ The Next.js [`<Image>`](/docs/app/building-your-application/optimizing/images) c ...@@ -31,7 +31,7 @@ The Next.js [`<Image>`](/docs/app/building-your-application/optimizing/images) c
- **Faster page loads:** Only loading images when they enter the viewport using native browser lazy loading, with optional blur-up placeholders. - **Faster page loads:** Only loading images when they enter the viewport using native browser lazy loading, with optional blur-up placeholders.
- **Asset flexibility:** Resizing images on-demand, even images stored on remote servers. - **Asset flexibility:** Resizing images on-demand, even images stored on remote servers.
To start using `<Image>`, first import it from `next/image` and render it within your component. To start using `<Image>`, import it from `next/image` and render it within your component.
```tsx filename="app/page.tsx" switcher ```tsx filename="app/page.tsx" switcher
import Image from 'next/image' import Image from 'next/image'
...@@ -127,9 +127,7 @@ export default function Page() { ...@@ -127,9 +127,7 @@ export default function Page() {
} }
``` ```
Since Next.js does not have access to remote files during the build process, you'll need to provide the [`width`](/docs/app/api-reference/components/image#width), [`height`](/docs/app/api-reference/components/image#height) and optional [`blurDataURL`](/docs/app/api-reference/components/image#blurdataurl) props manually. Since Next.js does not have access to remote files during the build process, you'll need to provide the [`width`](/docs/app/api-reference/components/image#width), [`height`](/docs/app/api-reference/components/image#height) and optional [`blurDataURL`](/docs/app/api-reference/components/image#blurdataurl) props manually. The `width` and `height` attributes are used to infer the correct aspect ratio of image and avoid layout shift from the image loading in. But `width` and `height` do _not_ determine the rendered size of the image file.
> **Good to know:** The `width` and `height` attributes are used to infer the correct aspect ratio of image and avoid layout shift from the image loading in. The `width` and `height` do _not_ determine the rendered size of the image file.
Then, to safely allow images from remote servers, you need to define a list of supported URL patterns in `next.config.js`. Be as specific as possible to prevent malicious usage. For example, the following configuration will only allow images from a specific AWS S3 bucket: Then, to safely allow images from remote servers, you need to define a list of supported URL patterns in `next.config.js`. Be as specific as possible to prevent malicious usage. For example, the following configuration will only allow images from a specific AWS S3 bucket:
...@@ -144,6 +142,7 @@ const config: NextConfig = { ...@@ -144,6 +142,7 @@ const config: NextConfig = {
hostname: 's3.amazonaws.com', hostname: 's3.amazonaws.com',
port: '', port: '',
pathname: '/my-bucket/**', pathname: '/my-bucket/**',
search: '',
}, },
], ],
}, },
...@@ -161,6 +160,7 @@ module.exports = { ...@@ -161,6 +160,7 @@ module.exports = {
hostname: 's3.amazonaws.com', hostname: 's3.amazonaws.com',
port: '', port: '',
pathname: '/my-bucket/**', pathname: '/my-bucket/**',
search: '',
}, },
], ],
}, },
...@@ -175,14 +175,13 @@ The [`next/font`](/docs/app/api-reference/components/font) module automatically ...@@ -175,14 +175,13 @@ The [`next/font`](/docs/app/api-reference/components/font) module automatically
It includes **built-in automatic self-hosting** for _any_ font file. This means you can optimally load web fonts with no layout shift. It includes **built-in automatic self-hosting** for _any_ font file. This means you can optimally load web fonts with no layout shift.
To start using `next/font`, import it from `next/font/local` or `next/font/google` (depending on whether you're using a [local](#local-fonts) or [Google](#google-fonts) font), call it as a function with the appropriate options, and set the `className` of the element you want to apply the font to. To start using `next/font`, import it from `next/font/local` or `next/font/google` (depending on whether you're using a [Google](#google-fonts) or [local](#local-fonts) font), call it as a function with the appropriate options, and set the `className` of the element you want to apply the font to.
```tsx filename="app/layout.tsx" switcher ```tsx filename="app/layout.tsx" switcher
import { Geist } from 'next/font/google' import { Geist } from 'next/font/google'
const geist = Geist({ const geist = Geist({
subsets: ['latin'], subsets: ['latin'],
display: 'swap',
}) })
export default function Layout({ children }: { children: React.ReactNode }) { export default function Layout({ children }: { children: React.ReactNode }) {
...@@ -199,7 +198,6 @@ import { Geist } from 'next/font/google' ...@@ -199,7 +198,6 @@ import { Geist } from 'next/font/google'
const geist = Geist({ const geist = Geist({
subsets: ['latin'], subsets: ['latin'],
display: 'swap',
}) })
export default function Layout({ children }) { export default function Layout({ children }) {
...@@ -211,16 +209,17 @@ export default function Layout({ children }) { ...@@ -211,16 +209,17 @@ export default function Layout({ children }) {
} }
``` ```
### Local fonts ### Google fonts
To use a local font, import `next/font/local` and specify the `src` of your local font file in the [`public` folder](#handling-static-assets). You can automatically self-host any Google Font. Fonts are included in the deployment and served from the same domain as your deployment. **No requests are sent to Google by the browser.**
To start using a Google Font, import it from `next/font/google` as a function.
```tsx filename="app/layout.tsx" switcher ```tsx filename="app/layout.tsx" switcher
import localFont from 'next/font/local' import { Inter } from 'next/font/google'
const myFont = localFont({ const inter = Inter({
src: './my-font.woff2', subsets: ['latin'],
display: 'swap',
}) })
export default function RootLayout({ export default function RootLayout({
...@@ -229,7 +228,7 @@ export default function RootLayout({ ...@@ -229,7 +228,7 @@ export default function RootLayout({
children: React.ReactNode children: React.ReactNode
}) { }) {
return ( return (
<html lang="en" className={myFont.className}> <html lang="en" className={inter.className}>
<body>{children}</body> <body>{children}</body>
</html> </html>
) )
...@@ -237,63 +236,29 @@ export default function RootLayout({ ...@@ -237,63 +236,29 @@ export default function RootLayout({
``` ```
```jsx filename="app/layout.js" switcher ```jsx filename="app/layout.js" switcher
import localFont from 'next/font/local' import { Inter } from 'next/font/google'
const myFont = localFont({ const inter = Inter({
src: './my-font.woff2', subsets: ['latin'],
display: 'swap',
}) })
export default function RootLayout({ children }) { export default function RootLayout({ children }) {
return ( return (
<html lang="en" className={myFont.className}> <html lang="en" className={inter.className}>
<body>{children}</body> <body>{children}</body>
</html> </html>
) )
} }
``` ```
If you want to use multiple files for a single font family, `src` can be an array: We recommend using [variable fonts](https://fonts.google.com/variablefonts) for the best performance and flexibility. But if you can't use a variable font, you will **need to specify a weight**:
```js
const roboto = localFont({
src: [
{
path: './Roboto-Regular.woff2',
weight: '400',
style: 'normal',
},
{
path: './Roboto-Italic.woff2',
weight: '400',
style: 'italic',
},
{
path: './Roboto-Bold.woff2',
weight: '700',
style: 'normal',
},
{
path: './Roboto-BoldItalic.woff2',
weight: '700',
style: 'italic',
},
],
})
```
### Google fonts
You can automatically self-host any Google Font. Fonts are included in the deployment and served from the same domain as your deployment. **No requests are sent to Google by the browser.**
To start using a Google Font, import it from `next/font/google` as a function.
```tsx filename="app/layout.tsx" switcher ```tsx filename="app/layout.tsx" switcher
import { Inter } from 'next/font/google' import { Roboto } from 'next/font/google'
const inter = Inter({ const roboto = Roboto({
weight: '400',
subsets: ['latin'], subsets: ['latin'],
display: 'swap',
}) })
export default function RootLayout({ export default function RootLayout({
...@@ -302,7 +267,7 @@ export default function RootLayout({ ...@@ -302,7 +267,7 @@ export default function RootLayout({
children: React.ReactNode children: React.ReactNode
}) { }) {
return ( return (
<html lang="en" className={inter.className}> <html lang="en" className={roboto.className}>
<body>{children}</body> <body>{children}</body>
</html> </html>
) )
...@@ -310,31 +275,31 @@ export default function RootLayout({ ...@@ -310,31 +275,31 @@ export default function RootLayout({
``` ```
```jsx filename="app/layout.js" switcher ```jsx filename="app/layout.js" switcher
import { Inter } from 'next/font/google' import { Roboto } from 'next/font/google'
const inter = Inter({ const roboto = Roboto({
weight: '400',
subsets: ['latin'], subsets: ['latin'],
display: 'swap',
}) })
export default function RootLayout({ children }) { export default function RootLayout({ children }) {
return ( return (
<html lang="en" className={inter.className}> <html lang="en" className={roboto.className}>
<body>{children}</body> <body>{children}</body>
</html> </html>
) )
} }
``` ```
We recommend using [variable fonts](https://fonts.google.com/variablefonts) for the best performance and flexibility. But if you can't use a variable font, you will **need to specify a weight**: ### Local fonts
To use a local font, import `next/font/local` and specify the `src` of your local font file in the [`public` folder](#handling-static-assets).
```tsx filename="app/layout.tsx" switcher ```tsx filename="app/layout.tsx" switcher
import { Roboto } from 'next/font/google' import localFont from 'next/font/local'
const roboto = Roboto({ const myFont = localFont({
weight: '400', src: './my-font.woff2',
subsets: ['latin'],
display: 'swap',
}) })
export default function RootLayout({ export default function RootLayout({
...@@ -343,7 +308,7 @@ export default function RootLayout({ ...@@ -343,7 +308,7 @@ export default function RootLayout({
children: React.ReactNode children: React.ReactNode
}) { }) {
return ( return (
<html lang="en" className={roboto.className}> <html lang="en" className={myFont.className}>
<body>{children}</body> <body>{children}</body>
</html> </html>
) )
...@@ -351,21 +316,48 @@ export default function RootLayout({ ...@@ -351,21 +316,48 @@ export default function RootLayout({
``` ```
```jsx filename="app/layout.js" switcher ```jsx filename="app/layout.js" switcher
import { Roboto } from 'next/font/google' import localFont from 'next/font/local'
const roboto = Roboto({ const myFont = localFont({
weight: '400', src: './my-font.woff2',
subsets: ['latin'],
display: 'swap',
}) })
export default function RootLayout({ children }) { export default function RootLayout({ children }) {
return ( return (
<html lang="en" className={roboto.className}> <html lang="en" className={myFont.className}>
<body>{children}</body> <body>{children}</body>
</html> </html>
) )
} }
``` ```
If you want to use multiple files for a single font family, `src` can be an array:
```js
const roboto = localFont({
src: [
{
path: './Roboto-Regular.woff2',
weight: '400',
style: 'normal',
},
{
path: './Roboto-Italic.woff2',
weight: '400',
style: 'italic',
},
{
path: './Roboto-Bold.woff2',
weight: '700',
style: 'normal',
},
{
path: './Roboto-BoldItalic.woff2',
weight: '700',
style: 'italic',
},
],
})
```
Learn more about Font Optimization in the [API Reference](/docs/app/api-reference/components/font). Learn more about Font Optimization in the [API Reference](/docs/app/api-reference/components/font).
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment