Разрабатываем шаблон React + Express + TypeScript приложения

Привет, друзья!

В этой статье я хочу показать вам, как создать шаблон React.js + Express.js + TypeScript приложения.

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

• React — далеко не идеальный, но лучший на сегодняшний день фреймворк для фронтенда (или, согласно официальной документации, "для создания пользовательских интерфейсов");
• Express — несмотря на наличие большого количества альтернативных решений, по-прежнему лучший Node.js-фреймворк для разработки веб-серверов;
• TypeScript — система типов для JavaScript (и еще кое-что), фактический стандарт современной веб-разработки.

Исходный код проекта.

Если вам это интересно, прошу под кат.

Здесь вы найдете шпаргалку по Express API, а здесь — Карманную книгу по TypeScript в формате PWA.

Несмотря на то, что в мире сборщиков модулей доминирующее положение по-прежнему занимает Webpack, для сборки React-приложения, мы будем использовать Snowpack. Он не такой кастомизируемый, зато проще в настройке и быстрее как при запуске и перезапуске сервера для разработки, так и при сборке проекта.

Для установки зависимостей и выполнения команд я буду использовать Yarn. Установить его можно так:

npm i -g yarn

Наши сервисы (имеется в виду клиент и сервер) будут полностью автономными, но, вместе с тем, они будут иметь доступ к общим типам.

Функционал нашего приложения будет следующим:

• клиент может отправить серверу либо неправильное сообщение, либо правильное;
• сервер проверяет сообщение, полученное от клиента, и если оно правильное, отправляет приветствие в ответ;
• если сообщение от клиента неправильное, сервер возвращает сообщение об ошибке.

Структурно сообщение будет состоять из заголовка (title) и тела (body). Синоним типа (type alias) сообщения будет общим для клиента и сервера.

Рекомендую вкратце ознакомиться с флагами tsc (CLI для сборки TS-проектов) и настройками tsconfig.json.

Подготовка и настройка проекта

Создаем новую директорию, переходим в нее и инициализируем Node.js-проект:

# ret - react + express + typescript
mkdir ret-template
cd ret-template # cd !$

# -y | --yes - пропускаем вопросы о структуре и назначении проекта
# -p | --private - частный/закрытый проект (не для публикации в реестре npm, не является библиотекой)
yarn init -yp

На верхнем уровне нам потребуется две зависимости:

yarn add concurrently
# -D | --save-dev - зависимость для разработки
yarn add -D typescript

• concurrently — утилита, позволяющая одновременно выполнять несколько команд, определенных в package.json
• typescript — компилятор TypeScript

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

Создаем директорию shared, в которой будут храниться общие типы, а также файлы index.d.ts и tsconfig.json:

mkdir shared
cd shared

touch index.d.ts
touch tsconfig.json

Файлы с расширением d.ts — это так называемые файлы деклараций. Их основное отличие от обычных TS-файлов (с расширением ts) состоит в том, что декларации могут содержать только объявления типов (но не выполняемый код), и не компилируются в JS. Если мы создадим файл types.ts, то после компиляции получим файл types.js с export {} внутри. Нам это ни к чему.

Наличие файла tsconfig.json в директории сообщает компилятору, что он имеет дело с TS-проектом.

Определяем общий синоним типа сообщения в index.d.ts:

export type Message = {
 title: string
 body: string
}

Типы в декларациях часто объявляются с помощью ключевого слова declare, но в нашем случае это не имеет принципиального значения.

Определяем единственную настройку в tsconfig.json:

{
 "compilerOptions": {
   "composite": true
 }
}

Эта настройка сообщает TypeScript, что данный проект является частью другого проекта.

Создаем файл .gitignore следующего содержания:

node_modules
# настройки, вместо переменных среды окружения (.env)
config
# директория сборки
build
yarn-error.log*

.snowpack
# mac
.DS_Store

Осталось определить команды для запуска проекта в режиме для разработки и производственном режиме. Режим для разработки предполагает запуск 2 серверов для разработки: одного для клиента и еще одного для сервера. Производственный режим предполагает сборку клиента, сборку сервера и запуск сервера (сборка клиента будет обслуживаться сервером в качестве директории со статическими файлами). Поэтому для определения названных команд придется сначала разобраться с клиентом и сервером.

