Next.js. API

Next позволяет легко создавать эндпоинты API.

Создаем в папке pages новую папку api, а в ней - файлы для эндпоинтов.
Из каждого файла нужно по дефолту экспортировать функцию, которая будет обрабатывать запрос.

export default function echo(req, res) {
     res.status(200).json({
        message: req.query.message,
    });
}

Обратиться к нему можно по урлу /api/echo?message=SomeText.

В папке api также можно создавать роуты с динамической частью: pages/api/[id].ts. Динамический параметр можно получить из req.query.id.

#nextjs #серверныйрендеринг

Переходим к нашему любимому чтению документации: https://nextjs.org/docs/getting-started

В курсе есть еще несколько интересных моментов, например, работа с TypeScript, файл конфигурации и библиотека для отображения состояния загрузки при переходе между страницами, но первые два я планирую разобрать по документации, а третий пока выглядит больше как магия, нужно копнуть Next чуть глубже, чтобы понять, что там происходит.

#документация #nextjs #серверныйрендеринг

Next.js. Начало работы

Статьи в документации (англ.):
https://nextjs.org/docs/getting-started
https://nextjs.org/docs/basic-features/pages

Проще всего начать работу с помощью утилиты create-next-app (есть флаг --typescript`) , но можно и вручную все сделать. Для этого нужно к обычному React-приложению (`react, react-dom`) добавить еще пакет `next и пару npm-скриптов для запуска. Все самое приятное уже есть из коробки - сборка, запуск сервера, быстрое обновление.

У нас есть две важные папки - pages и public. Про страницы мы уже в целом знаем.

Нам снова рассказывают про SSG (Static Generation, генерация во время сборки) и SSR (Server Side Rendering), говорят, что эти подходы можно совмещать, но сильно рекомендуют SSG. Говорят, что если не получается чистый SSG, то можно сделать SSG для костяка страницы, а данные запрашивать уже на клиенте.

#документация #nextjs #серверныйрендеринг

Next.js. Data Fetching

Статьи в документации (англ.):
- https://nextjs.org/docs/basic-features/data-fetching/overview
- https://nextjs.org/docs/basic-features/data-fetching/get-server-side-props
- https://nextjs.org/docs/basic-features/data-fetching/get-static-paths
- https://nextjs.org/docs/basic-features/data-fetching/get-static-props

Чтобы заполнить наши шаблоны данными, нам необходимо эти данные получить. Делать это можно в разное время, как мы уже знаем:

- в рантайме при запросе к странице - getServerSideProps
- при сборке - getStaticProps + getStaticPaths
- на клиенте - useEffect

getServerSideProps

При каждом запросе к странице Next.js (на сервере) будет выполнять функцию getServerSideProps и рендерить компонент страницы с полученными данными. На клиенте эта функция никогда не выполняется и вырезается из клиентского бандла.
Если мы переходим на страницу с помощью next/link или next/router, функция тоже выполняется (API-запрос).

Использовать эту функцию нужно в том случае, если данные необходимо получать именно во время запроса (авторизация/гео-локация/актуальные данные).

Документация советует не использовать API-роуты (папка pages/api) внутри getServerSideProps, так как это снижает производительность. Лучше напрямую выполнять запросы из функции.

Функция имеет доступ к объекту запроса (ctx.res). Это позволяет управлять кэшем:

export async function getServerSideProps({ req, res }) {
  res.setHeader(
    'Cache-Control',
    'public, s-maxage=10, stale-while-revalidate=59'
  )

  return {
    props: {},
  }
}

При возникновении ошибки в getServerSideProps рендерится страница 500 ошибки.

getStaticPaths

Функция необходима для динамических роутов, чтобы указать, какие значения могут принимать динамические параметры. Она возвращает объект с двумя полями paths и fallback (false/true/'blocking', разберемся с этим параметром чуть позже).

Здесь можно обратиться к базе данных/файловой системе и получить все возможные значения параметров.

Функция выполняется только при сборке и не входит в клиентскую сборку, так что здесь смело можно писать серверный код (например, обращение к БД). В режиме разработки функция выполняется при каждом запросе.

Необходимо использовать вместе с getStaticProps, так как нужно передать полученные динамические параметры на страницу.

getStaticProps

Идея та же, что и у getServerSideProps, но выполняется не в рантайме, а во время сборки. Является предпочтительным методом запроса данных.

Выполняется только на сервере, не входит в клиентскую сборку.

Документация советует не использовать API-роуты (папка pages/api) внутри getStaticProps, так как это снижает производительность. Лучше напрямую выполнять запросы из функции.

Не имеет доступа к объекту запроса.

При выполнении функции getStaticProps Next.js генерирует HTML-файл и вдобавок к нему JSON-файл, который используется, если на страницу переходят на клиенте с помощью next/link или next/router. То есть запросы заново не выполняются, берутся те данные, которые были получены при сборке.

В режиме разработки функция выполняется при каждом запросе.

#nextjs #серверныйрендеринг #документация

Next.js. Инкрементальная статическая регенерация

Если мы используем подход SSG, то для внесения любых изменений нужно пересобрать приложение (например, если появились новые посты).

Но Next позволяет избежать пересборки - этот подход называется ISR - Incremental Static Regeneration. Для его использования нужно только добавить поле revalidate в результат функции getStaticProps:

export async function getStaticProps() {
    ...
    return {
        props: {},
        revalidate: 10
    }
}

Значение - это количество секунд, по истечении которых нужно обновить пропсы. То есть мы делаем первый запрос, функция выполняется и результат кешируется на 10 секунд. После этого времени для нового запроса функция будет выполнена заново.

#nextjs #серверныйрендеринг #документация

Next.js. useSWR

Для запроса данных на стороне клиента нам настойчиво рекомендуют библиотеку SWR, которая предоставляет много плюшек вроде кеширования, ревалидации, перезапроса данных и т.д.

#nextjs #серверныйрендеринг #документация

Next.js. getStaticPaths - fallback

Параметр fallback определяет поведение Next.js при обращении к странице с несуществующим динамическим параметром.

fallback: false

Если fallback: false, то для неперечисленных параметров будет возвращаться страница 404. Это удобно, если у вас не очень много роутов и они не часто добавляются.

fallback: true

Если fallback: true, то при обращении к странице с несуществующим параметром будет возвращена "резервная" версия страницы.

Резервная - значит, с пустыми пропсами. При этом у объекта роутера поле isFallback будет равно true:

import { userRouter } from 'next/router';

function Post({ post }) {
    const router = useRouter();

    if (router.isFallback) {
        // рендеринг экрана загрузки
    }

    // рендеринг поста
}

Резервная страница будет отображаться до тех пор, пока Next в фоновом режиме не сгенерирует HTML и JSON для новой страницы (getStaticProps). Затем браузер получит JSON и отрендерит новую страницу, а новый путь добавится в список "уже отрендеренных". По сути у нас тут SSR.

Этот подход полезен, если у вас очень много страниц, которые зависят от данных (например, товары в интернет-магазине). Если рендерить страницы для всех товаров при сборке, это займет слишком много времение, поэтому изначально рендерим лишь некоторые страницы (getStaticPaths) и включаем fallback: true.

При запросе неуказанных товаров будет выполняться getStaticProps в фоновом режиме, а пользователь будет видеть резервную версию страницы, пока она не загрузится.

fallback: 'blocking'

Если fallback: 'blocking', то будет то же самое, что и для fallback: true, но резервная страница во время загрузки отображаться не будет.

#nextjs #серверныйрендеринг #документация

Next.js. Layouts

Статья в документации (англ.): https://nextjs.org/docs/basic-features/layouts

Лейауты - отдельные компоненты, которые предоставляют как бы HTML-обертку для наших страниц. Например, в лейаут можно добавить шапку и футер, общие для всех страниц, и таким образом подключать их.

Если у нас для всех страниц один лейаут, то проще всего подключить его в файле pages/_app.js (это компонент, инициализирующий активную страницу, подробнее здесь). Просто импортируем нужный лейаут и оборачиваем им контент страницы.

Если же у разных страниц разные лейауты, нужно идти другим путем.

Проще всего указать нужный лейаут прямо в теле компонента страницы, но тут есть один нюанс. Если в лейауте есть какое-то состояние (например, поле ввода), то при смене страниц оно будет сбрасываться, даже если лейаут один и тот же.

Демо: https://codesandbox.io/p/sandbox/jolly-agnesi-w90pmj?file=%2Fpages%2Fcomponents%2FLayoutWithState.tsx&selection=%5B%7B%22endColumn%22%3A24%2C%22endLineNumber%22%3A15%2C%22startColumn%22%3A24%2C%22startLineNumber%22%3A15%7D%5D

У нас есть две страницы, которые подключают в своем теле компонент LayoutWithState. Этот компонент имеет внутреннее состояние (useState). При переключении между страницами это состояние сбрасывается.

Документация предлагает нам использовать другой паттерн.

Мы можем добавить нашим страницам статический метод getLayout, который будет возвращать нужную обертку. Если вы используете TypeScript, понадобится создать новый тип NextPageWithLayout, расширяющий NextPage.

Внутри компонента-инициализатора App проверяем, есть ли у текущией страницы этот метод. Если есть, то вызываем его, чтобы получить нужную разметку.

Для обеих страниц переносим рендер обертки в метод getLayout. Теперь при переключении страницы состояние в лейауте сохраняется, так как React не заменяет компонент обертки на новый экземпляр.

Демо: https://codesandbox.io/p/sandbox/next-js-layouts-react-junior-forked-vl930n?file=%2Fpages%2F_app.tsx&selection=%5B%7B%22endColumn%22%3A1%2C%22endLineNumber%22%3A21%2C%22startColumn%22%3A1%2C%22startLineNumber%22%3A21%7D%5D

#nextjs #серверныйрендеринг #примерыкода #документация

Next.js. Изображения

Статьи в документации (англ.):
- https://nextjs.org/docs/basic-features/image-optimization
- https://nextjs.org/docs/api-reference/next/image

Next.js предоставляет собственный компонент Image, который является оберткой над стандартным img. Этот компонент умеет много полезного, например, самостоятельно может определять размеры изображений, чтобы предотвратить кумулятивный сдвиг страницы (CLS), реализует ленивую загрузку, умеет отображать плейсхолдер - и это наверняка не все его достоинства.

Основные атрибуты у него стандартные: src, alt, width и height, с тонкостями разберемся далее.

#nextjs #серверныйрендеринг #документация

Next.js. Image. Источник изображения

Image может работать и с локальными, и с удаленными файлами, причем с локальными - больше плюшек.

Локальные изображения

Изображения проекта должны храниться в папке public. Импортируем их в нужный компонент и передаем в проп src компонента Image.

Для таких изображений даже необязательно указывать width и height, если они не отличаются от оригинальных. Во время сборки Next проанализирует файл изображения, определит его размеры и подставит самостоятельно.

Динамический импорт не поддерживается.

Удаленные изображения

В src можно указать и обычный урл (относительный или абсолютный). Если используются абсолютные пути, то домены обязательно нужно добавить в файл next.config.js в секцию images.remotePatterns.

module.exports = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'example.com',
      },
    ],
  },
}

