simolex / ut-blog-project

Запуск проекта

1. Установка зависимостей

npm install             # Установка зависимостей

2. Запуск backend + frontend частей проекта

npm run start:dev       # Webpack dev server + json server
                        # или
npm run start:dev:vite  # Vite + json server

---

Скрипты

Скрипты исполняемые в консоли среды разработки проекта

Скрипты для режима разработки ( Development )

Скрипт	Описание
npm run start	Запуск frontend проекта на Webpack dev server
npm run start:vite	Запуск frontend проекта на Vite
npm run build:dev	Сборка frontend проекта в режиме разработки
npm run build:dev:analize	Сборка проекта в режиме разработки с включенным плагином Bundle analyzer1
npm run json:server	Запуск backend проекта на Json server'e
npm run start:dev	Сборка frontend + backend проекта в режиме разработки на Webpack dev server
npm run start:dev:vite	Сборка frontend + backend проекта в режиме разработки на Vite
npm run lint:ts	Проверка файлов *.ts, *.tsx линтером
npm run lint:ts:fix	Исправление файлов *.ts, *.tsx линтером
npm run lint:scss	Проверка файлов *.scss линтером
npm run lint:scss:fix	Исправление файлов *.scss линтером
npm run test:unit	Запуск unit - тестов в Jest2
npm run test:ui	Запуск скриншотных тестов в Loki3
npm run test:ui:ok	Сохранение новых и измененных тестов в Loki3
npm run test:ui:ci	Запуск скриншотных тестов в CI
npm run test:ui:update	Обновление новых и измененных тестов в Loki3
npm run test:ui:json	Генерация Json отчета для скриншотных тестов
npm run test:ui:html	Генерация HTML отчета для скриншотных тестов
npm run test:ui:report	Генерация полного (HTML+JSON) отчета для скриншотных тестов
npm run storybook	Запуск Storybook
npm run storybook:build	Генерации статичной сборки Storybook
npm run prepare	Прекоммит хуки
npm run generate:slice	Скрипт для генерации FSD слайсов
npm run update:imports	Скрит для перезаписи абсолютных путей импортов на пути с алиасом '@'

Скрипты для финальной сборки ( Production )

Скрипт	Описание
npm run build:prod	Сборка проекта в режиме финальной сборки
npm run build:prod:analize	Сборка проекта в режиме финальной сборки с включенным плагином Bundle analyzer

---

Архитектура проекта

Проект написан в соответствии с методологией Features sliced design⁴

Документация: Features sliced design

---

Работа с переводами

В проекте используется библиотека react-i18next⁵ для работы с переводами. Файлы переводов хранятся в папке public/locales, в формате JSON. Языковые фразы и термины представлены в виде пары Ключ: Значение

• Ключ - смысловые фразы, латинскими символами в формате snakecase
• Значение - перевод фразы на соответствующем языке, ограниченное кавычками

Документация: react-i18next

---

Тестирование

Реализовано тестирование проекта 4-я видами тестов.

	Вид теста	Запуск
1	Функциональные unit-тесты на Jest2	npm run test:unit
2	Компонентные тесты с React testing library3	npm run test:unit
3	Скриншотные тесты с Loki6	npm run test:ui
4	e2e тестирование с Cypress7	npm run test:e2e

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

---

Линтинг

В проекте используется eslint⁸ для проверки typescript кода и stylelint для проверки файлов со стилями.

Также для строгого контроля главных архитектурных принципов используется собственный eslint plugin eslint-plugin-path-checker⁹,

который содержит 3 правила

1. path-checker - запрещает использовать абсолютные импорты в рамках одного модуля
2. layer-imports - проверяет корректность использования слоев с точки зрения FSD (например widgets нельзя использовать в features и entitites)
3. public-api-imports - разрешает импорт из других модулей только из public api. Имеет auto fix

	Скрипты линтера	Запуск
1	Проверка ts файлов линтером	npm run lint:ts
2	Исправление ts файлов линтером	npm run lint:ts:fix
3	Проверка scss файлов style линтером	npm run lint:scss
4	Исправление scss файлов style линтером	npm run lint:scss:fix

