NEST-NEXT: Best Practices — Часть 1

Это первая часть статьи о применении комбинации технологий nest.js и NEXT.js, где будет рассмотрено создание проекта, подключение фреймворков и выбор эффективного способа работы с SSR. Во второй части я расскажу о HMR, использовании данных при SSR и разворачивании "за слешом".

Наступил Октябрь 2022 и вышла новая 13 версия NEXT.js. В ней очень много важных изменений, которые сильно меняют то, как можно использовать nest.js и NEXT.js вместе. Пока я изучаю работу с новой директорией app и готовлю обновление для этого туториала, предлагаю вам тоже оставлять ваш фидбек по использованию NEXT.js 13 с библиотекой nest-next (про которую речь пойдет дальше) в этом GitHub issue.

Оглавление

• Вступление

• Прежде чем мы начнем

• Создание приложения nest

• Установка NEXT.js

• Подружим фреймворки

• Запрос данных для SSR

  • Через контроллер nest

  • Через прямое обращение к сервисам

  • Через обращение сервера к самому себе

    • Обертка над fetch

    • Прокидывание параметров запроса

• Заключение

Вступление

Когда речь заходит о выборе фреймворка для разработки вебсайта в 2021 году, обязательно всплывает NEXT.js - основанный на React фреймворк из коробки позволяет поддерживать SSR/SSG, TypeScript, code-splitting, раутинг и имеет прочие возможности. Но это в первую очередь клиентский фреймворк, который также имеет простенький сервер.

Возникает вопрос - а что использовать для бэкенда/фронтбэка? Отличным вариантом будет nest - прогрессивный node.js фреймворк, который позволяет писать достаточно производительные и легко поддерживаемые бэкенды. Сильным его преимуществом является знакомая по Angular/Spring MVC модель архитектуры, основанная на DI.

А как связать эти две сущности? Есть вариант запускать два сервера и настраивать хитрый proxy-сервер, который будет распределять запросы между ними, но такой способ очевидно имеет недостатки: необходимость поднимать несколько сервисов/контейнеров и сложная конфигурация прокси.

К счастью, существует специальный пакет nest-next, который позволяет запускать NEXT.js внутри nest, рендерить страницы на запросы и т.д. Но при такой работе возникает ряд нюансов и неприятностей, решения которых не всегда очевидны. Давайте вместе создадим простой проект на nest-next, по ходу чего я расскажу о главных особенностях данных технологий и поделюсь теми best practices, которые были обнаружены мною и моими коллегами за почти год разработки в таком режиме.

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

Прежде чем мы начнем

Скорее всего, решение использовать NEXT.js будет принято первым, а потом уже команда или одиночный разработчик задумаются о выборе бэкенда или фронтбэка. Здесь следует остановиться и всерьез рассмотреть имеющиеся возможности NEXT.js. Если планируется создавать простой фронтбэк, который будет рендерить страницы клиенту и проксировать запросы в бэкенд, то сервер NEXT.js как раз это и умеет, не имеет смысла тянуть отдельный сервер и заниматься оптимизацией совместной работы двух сущностей.

Следует рассматривать симбиоз nest-next только в тех случаях, когда требуется либо полноценный бэкенд на node.js, который не хочется выносить в отдельный сервис, либо достаточно серьезный фронтбэк-сервер с существенными обязанностями и/или завязкой под имеющуюся инфраструктуру на Express/nest.

Статья была разделена на 2 части: в этой, первой части я расскажу про создание проекта на nest-next с нуля и его настройке, решению самых первых проблем SSR. Если вы считаете себя уже достаточно опытным разработчиком в этом стеке, то, возможно, стоит начать сразу со второй части, где я рассказываю о HMR, использовании данных при SSR и разворачивании "за слэшом".

И последнее: для желающих сразу же взглянуть на готовый код прикладываю ссылку на проект на GitHub - https://github.com/yakovlev-alexey/nest-next-example - последовательность коммитов в целом совпадает с ходом дилогии статей.

Создание приложения nest

Первым делом создадим базовое приложение nest в терминале. Для этого воспользуемся утилитой @nestjs/cli, которая позволяет генерировать шаблонные проекты:

npx @nestjs/cli new nest-next-example

Проследуем указаниям генератора. Я выбрал yarn в качестве менеджера пакетов и далее в статье буду приводить сниппеты для yarn, для npm они будут аналогичными.

