Структура и организация проекта

Эта страница содержит обзор всех соглашений о папках и файлах в Next.js, а также рекомендации по организации вашего проекта.

Соглашения о папках и файлах

Папки верхнего уровня

Папки верхнего уровня используются для организации кода приложения и статических ресурсов.

Файлы верхнего уровня

Файлы верхнего уровня используются для настройки приложения, управления зависимостями, запуска middleware, интеграции инструментов мониторинга и определения переменных окружения.

Файлы маршрутизации

Вложенные маршруты

Динамические маршруты

Группы маршрутов и приватные папки

Параллельные и перехваченные маршруты

Соглашения для файлов метаданных

Иконки приложения

Open Graph и Twitter изображения

SEO

Организация проекта

Next.js не навязывает конкретный способ организации файлов проекта, но предоставляет несколько возможностей для удобной структуризации.

Иерархия компонентов

Компоненты, определённые в специальных файлах, рендерятся в определённой иерархии:

• layout.js
• template.js
• error.js (граница ошибок React)
• loading.js (граница Suspense React)
• not-found.js (граница ошибок React)
• page.js или вложенный layout.js

Компоненты рендерятся рекурсивно во вложенных маршрутах, что означает вложение компонентов сегмента маршрута внутри компонентов родительского сегмента.

Совмещение файлов (Colocation)

В директории app вложенные папки определяют структуру маршрутов. Каждая папка представляет сегмент маршрута, который соответствует сегменту в URL-пути.

Однако, несмотря на то, что структура маршрутов определяется через папки, маршрут не будет общедоступным, пока в сегменте маршрута не будет добавлен файл page.js или route.js.

И даже когда маршрут становится общедоступным, клиенту отправляется только контент, возвращаемый page.js или route.js.

Это означает, что файлы проекта можно безопасно размещать внутри сегментов маршрутов в директории app, не опасаясь, что они случайно станут доступными.

Полезно знать: Хотя вы можете размещать файлы проекта в app, вы не обязаны это делать. Если предпочитаете, можно хранить их вне директории app.

Приватные папки

Приватные папки можно создать, добавив к имени папки префикс в виде подчёркивания: _имяПапки

Это указывает, что папка является приватной деталью реализации и не должна учитываться системой маршрутизации, тем самым исключая папку и все её подпапки из маршрутизации.

Поскольку файлы в директории app по умолчанию можно безопасно совмещать, приватные папки не обязательны для совмещения. Однако они могут быть полезны для:

• Разделения логики интерфейса и маршрутизации.
• Единообразной организации внутренних файлов в проекте и экосистеме Next.js.
• Сортировки и группировки файлов в редакторах кода.
• Избежания потенциальных конфликтов имён с будущими соглашениями Next.js о файлах.

Полезно знать:

• Хотя это и не соглашение фреймворка, вы также можете пометить файлы вне приватных папок как "приватные", используя тот же паттерн с подчёркиванием.
• Можно создать сегменты URL, начинающиеся с подчёркивания, добавив к имени папки префикс %5F (URL-кодированная форма подчёркивания): %5FимяПапки.
• Если не использовать приватные папки, полезно знать специальные соглашения Next.js о файлах, чтобы избежать неожиданных конфликтов имён.

Группы маршрутов (Route Groups)

Группы маршрутов можно создать, заключив папку в скобки: (имяПапки)

Это указывает, что папка предназначена для организации и не должна включаться в URL-путь маршрута.

Группы маршрутов полезны для:

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

Папка src

Next.js поддерживает хранение кода приложения (включая app) внутри опциональной папки src. Это отделяет код приложения от файлов конфигурации проекта, которые в основном находятся в корне проекта.

Примеры

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

Полезно знать: В наших примерах ниже мы используем папки components и lib как обобщённые заполнители — их имена не имеют особого значения для фреймворка, и ваши проекты могут использовать другие папки, такие как ui, utils, hooks, styles и т.д.

Хранение файлов проекта вне app

Эта стратегия предполагает хранение всего кода приложения в общих папках в корне проекта, а директория app используется исключительно для маршрутизации.

Хранение файлов проекта в корневых папках внутри app

Эта стратегия предполагает хранение всего кода приложения в общих папках в корне директории app.

Разделение файлов проекта по функциональности или маршрутам

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

Организация маршрутов без влияния на URL-путь

Для организации маршрутов без изменения URL создайте группу, чтобы держать связанные маршруты вместе. Папки в скобках будут исключены из URL (например, (marketing) или (shop)).

Хотя маршруты внутри (marketing) и (shop) имеют одинаковую иерархию URL, для каждой группы можно создать отдельный макет, добавив файл layout.js в их папки.

Подключение определённых сегментов к макету

Чтобы подключить определённые маршруты к макету, создайте новую группу маршрутов (например, (shop)) и переместите в неё маршруты, которые должны использовать общий макет (например, account и cart). Маршруты вне группы не будут использовать этот макет (например, checkout).

Подключение скелетонов загрузки к определённому маршруту

Чтобы применить скелетон загрузки через файл loading.js к определённому маршруту, создайте новую группу маршрутов (например, /(overview)) и поместите ваш loading.tsx внутрь этой группы.

Теперь файл loading.tsx будет применяться только к странице dashboard → overview, а не ко всем страницам dashboard, без изменения структуры URL-пути.

Создание нескольких корневых макетов

Чтобы создать несколько корневых макетов, удалите корневой файл layout.js и добавьте файл layout.js в каждую группу маршрутов. Это полезно для разделения приложения на секции с совершенно разным интерфейсом или опытом. Теги <html> и <body> нужно добавить в каждый корневой макет.

В приведённом примере и (marketing), и (shop) имеют свои собственные корневые макеты.