---

Storybook

В проекте для каждого компонента описываются стори-кейсы. Запросы на сервер мокаются с помощью storybook-addon-mock.

Файл со сторикейсами создает рядом с компонентом с расширением *.stories.tsx

	Скрипты	Запуск
1	Запустить оболочку Storybook	npm run storybook

Подробнее о Storybook

Пример:

import { ComponentStory, ComponentMeta } from '@storybook/react';
import { Text } from '@/shared/ui/Text';
import { Theme } from '@/shared/const/theme';
import { ThemeDecorator } from '@/shared/config/storybook/ThemeDecorator/ThemeDecorator';
import { Card } from './Card';

export default {
    title: 'shared/Card',
    component: Card,
    argTypes: {
        backgroundColor: { control: 'color' },
    },
} as ComponentMeta<typeof Card>;

const Template: ComponentStory<typeof Card> = (props) => <Card {...props} />;

export const Normal = Template.bind({});
Normal.args = {
    children: <Text title="Title" text="text text" />,
};

export const NormalDark = Template.bind({});
NormalDark.args = { children: <Text title="Title" text="text text" /> };
NormalDark.decorators = [ThemeDecorator(Theme.DARK)];

---

Конфигурация проекта

Для разработки проект содержит 2 конфигурации:

1. Webpack - ./config/build
2. Vite - vite.config.ts

Оба сборщика адаптированы под основные фичи приложения.

Вся конфигурация хранится в /config

• /config/babel - babel
• /config/build - конфигурация webpack
• /config/jest - конфигурация тестовой среды
• /config/storybook - конфигурация сторибука

В папке scripts находятся различные скрипты для рефакторинга\упрощения написания кода\генерации отчетов и тд.

---

CI pipeline и pre commit хуки

Конфигурация github actions находится в /.github/workflows. В CI прогоняются все виды тестов, сборка проекта и сторибука, линтинг.

В прекоммит хуках проверяем проект линтерами, конфиг в /.husky

---

Работа с данными

Взаимодействие с данными осуществляется с помощью Redux Toolkit¹⁰. По возможности переиспользуемые сущности необходимо нормализовать с помощью EntityAdapter

Запросы на сервер отправляются с помощью RTK Query¹¹

Для асинхронного подключения редюсеров (чтобы не тянуть их в общий бандл) используется DynamicModuleLoader

---

Работа с feature-flags

Реализовано использование feature flags с помощью хеллпер функции toggleFeatures и компонентна ToggleFeatures

В функцию параметром передается следующий объект:

{ name: string , on: ()=>void , off: ()=>void }

toggleFeatures ({
    name: 'название фича-флага',
    on: ()=>{ Отображается результат этой функции при ВКЛючении фичи },
    off: ()=>{ Отображается результат этой функции при ВЫКЛючении фичи },
})

В компонент пропсами передаются следующие атрибуты:

feature, on, off

<ToggleFeatures
    feature="название фича-флага"
    on={<JSX-элемент при ВКЛючении фичи/>}
    off={<JSX-элемент при ВЫКЛючении фичи/>}
/>

Для автоматического удаления фичи можно использовать скрипт remove-feature.ts Принимает 2 аргумента:

1. Название удаляемого фича-флага
2. Выбранное состояние (on | off)

---

Сущности (entities)

• Article
• Comment
• Counter
• Country
• Currency
• Notification
• Profile
• Rating
• User

Фичи (features)

• addCommentForm
• articleEditForm
• articleRating
• articleRecommendationsList
• AuthByUsername
• avatarDropdown
• editableProfileCard
• LangSwitcher
• notificationButton
• profileRating
• ThemeSwitcher
• UI

---

Ссылки на документацию

Footnotes

1. Webpack bundle analyzer ↩

2. Jest ↩ ↩²

3. React testing library ↩ ↩² ↩³ ↩⁴

4. Features sliced design ↩

5. react-i18next ↩

6. Loki ↩

7. Cypress ↩

8. eslint ↩

9. Специализированный Линтер плагин simolex-plugin-lint ↩

10. Redux Toolkit (RTK) ↩

11. RTK Query ↩