Клиент

Создаем шаблон React + TypeScript-приложения с помощью create-snowpack-app:

# client - название проекта
# --template @snowpack/app-template-react-typescript - название используемого шаблона
# --use-yarn - использовать yarn вместо npm для установки зависимостей
yarn create snowpack-app client --template @snowpack/app-template-react-typescript --use-yarn

Переходим в созданную директорию (cd client) и приводим ее к такой структуре:

- public
 - index.html
 - favicon.ico
- src
 - api
   - index.ts
 - config
   - index.ts
 - App.scss
 - App.tsx
 - index.tsx
- types
 - static.d.ts
- .prettierrc
- package.json
- snowpack.config.mjs
- tsconfig.json

Отредактируем несколько файлов. Начнем с .prettierrc:

{
 "singleQuote": true,
 "trailingComma": "none",
 "jsxSingleQuote": true,
 "semi": false
}

Разбираемся с зависимостями в package.json:

{
 "scripts": {
   "start": "snowpack dev",
   "build": "snowpack build",
   "format": "prettier --write \"src/**/*.{js,jsx,ts,tsx}\"",
   "lint": "prettier --check \"src/**/*.{js,jsx,ts,tsx}\""
 },
 "dependencies": {
   "react": "^17.0.2",
   "react-dom": "^17.0.2"
 },
 "devDependencies": {
   "@snowpack/plugin-react-refresh": "^2.5.0",
   "@snowpack/plugin-sass": "^1.4.0",
   "@snowpack/plugin-typescript": "^1.2.1",
   "@types/react": "^17.0.4",
   "@types/react-dom": "^17.0.3",
   "@types/snowpack-env": "^2.3.4",
   "prettier": "^2.2.1",
   "snowpack": "^3.3.7",
   "typescript": "^4.5.2"
 }
}

Выполняем команду yarn для переустановки зависимостей.

Редактируем настройки в tsconfig.json:

{
 "compilerOptions": {
   "allowJs": true,
   "esModuleInterop": true,
   "forceConsistentCasingInFileNames": true,
   "jsx": "preserve",
   "module": "esnext",
   "moduleResolution": "node",
   "noEmit": true,
   "resolveJsonModule": true,
   "skipLibCheck": true,
   "strict": true
 },
 "include": [
   "src",
   "types"
 ],
 "references": [
   {
     "path": "../shared"
   }
 ]
}

Здесь:

• "noEmit": true означает, что TS в проекте используется только для проверки типов (type checking). Это объясняется тем, что компиляция кода в JS выполняется snowpack;
• этим же объясняется настройка "jsx": "preserve", которая означает, что TS оставляет JSX как есть;
• этим же объясняется отсутствие настройки target (эта настройка содержится в snowpack.config.mjs);
• references позволяет указать ссылку на другой TS-проект. В нашем случае этим "проектом" является директория shared с общим типом сообщения.

Редактируем настройки в snowpack.config.mjs:

/** @type {import("snowpack").SnowpackUserConfig } */
export default {
 mount: {
   public: { url: '/', static: true },
   src: { url: '/dist' }
 },
 plugins: [
   '@snowpack/plugin-react-refresh',
   // здесь был плагин для переменных среды окружения,
   // но с TS они работают очень плохо

   // добавляем плагин для sass, опционально (можете использовать чистый CSS)
   '@snowpack/plugin-sass',
   [
     '@snowpack/plugin-typescript',
     {
       ...(process.versions.pnp ? { tsc: 'yarn pnpify tsc' } : {})
     }
   ]
 ],
 // оптимизация сборки для продакшна
 optimize: {
   bundle: true,
   minify: true,
   treeshake: true,
   // компиляция TS в JS двухлетней давности
   target: 'es2019'
 },
 // удаление директории со старой сборкой перед созданием новой сборки
 // может негативно сказаться на производительности в больших проектах
 buildOptions: {
   clean: true
 }
}

