В данной небольшой заметке я бы хотел показать, как можно достаточно быстро развернуть и настроить проект на NextJS 11

Штатным и самым быстрым способом создания проекта является использование штатной утилиты create-next-app, которая, по аналогии со всем известной CRA создаст проект за считанные секунды.

Я же хочу показать другой путь - чуть более сложный, но позволяющий (через некоторое количество ручной работы) намного лучше понять, из чего проект строится и как настраивается, как устанавливается и настраивается компилятор TypeScript и линтер ESLint.

Немного о фреймворке NextJS

NextJS (https://nextjs.org/) - это javascript-фреймворк для создания универсальных веб-приложений (таких, которые могут рендерить html как на клиентской стороне, так и на серверной). Что он дает?

Простой, интуитивно понятный роутинг по страницам приложения, основанный на файлах
Поддержку SSR - server-side rendering, что позволяет разгрузить клиентские устройства и каналы связи ценой нагрузки на сервер. Клиенты на слабых устройствах (в том числе, и в особенности - мобильных) и клиенты на слабых и нестабильных каналах связи получают намного более высокий user experience за счет в разы более быстрого отображения контента
Поддержку SSG - static site generation, что позволяет много всего интересного: корректно индексировать контент сайта без танцев с бубном вокруг nginx, эффективно кэшировать данные и пользоваться сетями доставки контента (CDN)
Поддержку фичей Webpack 5 (который во фреймворке используется как бортовой сборщик)
Возможность в рамках одного проекта создавать как фронтендовую часть, так и бэкендовую (за счет создания api-эндпоинтов)
Поддержку TypeScript "из коробки"
Оптимизацию изображений (и использование изображений как React-компонентов)
CSS Modules, Sass/SCSS (через установку препроцессора)
и много всего интересного, о чем можно прочитать на официальном сайте и в документации

Результаты (с более-менее последовательной и соответствующей тексту пошаговой разбивкой в виде коммитов) - в репозитории

Создаем проект, устанавливаем react и next

Для работы NextJS требует Node.js версии 12.0 и выше, но я рекомендую использовать релиз Node.js 14.17 как наиболее стабильный и вообще LTS.

Первым шагом необходимо инициализировать проект и установить фреймворки

mkdir nextjs-app && cd nextjs-app
npm init -y
npm i react react-dom next

После установки файл package.json проекта будет выглядеть примерно так:

{
  "name": "nextjs-app",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "dependencies": {
    "next": "^11.0.1",
    "react": "^17.0.2",
    "react-dom": "^17.0.2"
  }
}

Далее, необходимо в секции scripts указать все скрипты, необходимые для проекта - запуска dev-сервера, сборки, запуска собранного проекта и запуска линтера (небольшой тюннинг линтера будет показан чуть позже):

"scripts": {
  "dev": "next dev",
  "build": "next build",
  "start": "next start",
  "lint": "next lint"
}

Если вдруг у вас (как и у меня) порт по умолчанию (3000) перманентно чем-то занят, можно переопределить его ключом -p:

"scripts": {
  "dev": "next dev -p 9993",
  "build": "next build",
  "start": "next start",
  "lint": "next lint"
}

Базовая преднастройка закончена, теперь пришло время установить и настроить typescript

TypeScript

Устанавливаем TypeScript и типы для React и его DOM

npm i -D typescript @types/react @types/react-dom

Далее необходимо в корне проекта создать файл конфигурации компилятора - tsconfig.json

Я использую следующую конфигурацию (стоит ли ее использовать - вопрос вкуса):

{
  "compilerOptions": {
    "target": "es5",
    "lib": [
      "dom",
      "dom.iterable",
      "esnext"
    ],
    "allowJs": false,
    "skipLibCheck": true,
    "strict": true,
    "strictPropertyInitialization": false,
    "forceConsistentCasingInFileNames": true,
    "noEmit": true,
    "esModuleInterop": true,
    "module": "esnext",
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "preserve"
  },
  "include": [
    "**/*.ts",
    "**/*.tsx"
  ],
  "exclude": [
    "node_modules"
  ]
}

Немного про опции файла конфигурации

target - целевая версия ECMAScript. Для поддержки более старых браузеров можно использовать версию ES5 (как в примере). Подробнее
lib - набор библиотек определений типов, нужных для работы приложения. Наше приложение работает в браузере, поэтому нам нужны dom (основные типы DOM браузера), dom.iterable (итерационные типы DOM) и esnext (современные API ECMAScript). Подробнее
allowJs - разрешен ли импорт JS-файлов в TS- и TSX-файлы. Подробнее
skipLibCheck - пропускать ли полную проверку *.d.ts-файлов (файлов определений). Если true, компилятор будет проверять только библиотеки, непосредственно импортируемые в проекте. Подробнее
strict - включает пачку режимов строгой проверки приложения. После включения можно прицельно отключить те проверки, которые в данном проекте не нужны. Подробнее
strictPropertyInitialization - отключает проверку объявленного, но не установленного в конструкторе класса свойства. Подробнее
forceConsistentCasingInFileNames - включает форсированную чувствительность к регистру имени файла. Актуально, если разработчики работают в разных операционных системах. Подробнее
noEmit - не создавать результирующие файлы компиляции. У нас итоговой сборкой рулит NextJS и Webpack, поэтому промежуточные файлы нам не нужны. Подробнее
esModuleInterop - позволяет импортировать файлы по стандартам ES6. Подробнее
module - используемая модульная система. Подробнее
moduleResolution - используемая стратегия разрешения импортов. Подробнее
resolveJsonModule - разрешен ли импорт JSON-файлов. Подробнее
isolatedModules - нужно ли компилятору обрабатывать каждый файл как изолированный модуль. Если в файле не хватает импортов и определений (или по какой-то еще причине компилятор не будет понимать, что это за класс/тип/ ит.д.) - при компиляции будет выдаваться ошибка. Подробнее
jsx - какой стратегии будет придерживаться компилятор, когда встретит JSX-код. Он, например, может пытаться заменять JSX на эквивалентные конструкции вида React.createElement или, как в нашем случае - выдавать JSX-код без изменений. Подробнее
include - какие файлы будут использоваться при компиляции
exclude - а какие - не будут

Конфигурация NextJS, структура директорий и запуск

После настройки компилятора самое время перейти к донастройке проекта, первому роуту и первому запуску

Для начала в корне проекта создадим файл определений - next-env.d.ts, содержащий референсы на определения типов NextJS

/// <reference types="next" />
/// <reference types="next/types/global" />
/// <reference types="next/image-types/global" />

и конфигурационный файл - next.config.js

module.exports = {
  reactStrictMode: true,
}

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

Теперь необходимо воссоздать для NextJS его привычную структуру директорий. По умолчанию он требует наличия директории pages/ в корне проекта. Данная директория используется для работы роутера: каждый файл в ней является обработчиком какого-то роута (файл index.tsx, например, будет индексным файлом и отрабатывать на роуте /).

Директория pages в корне проекта - это удобно, но только пока проект пуст. Постепенно к ней добавится куча других директорий - components, utils, helpers и прочего. Их нельзя прятать внутрь директории pages - там NextJS ожидает увидеть только обработчики, и любой файл/директорию будет интерпретировать именно так, рождая ошибки. Поэтому NextJS позволяет создать (но при работе create-next-app, что характерно, сам не создает) директорию src и в нее уже спрятать весь код приложения. Сделаем именно так:

mkdir -p src/pages

В директории pages создадим файл _app.tsx (дефолтный компонент приложения). В нем мы создаем базовую структуру компонента приложения и используем встроенный компонент NextJS - Head, чтобы передать title в заголовок страницы

import { AppProps } from 'next/dist/next-server/lib/router/router';
import React from 'react';
import Head from 'next/head';

const MyApp = ({ Component, pageProps }: AppProps): JSX.Element => {
  return (
    <>
      <Head>
        <title>NextJS App From Scratch</title>
      </Head>
      <Component {...pageProps} />
    </>
  );
};

export default MyApp;

А теперь - создаем индексный модуль index.tsx с компонентом домашней страницы

const Home = (): JSX.Element => {
  return (
    <div>
      Hello, NextJS!
    </div>
  );
};

export default Home;

Теперь можно запустить проект командой

npm run dev

и радоваться "Hello, NextJS!" в браузере

Установка, настройка и запуск линтера

Линтинг - это хорошо. Линтинг позволяет нам не забывать про импорты, типы и точки с запятой. Давайте настроим линтинг.

Под капотом NextJS использует в качестве линтера, как это ни странно, ESLint. Для корректной работы ESlint с typescript-кодом необходимо установить несколько плагинов и создать файл конфигурации .eslintrc

Для начала - установка плагинов и парсеров

npm i -D eslint eslint-config-next
npm i -D @typescript-eslint/eslint-plugin @typescript-eslint/parser

И теперь сконфигурируем его

{
	"root": true,
	"parser": "@typescript-eslint/parser",
	"plugins": [
		"@typescript-eslint"
	],
	"rules": {
		"semi": "off",
		"@typescript-eslint/semi": [
			"error"
		],
		"@typescript-eslint/no-empty-interface": [
			"error",
			{
				"allowSingleExtends": true
			}
		]
	},
	"extends": [
		"next",
		"next/core-web-vitals",
		"eslint:recommended",
		"plugin:@next/next/recommended",
		"plugin:@typescript-eslint/eslint-recommended",
		"plugin:@typescript-eslint/recommended"
	]
}

Здесь мы устанавливаем в качестве парсера typescript-eslint/parser, в правилах отключаем стандартную обработку точек с запятой и назначаем свою (мне нравится, когда линтер ругается на отсутствие точки с запятой с помощью error, но вы можете поменять typescript-eslint/semi на warn, например). Кроме того, в секции extends мы подключаем много разных конфигураций как из NextJS, так и из плагинов - так мы будем получать рекомендации по созданию качественного кода. На данном этапе IDE (особенно если у вас VSCode, как у меня) уже должна отображать результаты линтинга корректно.

Для запуска проверки проекта линтером (например, перед сборкой) есть два пути: можно пользоваться штатной оберткой next lint (которая есть просто запуск eslint с некоторыми предопределенными в глубинах NextJS настройками), либо - запускать eslint напрямую, указав директорию, в которой он должен анализировать код. Я предпочитаю второй вариант (одной из причин является то, что next lint по умолчанию проверяет только директории pages/, components/ и lib/ проект, а чтобы добавить к ним, например, utils/, необходимо писать длинную портянку ключей next lint -d pages -d utils ....)

Посему, необходимо обновить скрипт линтинга в файле package.json на следующий:

"scripts": {
  "dev": "next dev -p 9993",
  "build": "next build",
  "start": "next start",
  "lint": "eslint src/**/*.{ts,tsx}"
},

Этим мы говорим, что хотим натравить eslint на все директории внутри src/, в которых лежат файлы ts и tsx.

После этого запуск npm run lint будет выводить нам все ошибки во всех typescript-файлах проекта

Настройка использования SVG

По умолчанию NextJS умеет работать с изображениями, как с компонентами. Что, надо признать, достаточно удобно. Однако, если возникнет необходимость использовать векторные изображения в формате SVG, потребуется некоторый тюннинг конфигурационных файлов. Сделаем это загодя.

Благодаря Webpack в качестве бортового сборщика подключение загрузчика SVG не представляет серьезной проблемы. Сначала необходимо установить пакет загрузчика в dev-зависимости:

npm i -D @svgr/webpack

и затем - добавить webpack-правило для этого загрузчика в конфигурационный файл сборщика (next.config.js)

module.exports = {
  reactStrictMode: true,
  webpack(config, options) {
    config.module.rules.push({
      test: /\.svg$/i,
      issuer: { and: [/\.(ts)x?$/] },
      use: [
        {
          loader: "@svgr/webpack",
          options: {
            svgoConfig: { plugins: [{ removeViewBox: false }] },
          },
        },
      ],
    });

    return config;
  }
}

Если бы мы использовали JS вместо TypeScript, на этом настройка SVG бы завершилась. Но нет, за типизацию надо платить.

Для того, чтобы компилятор подтягивал к компоненту SVG-изображения корректные типы, необходимо внести изменения в файл определений проекта - next-env.d.ts. И в NextJS 10 мы бы так и сделали. Но в 11 версии данный файл стал автогенерируемым и сборщик перетирает его каждый раз при сборке, что несколько усложняет дело. Нужно создавать отдельный файл определений.

Создаем в корне проекта директорию @types, а в ней - файл images.d.ts следующего содержания:

declare module "*.svg" {
  const component: React.FC<React.SVGProps<SVGAElement>>;
  
  export default component;
}

Этим мы сообщаем компилятору, что модули с расширением *.svg - это не объекты типа any (как в типах по-умолчанию), а вполне себе функциональные React-компоненты.

После этого компилятор подтянет для компонентов-изображений корректный тип

Итоги

Следуя данной заметке, можно достаточно быстро (ну, второй раз выходит и правда быстро!) создать полностью настроенный NextJS-проект с подключенным и настроенным TypeScript, реализованной поддержкой SVG и линтингом.

Спасибо за внимание!

Минимальная установка NextJS без create-next-app