В результате выполнения мы получим стартовый проект, который сразу можно запустить. Предлагаю удалить файлы для тестирования (директория test в корне проекта и файл app.controller.spec.ts - в рамках данной статьи мы не будем писать тесты.

Для удобства будем использовать следующую архитектуру папки src:

└── src
    ├── client # клиентский код: хуки, компоненты и т.д.
    ├── pages # экраны вебсайта (NEXT.js)
    ├── server # сервер nest.js
    └── shared # общие типы/хелперы и т.д.

Отразим эти изменения в конфигурации nest:

// ./nest-cli.json
{
    "collection": "@nestjs/schematics",
    "sourceRoot": "src",
    "entryFile": "server/main"
}

Теперь мы можем запустить сервер командой yarn start:dev и увидеть наш "Hello world" по адресу localhost:3000 в браузере.

Из-за особенностей сборки nest, при запуске может появиться ошибка Error: Cannot find module '.../dist/server/main' - в таком случае временно можно сделать "entryFile": "main".

Установка NEXT.js

Теперь добавим в проект NEXT.js:

# NEXT.js и его peer зависимости
yarn add next react react-dom
# необходимые типы и конфиг для eslint
yarn add -D @types/react @types/react-dom eslint-config-next

Запустим сервер разработки NEXT.js: yarn next dev. В наш проект будут внесены следующие необходимые изменения: добавлен файл next-env.d.ts и изменен tsconfig.json. Сервер будет успешно запущен, но когда мы попытаемся снова запустить nest, обнаружим, что изменения конфигурации TypeScript сломали сборку. Переиспользуем имеющийся tsconfig.build.json в качестве tsconfig.server.json и поместим туда следующее:

// ./tsconfig.server.json
{
    "extends": "./tsconfig.json",
    "compilerOptions": {
        "noEmit": false
    },
    "include": [
        "./src/server/**/*.ts",
        "./src/shared/**/*.ts",
        "./@types/**/*.d.ts"
    ]
}

Теперь сервер вновь заработает, когда мы подключим корректный конфиг Typescript. Для этого обновим скрипты в package.json, чтобы обеспечить поддержку обоих фреймворков:

// ./package.json
"scripts": {
    "prebuild": "rimraf dist",
    "build": "yarn build:next && yarn build:nest",
    "build:next": "next build",
    "build:nest": "nest build --path ./tsconfig.server.json",
    "start": "node ./dist/server/main.js",
    "start:next": "next dev",
    "start:dev": "nest start --path ./tsconfig.server.json --watch",
    "start:debug": "nest start --path ./tsconfig.server.json --debug --watch",
    "start:prod": "node dist/main",
    // ... прочие скрипты (lint/format etc)
},

Добавим в каталог src/pages экран index и компонент App, необходимый для работы NEXT.js:

// ./src/pages/app.tsx
import { FC } from 'react';
import { AppProps } from 'next/app';

const App: FC<AppProps> = ({ Component, pageProps }) => {
    return <Component {...pageProps} />;
};

export default App;

// ./src/pages/index.tsx
import { FC } from 'react';

const Home: FC = () => {
    return <h1>Home</h1>;
};

export default Home;

Запустив сервер NEXT.js командой yarn start:next, мы сможем увидеть эти страницы по адресу localhost:3000.

В .gitignore следует добавить .next - туда будут попадать результаты сборок NEXT.js

Подружим фреймворки

Теперь у нас есть два отдельных сервера, но нашей целью было подключить NEXT.js в nest. Для этого установим пакет nest-next:

yarn add nest-next

Для корректной работы библиотеки нам следует подключить RenderModule в app.module.ts:

// ./src/server/app.module.ts
import { Module } from '@nestjs/common';
import { RenderModule } from 'nest-next';
import Next from 'next';
import { AppController } from './app.controller';
import { AppService } from './app.service';

@Module({
    /* в метод инициализации следует
        передать инстанс сервера NEXT.js */
    imports: [RenderModule.forRootAsync(Next({}))],
    controllers: [AppController],
    providers: [AppService],
})
export class AppModule {}

Теперь нам доступен декоратор @Render, который позволяет рендерить страницы подключаемым рендер-модулем nest. Обновим контроллер app.controller.ts:

// ./src/server/app.controller.ts
import { Controller, Get, Render } from '@nestjs/common';
import { AppService } from './app.service';

@Controller()
export class AppController {
    constructor(private readonly appService: AppService) {}
    
    @Get()
    @Render('index')
    home() {
        return {};
    }
}

Запустим сервер nest: yarn start:dev. При попытке зайти на страницу, мы увидим ошибку при создании инстанса NEXT.js - собранный бандл не был обнаружен - сервер запустился в продакшен режиме. Для корректной работы нам нужно передать в инстанс NEXT.js опцию dev: true:

// ./src/server/app.module.ts
imports: [
    RenderModule.forRootAsync(Next({ dev: true }))
],

Теперь попробуем зайти на localhost:3000. Мы увидим стандартную страницу 404 NEXT.js - странно, ведь у нас есть файл index.tsx в src/pages и мы видели его при запуске отдельного сервера NEXT.js. На самом деле nest-next по умолчанию ищет страницы в директории views внутри pages, чтобы изменить этот параметр, передадим опцию viewsDir в метод инициализации RenderModule:

// ./src/server/app.module.ts
imports: [
    RenderModule.forRootAsync(
        Next({ dev: true }),
        /* значение null сообщает nest-next 
            искать экраны в корне pages */
        { viewsDir: null }
    )
],

Рядом с viewsDir есть еще одна опция dev уже для nest-next, которая отвечает уже за сериализацию ошибок перед отправкой их в NEXT.js - в production окружениях мы можем не хотеть отправлять подробную информацию об ошибке.

Теперь по адресу localhost:3000 мы наконец обнаружим нашу страницу, описанную в index.tsx.

Запрос данных для SSR

Одно из главных преимуществ NEXT.js - возможность удобно запрашивать данные для SSR. Для этого у нас есть сразу несколько методов, мы будем использовать getServerSideProps (далее - GSSP) - для рендеринга страницы во время обработки запроса - классический SSR. При этом nest-next корректно поддерживает другие виды генерации страниц, предоставляемые NEXT.js. Первым делом добавим еще одну страницу. Предположим, что главная страница - список всех записей в блоге, и добавим страницу блогпоста по id. На нее добавим ссылку на главную страницу.

// ./src/shared/types/blog-post.ts
export type BlogPost = {
    title: string;
    id: number;
};

// ./src/server/app.controller.ts
import { Controller, Get, Param, Render } from '@nestjs/common';

// ...

@Get(':id')
@Render('[id]')
public blogPost(@Param('id') id: string) {
 return {};
}

// ./src/pages/[id].tsx
import { GetServerSideProps } from 'next';
import Link from 'next/link';
import { FC } from 'react';
import { BlogPost } from 'src/shared/types/blog-post';

type TBlogProps = {
    post: BlogPost;
};

const Blog: FC<TBlogProps> = ({ post = {} }) => {
    return (
        <div>
            <Link href={'/'}>Home</Link>
            <h1>Blog {post.title}</h1>
        </div>
    );
};

export const getServerSideProps: GetServerSideProps<TBlogProps> = async (
    ctx,
) => {
    return { props: {} };
};

export default Blog;

// ./src/pages/index.tsx
import { GetServerSideProps } from 'next';
import Link from 'next/link';
import { FC } from 'react';
import { BlogPost } from 'src/shared/types/blog-post';

type THomeProps = {
    blogPosts: BlogPost[];
};

const Home: FC<THomeProps> = ({ blogPosts = [] }) => {
    return (
        <div>
            <h1>Home</h1>
            {blogPosts.map(({ title, id }) => (
                <div key={id}>
                    <Link href={`/${id}`}>{title}</Link>
                </div>
            ))}
        </div>
    );
};

export const getServerSideProps: GetServerSideProps<THomeProps> = async (
    ctx,
) => {
    return { props: {} };
};

export default Home;

Отлично, теперь у нас есть страницы, которым нужны данные. Осталось эти данные им отправить. Рассмотрим разные варианты, которые мы можем использовать.

Через контроллер nest

Наш контроллер home в app.controller.ts возвращает пустой объект - все, что мы отправим отсюда, попадет в ctx.query в GSSP.

Замокаем блогпосты в app.service.ts:

// ./src/server/app.service.ts
import { Injectable } from '@nestjs/common';
import { from } from 'rxjs';

const BLOG_POSTS = [
    { title: 'Lorem Ipsum', id: 1 },
    { title: 'Dolore Sit', id: 2 },
    { title: 'Ame', id: 3 },
];

@Injectable()
export class AppService {
    getBlogPosts() {
        return from(BLOG_POSTS);
    }
}

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

// ./src/server/app.controller.ts
import { map, toArray } from 'rxjs';

// ...

@Get('/')
@Render('index')
home() {
    return this.appService.getBlogPosts().pipe(
        toArray(),
        map((blogPosts) => ({ blogPosts })),
    );
}

Теперь в GSSP мы сможем получить доступ к blogPosts через ctx.query. Очевидно, такой вариант крайне неудобен - тайпинги query подсказывают нам, что нет там никакого blogPosts, а есть только параметры запроса ParsedUrlQuery. Дейстивтельно, попробуем зайти на страницу localhost:3000/1, например, и осуществить переход по ссылке на Home - мы обнаружим, что blogPosts там не окажется.

При переходах NEXT.js обращается к внутреннему эндопинту, который на сервере исполняет GSSP и возвращает JSON - в таком случае наш контроллер вовсе не исполняется, а в ctx.query попадают только параметры запроса из адреса и location.search.

Через прямое обращение к сервисам

Как известно, GSSP исполняется только на сервере, следовательно, мы могли бы обращаться к сервисам nest прямо из тела функции. В действительности этот вариант так же нас совершенно не устраивает - нам нужно самостоятельно создавать инстансы сервисов, про сервисы-синглтоны, DI и вообще все преимущества nest можно забыть. Если же мы попробуем обратиться к сервисам через инстанс приложения, мы натолкнемся на схожую проблему при переходах - сервисам будет не хватать контекста (например, объекта req) для корректной работы.

Через обращение сервера к самому себе

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

// ./src/shared/constants/env.ts
export const isServer = typeof window === 'undefined';

export const isClient = !isServer;

export const NODE_ENV = process.env.NODE_ENV;

export const PORT = process.env.PORT || 3000;

Обновим подписку на порт в main.ts (await app.listen(PORT)), а также определим режим работы для NEXT в зависимости от среды исполнения:

// ./src/server/app.module.ts
RenderModule.forRootAsync(
    Next({ dev: NODE_ENV === 'development' }),
    { viewsDir: null }
)

// ./package.json
"start:dev": "NODE_ENV=development nest start --path ./tsconfig.server.json --watch"

Теперь сервер импортирует модули из src/shared и структура скомпилированного сервера nest выглядит иначе: main.ts переехал в dist/server, как и следовало изначально. Если вы меняли entryFile в nest-cli.json, то нужно вернуть изначально запланированное значение и перезапустить сервер, а папку dist очистить, иначе сервер будет запускаться на старой версии сборки.

Обертка над fetch

Теперь мы можем добавить обертку для выбора адреса запроса в fetch в зависимости от среды исполнения - на сервере мы будем отсылать запрос самим себе:

// ./src/shared/utils/fetch.ts
import { isServer, PORT } from '../constants/env';

const envAwareFetch = (url: string, options?: Record<string, unknown>) => {
    const fetchUrl =
        isServer && url.startsWith('/') ? `http://localhost:${PORT}${url}` : url;

    return fetch(fetchUrl, options).then((res) => res.json());
};

export { envAwareFetch as fetch };

Обновим сервис app.service.ts:

// ./src/server/app.service.ts
import { Injectable, NotFoundException } from '@nestjs/common';
import { from, of, toArray } from 'rxjs';

const BLOG_POSTS = [
  { title: 'Lorem Ipsum', id: 1 },
  { title: 'Dolore Sit', id: 2 },
  { title: 'Ame', id: 3 },
];

@Injectable()
export class AppService {
  getBlogPosts() {
    return from(BLOG_POSTS).pipe(toArray());
  }

  getBlogPost(postId: number) {
    const blogPost = BLOG_POSTS.find(({ id }) => id === postId);

    if (!blogPost) {
      throw new NotFoundException();
    }

    return of(blogPost);
  }
}

Добавим эндпоинты API для запроса блогпостов в наш контроллер:

// ./src/server/app.controller.ts
import { Controller, Get, Param, ParseIntPipe, Render } from '@nestjs/common';
import { AppService } from './app.service';

@Controller()
export class AppController {
  constructor(private readonly appService: AppService) {}

  @Get('/')
  @Render('index')
  home() {
    return {};
  }

  @Get(':id')
  @Render('[id]')
  public blogPost(@Param('id') id: string) {
    return {};
  }

  @Get('/api/blog-posts')
  public listBlogPosts() {
    return this.appService.getBlogPosts();
  }

  @Get('/api/blog-posts/:id')
  public getBlogPostById(@Param('id', new ParseIntPipe()) id: number) {
    return this.appService.getBlogPost(id);
  }
}

Отлично, теперь мы можем обновить методы GSSP в наших экранах:

// ./src/pages/index.tsx
import { fetch } from 'src/shared/utils/fetch';

export const getServerSideProps: GetServerSideProps<THomeProps> = async () => {
    const blogPosts = await fetch('/api/blog-posts');
    return { props: { blogPosts } };
};

// ./src/pages/[id].tsx
import { fetch } from 'src/shared/utils/fetch';

export const getServerSideProps: GetServerSideProps<TBlogProps> = async () => {
    const id = ctx.query.id;
    const post = await fetch(`/api/blog-posts/${id}`);
    
    return { props: { post } };
};

Зайдем на localhost:3000 и увидим, что список блогпостов действительно подгрузился. Перейдем по ссылке на один из постов - здесь тоже все работает, как нужно, мы видим корректное название. Но попробуем обновить страницу: теперь мы видим ошибку - такой блогпост не был найден. Странно, ведь при переходе все работало.

На самом деле, как мы уже выяснили, при SSR nest-next подкладывает в ctx.query возвращаемое значение контроллера, соответственно, параметров запроса там не оказывается. Решим это недоразумение - вернем нужный параметр из контроллера.

// ./src/server/app.controller.ts
@Get(':id')
@Render('[id]')
public blogPost(@Param('id') id: string) {
    return { id };
}

Для эндпоинта API мы парсили передаваемый параметр в Int - здесь нет в этом необходимости, ведь это внесет больше путаницы: NEXT.js не преобразует параметры, когда помещает их ctx.query, не будем и мы.

Теперь обновим страницу в браузере - как и ожидалось, это решило нашу проблему.

Прокидывание параметров запроса

Прописывать все параметры вручную в каждом контроллере неудобно - можно забыть, особенно если это касается location.search. Для избежания повторения таких конструкций обратимся к AOP (Aspect-oriented programming) и механизму его реализации при обработке запросов в nest: концепту Interceptor.

// ./src/server/params.interceptor.ts
import {
    Injectable,
    NestInterceptor,
    ExecutionContext,
    CallHandler,
} from '@nestjs/common';
import { Request } from 'express';
import { Observable } from 'rxjs';
import { map } from 'rxjs/operators';

@Injectable()
export class ParamsInterceptor implements NestInterceptor {
    intercept(context: ExecutionContext, next: CallHandler): Observable<unknown> {
        const request = context.switchToHttp().getRequest() as Request;
          
      /* после выполнения обработчика запроса подложим
          возвращаемому значению параметры запроса */
        return next.handle().pipe(
            map((data) => {
                return {
                    ...request.query,
                    ...request.params,
                    ...data,
                };
            }),
        );
    }
}

В соответствии с документацией NEXT.js, параметры запроса имеют приоритет по сравнению с параметрами query. Так же не будем перезаписывать поля из возвращаемого значения контроллера, оставляя возможность обработать параметры в контроллере вручную.

Подключим наш интерсептор на обработчики запросов страниц:

// ./src/server/app.controller.ts
import { UseInterceptors } from '@nestjs/common';
import { ParamsInterceptor } from './params.interceptor';

// ...

@Get('/')
@Render('index')
@UseInterceptors(ParamsInterceptor)
public home() {
    return {};
}

@Get(':id')
@Render('[id]')
@UseInterceptors(ParamsInterceptor)
public blogPost() {
    return {};
}

Важно помнить, что названия переменных в адресе должны совпадать в nest и NEXT.js. Иными словами, названия переменных в декораторах @Get() и @Render() должны совпадать. На обработчики API, разумеется, вешать этот интерсептор не требуется - мы не хотим, чтобы в возвращаемый JSON попадали параметры запроса.

Хорошим паттерном при разработке nest-next будет разделять контроллеры страниц и API - тогда можно будет повесить декоратор @UseInterceptors() прямо на весь класс контроллера. В рамках данной статьи для простоты примера контроллеры не были разделены.

Проверим работу интерсептора в браузере: вновь обновим страницу - интерсептор успешно работает.

Заключение

Уже сейчас приложение позволяет удовлетворить большинство потребностей при разработки простого вебсайта. Но есть еще несколько способов выжать пользу из nest-next, а также ряд нюансов, которые могут встретиться, особенно в энтерпрайзе. Про них читайте во второй части.

Надеюсь, что данная статья помогла желающим попробовать эти фреймворки вместе войти в разработку с максимальной эффективностью, даже несмотря на почти полное отсутствие официальной документации по nest-next.