Определяем адрес сервера в файле с настройками (config/index.ts):

export const SERVER_URI = 'http://localhost:4000/api'

Определяем API для клиента в файле api/index.ts:

// адрес сервера
import { SERVER_URI } from '../config'
// общий тип сообщения
import { Message } from '../../../shared'

// общие настройки запроса
const commonOptions = {
 method: 'POST',
 headers: {
   'Content-Type': 'application/json'
 }
}

// функция отправки неправильного сообщения
const sendWrongMessage = async () => {
 const options = {
   ...commonOptions,
   body: JSON.stringify({
     title: 'Message from client',
     // как самонадеянно
     body: 'I know JavaScript'
   })
 }

 try {
   const response = await fetch(SERVER_URI, options)
   if (!response.ok) throw response
   const data = await response.json()
   if (data?.message) {
     // это называется утверждением типа (type assertion)
     // при использовании JSX возможен только такой способ
     return data.message as Message
   }
 } catch (e: any) {
   if (e.status === 400) {
     // сообщение об ошибке
     const data = await e.json()
     throw data
   }
   throw e
 }
}

// функция отправки правильного сообщения
const sendRightMessage = async () => {
 const options = {
   ...commonOptions,
   body: JSON.stringify({
     title: 'Message from client',
     body: 'Hello from client!'
   })
 }

 try {
   const response = await fetch(SERVER_URI, options)
   if (!response.ok) throw response
   const data = await response.json()
   if (data?.message) {
     // !
     return data.message as Message
   }
 } catch (e) {
   throw e
 }
}

export default { sendWrongMessage, sendRightMessage }

Наконец, само приложение (App.tsx):

import './App.scss'
import React, { useState } from 'react'
// API
import messageApi from './api'
// общий тип сообщения
import { Message } from '../../shared'

function App() {
 // состояние сообщения
 const [message, setMessage] = useState<Message | undefined>()
 // состояние ошибки
 const [error, setError] = useState<any>(null)

 // метод для отправки неправильного сообщения
 const sendWrongMessage = () => {
   // обнуляем приветствие от сервера
   setMessage(undefined)

   messageApi.sendWrongMessage().then(setMessage).catch(setError)
 }

 const sendRightMessage = () => {
   // обнуляем сообщение об ошибке
   setError(null)

   messageApi.sendRightMessage().then(setMessage).catch(setError)
 }

 return (
   <>
     <header>
       <h1>React + Express + TypeScript Template</h1>
     </header>
     <main>
       <div>
         <button onClick={sendWrongMessage} className='wrong-message'>
           Send wrong message
         </button>
         <button onClick={sendRightMessage} className='right-message'>
           Send right message
         </button>
         {/* onClick={window.location.reload} не будет работать из-за того, что this потеряет контекст, т.е. window.location */}
         <button onClick={() => window.location.reload()}>Reload window</button>
       </div>
       {/* блок для приветствия от сервера */}
       {message && (
         <div className='message-container'>
           <h2>{message.title}</h2>
           <p>{message.body}</p>
         </div>
       )}
       {/* блок для сообщения об ошибке */}
       {error && <p className='error-message'>{error.message}</p>}
     </main>
     <footer>
       <p>&copy; 2021. Not all rights reserved</p>
     </footer>
   </>
 )
}

export default App

Запускаем клиента в режиме для разработки с помощью команды yarn start.

При попытке отправить любое сообщение, получаем ошибку Failed to fetch.

Логично, ведь у нас еще нет сервера. Давайте это исправим.

Сервер

Создаем новую директорию, переходим в нее и инициализируем Node.js-проект:

mkdir server
cd server

yarn init -yp

Устанавливаем основные зависимости:

yarn add express helmet cors concurrently cross-env

• helmet — утилита для установки HTTP-заголовков, связанных с безопасностью
• cors — утилита для установки HTTP-заголовков, связанных с CORS
• cross-env — утилита для платформонезависимой передачи переменных среды окружения (process.env)

Устанавливаем зависимости для разработки:

yarn add -D typescript nodemon @types/cors @types/express @types/helmet @types/node