#nextjs #серверныйрендеринг #документация

Next.js. Image. srcset

Компонент Image рендерит стандартный тег img и проставляет для него массу полезных атрибутов, например, srcset. Что именно в нем будет, зависит от пропа sizes (https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/sizes). Если этот проп не передан, будет всего пара размеров, но может быть и очень большой список.

srcset генерируется и для локальных, и для удаленных изображений.

Видео (англ.): https://www.youtube.com/watch?v=R4sdWUI3-mY&ab_channel=BrunoAntunes

В начале видео очень подробно и понятно рассказывается об атрибутах srcset и sizes. Вторая часть (про Next.js) немного устарела, с момента записи произошли некоторые изменения.

#nextjs #серверныйрендеринг #документация

Next.js. Image. Ленивая загрузка

Изображения, сгенерированные компонентом Image по умолчанию грузятся "лениво" - только когда попадают во вьюпорт.
Если указать проп placeholder=blur, то до окончательной загрузки будет отображаться размытая версия изображения. Для локальных изображений она сгенерируется автоматически, а для всех остальных можно указать нужный адрес в пропе blurDataURL.

#nextjs #серверныйрендеринг #документация

Next.js. Image

Еще несколько полезных пропсов:

- fill - привязывает размеры изображения к размерам родительского контейнера. Работает как position: absolute + inset: 0.

