В данной небольшой заметке я бы хотел показать, как можно достаточно быстро развернуть и настроить проект на NextJS 11
Штатным и самым быстрым способом создания проекта является использование штатной утилиты create-next-app, которая, по аналогии со всем известной CRA создаст проект за считанные секунды.
Я же хочу показать другой путь - чуть более сложный, но позволяющий (через некоторое количество ручной работы) намного лучше понять, из чего проект строится и как настраивается, как устанавливается и настраивается компилятор TypeScript и линтер ESLint.
Немного о фреймворке NextJS
NextJS (https://nextjs.org/) - это javascript-фреймворк для создания универсальных веб-приложений (таких, которые могут рендерить html как на клиентской стороне, так и на серверной). Что он дает?
Первым шагом необходимо инициализировать проект и установить фреймворки
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
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"
]
}
Немного про опции файла конфигурации
Для начала в корне проекта создадим файл определений - 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",
"plugintypescript-eslint/eslint-recommended",
"plugintypescript-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-файлах проекта
Благодаря 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-компоненты.
После этого компилятор подтянет для компонентов-изображений корректный тип
Спасибо за внимание!
habr.com
Штатным и самым быстрым способом создания проекта является использование штатной утилиты 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 и его DOMnpm 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
В данной небольшой заметке я бы хотел показать, как можно достаточно быстро развернуть и настроить проект на NextJS 11 Штатным и самым быстрым способом создания проекта является использование штатной...
habr.com