• @types — типы для соответствующих утилит и Node.js
• nodemon — утилита для запуска сервера для разработки

Структура сервера:

- src
  - config
    - index.ts
  - middleware
    - verifyAndCreateMessage.ts
  - routes
    - api.routes.ts
  - services
    - api.services.ts
  - types
    - index.d.ts
  - utils
    onError.ts
- index.ts
- package.json
- tsconfig.json

Начнем с редактирования настроек в tsconfig.json:

{
 "compilerOptions": {
   "allowJs": true,
   "esModuleInterop": true,
   "forceConsistentCasingInFileNames": true,
   "module": "esnext",
   "moduleResolution": "node",
   "outDir": "./build",
   "rootDir": "./src",
   "skipLibCheck": true,
   "strict": true,
   "target": "es2019"
 },
 "references": [
   {
     "path": "../shared"
   }
 ]
}

Здесь:

• "target": "es2019" — в отличие от клиента, код сервера компилируется в JS с помощью tsc
• rootDir — корневая директория для предотвращения лишней вложенности сборки
• outDir — название директории сборки
• references — ссылка на общие типы

Код сервера (src/index.ts):

// библиотеки и утилиты
import cors from 'cors'
import express, { json, urlencoded } from 'express'
import helmet from 'helmet'
import { dirname, join } from 'path'
import { fileURLToPath } from 'url'
// настройки
import { developmentConfig, productionConfig } from './config/index.js'
// роуты
import apiRoutes from './routes/api.routes.js'
// обработчик ошибок
import onError from './utils/onError.js'

// путь к текущей директории
const __dirname = dirname(fileURLToPath(import.meta.url))

// определяем режим
const isProduction = process.env.NODE_ENV === 'production'

// выбираем настройки
let config
if (isProduction) {
 config = productionConfig
} else {
 config = developmentConfig
}

// создаем экземпляр приложения
const app = express()

// устанавливаем заголовки, связанные с безопасностью
app.use(helmet())
// устанавливаем заголовки, связанные с CORS
app.use(
 cors({
   // сервер будет обрабатывать запросы только из разрешенного источника
   origin: config.allowedOrigin
 })
)
// преобразование тела запроса из JSON в обычный объект
app.use(json())
// разбор параметров строки запроса
app.use(urlencoded({ extended: true }))
// если сервер запущен в производственном режиме,
// сборка клиента обслуживается в качестве директории со статическими файлами
if (isProduction) {
 app.use(express.static(join(__dirname, '../../client/build')))
}

// роуты
app.use('/api', apiRoutes)
// роут not found
app.use('*', (req, res) => {
 res.status(404).json({ message: 'Page not found' })
})
// обработчик ошибок
app.use(onError)

// запуск сервера
app.listen(config.port, () => {
 console.log('🚀 Server ready to handle requests')
})

Обратите внимание: импортируемые файлы имеют расширение js, а не ts.

Взглянем на типы (types/index.d.ts):

import { Request, Response, NextFunction } from 'express'

export type Route = (req: Request, res: Response, next: NextFunction) => void

И на настройки (config/index.ts):

export const developmentConfig = {
 port: 4000,
 allowedOrigin: 'http://localhost:8080'
}

export const productionConfig = {
 port: 4000,
 allowedOrigin: 'http://localhost:4000'
}

Утилита (utils/onError.ts):

import { ErrorRequestHandler } from 'express'

const onError: ErrorRequestHandler = (err, req, res, next) => {
 console.log(err)
 const status = err.status || 500
 const message = err.message || 'Something went wrong. Try again later'
 res.status(status).json({ message })
}

export default onError

Роутер (routes/api.routes.ts):

import { Router } from 'express'
// посредник, промежуточный слой
import { verifyAndCreateMessage } from '../middleware/verifyAndCreateMessage.js'
// сервис
import { sendMessage } from '../services/api.services.js'

const router = Router()

router.post('/', verifyAndCreateMessage, sendMessage)

export default router

Посредник (middleware/verifyAndCreateMessage.ts):

// локальный тип
import { Route } from '../types'
// глобальный тип
import { Message } from '../../../shared'