- quality - позволяет управлять качеством картинки (от 1 до 100). По умолчанию 75.

- priority - указывает, что картинку нужно загрузить как можно быстрее, без ленивой загрузки. Следует использовать для Largest Contentful Paint.

#nextjs #серверныйрендеринг #документация

Next.js. Image. Собственный лоадер и настройка srcset

Мы можем самостоятельно настроить урлы изображений, которые попадают в конечный srcset, передав свой собственный лоадер в проп loader.

Лоадер это обычная функция, которая принимает адрес (src), ширину и качество (quality). И должна вернуть урл изображения для заданной ширины. Если у вас есть апи, который умеет изменять размер и качество изображений, здесь можно его использовать. Но в целом у Next.js как будто нормальный дефолтный лоадер.

Откуда берутся значения ширины? Из настроек images.deviceSizes и image.imageSizes в файле next.config.js. По умолчанию там уже заданы большие наборы, при необходимости их можно переопределить. Оба эти массива объединяются для формирования srcset.

#nextjs #серверныйрендеринг #документация

Next.js. Image. Форматы изображений

Последняя приятная плюшка компонента Image, о которой я упомяну - это автоматическое использование производительных форматов. Если браузер клиента поддерживает webp, то изображение будет в webp, даже если вы сохранили его в jpg.

Настроить разрешенные форматы можно в next.config.js в поле images.formats.

#nextjs #серверныйрендеринг #документация

Next.js. Оптимизация шрифтов

Next реально много делает для оптимизации тяжелых ресурсов. Про изображения мы уже поговорили, теперь поговорим о шрифтах. Next предоставляет удобные функции для работы с ними, в том числе и для google-шрифтов.

Все шрифты хостятся на вашем сервере (гугловские шрифты загружаются во время сборки и тоже помещаются на сервер).

Для работы понадобится пакет @next/font.

Локальные шрифты

Для локальных шрифтов используем функцию localFont. Работает и с одним файлом, и с несколькими, если разные начертания находятся в разных файлах:

import localFont from '@next/font/local';

const myFont1 = localFont({ src: './my-font.woff2' });

const myFont2 = localFont({
  src: [
    {
      path: './Roboto-Regular.woff2',
      weight: '400',
      style: 'normal',
    },
    {
      path: './Roboto-Italic.woff2',
      weight: '400',
      style: 'italic',
    },
  ]
});

Функция localFont возвращает объект с полями className и style.

Применять такой загруженный шрифт нужно с помощью сгенерированного имени класса. Для нужного элемента в разметке устанавливаем проп className={myFont.className}. Теперь для этого элемента установлено нужное значение font-family.

Google-шрифты

Для гугл-шрифтов нужно импортировать функции из пакета @next/font/google. Потребуется указать подмножество шрифта и при необходимости настройки, например, вес и стиль:

import { Inter } from '@next/font/google';
import { Roboto } from '@next/font/google';

const inter = Inter({ subsets: ['latin'] })
const roboto = Roboto({
  weight: '400',
  subsets: ['latin'],
});
const roboto1 = Roboto({
  weight: ['400', '700'],
  style: ['normal', 'italic'],
  subsets: ['latin'],
});

Используем эти шрифты точно так же, через className.

Шрифты в head

Можно использовать и более привычный вариант - указать шрифты в теге style с помощью синтаксиса jsx. Это следует делать в файле _app.tsx. Значение берем из myFont.style.fontFamily. Важно сделать блок со стилями глобальным (атрибут global, чтобы стили были помещены в head.

Демо: https://codesandbox.io/p/sandbox/wizardly-dream-5gv4mx?file=%2Fpages%2Findex.tsx&selection=%5B%7B%22endColumn%22%3A37%2C%22endLineNumber%22%3A3%2C%22startColumn%22%3A37%2C%22startLineNumber%22%3A3%7D%5D

В демке для документа установлен глобальный стиль с font-family: Inter (файл pages/_app.tsx). На главной странице (pages/index.tsx) загружен шрифт Pacifico. Он установлен для одного абзаца с помощью className.

Статья в документации: https://nextjs.org/docs/basic-features/font-optimization

#nextjs #серверныйрендеринг #документация #примерыкода

Не могу удержаться и не поделиться) Вчера впервые потребовалось использовать infer в боевых условиях: https://telegra.ph/Infer-v-TypeScript-primer-ispolzovaniya-01-21

Ни на что не претендую, просто небольшой пример практического применения не самой простой концепции.

#примерыкода #typescript #infer

TypeScript в Next.js

Соберем в одном месте типы, которые использует Next:

Данные для серверного рендеринга - GetStaticProps, GetStaticPaths, GetServerSideProps

import { GetStaticProps, GetStaticPaths, GetServerSideProps } from 'next';
export const getStaticProps: GetStaticProps = async function (context) {
  // ...
}
export const getStaticPaths: GetStaticPaths = async function () {
  // ...
}
export const getServerSideProps: GetServerSideProps = async function (context) {
  // ...
}

API-роуты - NextApiRequest, NextApiResponse

import type { NextApiRequest, NextApiResponse } from 'next'

export default function handler(req: NextApiRequest, res: NextApiResponse) {
  res.status(200).json({ name: 'John Doe' })
}

Тип NextApiResponse может также принимать обобщенный тип данных ответа.

Компонент App - AppProps

import type { AppProps } from 'next/app'

export default function MyApp({ Component, pageProps }: AppProps) {
  // ...
}

#nextjs #документация #typescript

Next.js. Динамические роуты

Про динамические роуты мы уже знаем: можно создать файл pages/post/[id].tsx и он будет соответствовать множеству страниц /post/1, post/2, post/hello и т.д.

При этом в компоненте страницы можно узнать конкретный id, воспользовавшись хуком useRouter (в поле router.query.id).

Но это только один уровень вложенности, то есть страницу /post/react/23 так не опишешь. Если требуется вложенная структура, Next и это умеет.

Создаем страницу pages/post/[...id].tsx и получаем все возможные пути с любым уровнем вложенности.

При этом router.query.id будет не строкой, а массивом.

Если к этому набору урлов требуется добавить еще и просто /post (без id), название файла должно выглядеть так: pages/post/[[...id]].tsx.

#nextjs #серверныйроутинг #документация

Next.js. Api-роуты: примеры использования

Обычно не следует вызывать из апи-роута другой апи, но есть пара случаев, когда можно:

- вы хотите спрятать урл, к которому обращаетесь (поэтому запрос с клиента происходит на ваш апи /api/secret, а уже оттуда - на нужный https://company.com/secret-url)
- вы хотите использовать какие-то переменные окружения для формирования запроса

#nextjs #серверныйрендеринг #документация