export const verifyAndCreateMessage: Route = (req, res, next) => {
 // извлекаем сообщение из тела запроса
 // утверждение типа, альтернатива as Message
 const message = <Message>req.body
 // если сообщение отсутствует
 if (!message) {
   return res.status(400).json({ message: 'Message must be provided' })
 }
 // если тело сообщения включает слово "know"
 if (message.body.includes('know')) {
   // возвращаем сообщение об ошибке
   return res.status(400).json({ message: 'Nobody knows JavaScript' })
 }
 // создаем и записываем сообщение в res.locals
 res.locals.message = {
   title: 'Message from server',
   body: 'Hello from server!'
 }
 // передаем управление сервису
 next()
}

Сервис (services/api.services.ts):

// локальный тип
import { Route } from '../types'

export const sendMessage: Route = (req, res, next) => {
 try {
   // извлекаем сообщение из res.locals
   const { message } = res.locals
   if (message) {
     res.status(200).json({ message })
   } else {
     res
       .status(404)
       .json({ message: 'There is no message for you, my friend' })
   }
 } catch (e) {
   next(e)
 }
}

В package.json нам необходимо определить 3 вещи: основной файл сервера, тип кода сервера и команды для запуска сервера в режиме для разработки и производственном режиме. Основной файл и тип:

"main": "build/index.js",
"type": "module",

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

"scripts": {
 "ts:watch": "tsc -w",
 "node:dev": "cross-env NODE_ENV=development nodemon",
 "start": "concurrently \"yarn ts:watch\" \"yarn node:dev\"",
}

tsc означает сборку проекта — компиляцию TS в JS. Сборка проекта приводит к генерации директории, указанной в outDir, т.е. build. Флаг -w или --watch означает наблюдение за изменениями файлов, находящихся в корневой директории проекта, указанной в rootDir, т.е. src.

Для одновременного выполнения команд ts:watch и node:dev используется concurrently (обратите внимание на экранирование (\"), в JSON можно использовать только двойные кавычки). Вообще, для одновременного выполнения команд предназначен синтаксис ts:watch & node:dev, но это не работает в Windows.

Команда для запуска сервера в производственном режиме:

"scripts": {
 ...,
 "build": "tsc --build && cross-env NODE_ENV=production node build/index.js"
}

Флаг --build предназначен для выполнения инкрементальной сборки. Это означает, что повторно собираются только модифицированные файлы, что повышает скорость повторной сборки. && означает последовательное выполнение команд. Для начала выполнения последующей команды необходимо завершение выполнения предыдущей команды. Поэтому при выполнении tsc -w && nodemon, например, выполнение команды nodemon никогда не начнется.

Обратите внимание: в данном случае расположение основного файла сервера должно быть определено в явном виде как node build/index.js.

Проверка работоспособности

Поднимаемся на верхний уровень (ret-template) и определяем команды для запуска серверов в package.json:

"scripts": {
 "start": "concurrently \"yarn --cwd client start\" \"yarn --cwd server start\"",
 "build": "yarn --cwd client build && yarn --cwd server build"
}

Флаг --cwd означает текущую рабочую директорию (current working directory). yarn --cwd client start, например, означает выполнение команды start, определенной в package.json, находящемся в директории client.

Выполняем команду yarn start.

По адресу http://localhost:8080 автоматически открывается новая вкладка в браузере.

Отправляем неправильное сообщение.

Получаем сообщение об ошибке.

Отправляем правильное сообщение.

Получаем приветствие от сервера.

Изменение любого файла в директории client или server, кроме файлов с настройками snowpack и tsc, приводит к пересборке проекта.

Останавливаем сервера для разработки (Ctrl + C или Cmd + C).

Выполняем команду yarn build.

Получаем сообщения от snowpack об успешной сборке клиента (то, что import.meta будет пустой, нас не интересует), а также о готовности сервера обрабатывать запросы.

Переходим по адресу http://localhost:4000. Видим полностью работоспособное приложение, обслуживаемое сервером.

Пожалуй, это все, чем я хотел поделиться с вами в этой статье.

Благодарю за внимание и happy coding!

---