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

npm install - устанавливаем зависимости
npm run start:dev или npm run start:dev:vite - запуск сервера + frontend проекта в dev режиме

---

Скрипты

• npm run start - Запуск frontend проекта на webpack dev index
• npm run start:vite - Запуск frontend проекта на vite
• npm run start:dev - Запуск frontend проекта на webpack dev index + backend
• npm run start:dev:vite - Запуск frontend проекта на vite + backend
• npm run start:dev:index - Запуск backend сервера
• npm run build:prod - Сборка в prod режиме
• npm run build:dev - Сборка в dev режиме (не минимизирован)
• npm run lint:ts - Проверка ts файлов линтером
• npm run lint:ts:fix - Исправление ts файлов линтером
• npm run lint:scss - Проверка scss файлов style линтером
• npm run lint:scss:fix - Исправление scss файлов style линтером
• npm run test:unit - Запуск unit тестов с jest
• npm run test:ui - Запуск скриншотных тестов с loki
• npm run test:ui:ok - Подтверждение новых скриншотов
• npm run test:ui:ci - Запуск скриншотных тестов в CI
• npm run test:ui:report - Генерация полного отчета для скриншотных тестов
• npm run test:ui:json - Генерация json отчета для скриншотных тестов
• npm run test:ui:html - Генерация HTML отчета для скриншотных тестов
• npm run storybook - запуск Storybook
• npm run storybook:build - Сборка storybook билда
• npm run prepare - прекоммит хуки
• npm run generate:slice - Скрипт для генерации FSD слайсов
• npm run postinstall - Очистка кэша node_modules
• npm run remove-feature - Удаление кода по фича-флагам

---

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

Проект разработан с использованием методологии "Feature Sliced Design" (Дизайн по функциональным частям). Эта архитектурная методология является модульным подходом к организации кода, который стремится упростить управление состоянием, улучшить переиспользование кода и обеспечить четкое разделение функциональных возможностей.

Преимущества методологии "Feature Sliced Design":

• Модульность: Код разделяется на логические функциональные части (фичи), что делает его более организованным и легко масштабируемым. Каждая фича содержит все связанные компоненты, стили, действия и редьюсеры.

• Легкость поддержки: Фичи могут быть легко добавлены, удалены или модифицированы без необходимости переписывания большой части кода. Это упрощает поддержку проекта на протяжении всего его жизненного цикла.

• Улучшенное управление состоянием: Каждая фича может иметь собственное независимое состояние, что способствует упрощению управления состоянием приложения и предотвращает появление сложных конфликтов в данных.

• Единообразие Код распределяется согласно области влияния (слой), предметной области (слайс) и техническому назначению (сегмент). Благодаря этому архитектура стандартизируется и становится более простой для ознакомления.

• Контролируемое переиспользование логики Каждый компонент архитектуры имеет свое назначение и предсказуемый список зависимостей. Благодаря этому сохраняется баланс между соблюдением принципа DRY и возможностью адаптировать модуль под разные цели. Компоненты и логика, созданные для одной фичи, могут быть повторно использованы в других фичах. Это способствует устранению дублирования кода и повышению эффективности разработки.

• Устойчивость к изменениям и рефакторингу Один модуль не может использовать другой модуль, расположенный на том же слое или на слоях выше. Благодаря этому приложение можно изолированно модифицировать под новые требования без непредвиденных последствий.

• Ориентированность на потребности бизнеса и пользователей Разбиение приложения по бизнес-доменам помогает глубже понимать, структурировать и находить фичи проекта.

Подробнее об архитектуре - документация FSD

---

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

В проекте используется библиотека i18next для работы с переводами. Файлы с переводами хранятся в public/locales.

Для комфортной работы рекомендуем установить плагин для webstorm/vscode

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

---

Тесты

В проекте используются 4 вида тестов:

1. Обычные unit тесты на jest - npm run test:unit
2. Тесты на компоненты с React testing library -npm run test:unit
3. Скриншотное тестирование с loki npm run test:ui
4. e2e тестирование с Cypress npm run test:e2e

Подробнее о тестах - документация тестирование

---

Линтинг

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

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

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

Запуск линтеров

• npm run lint:ts - Проверка ts файлов линтером
• npm run lint:ts:fix - Исправление ts файлов линтером
• npm run lint:scss - Проверка scss файлов style линтером
• npm run lint:scss:fix - Исправление scss файлов style линтером

---

Storybook

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

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

Запустить сторибук можно командой:

• npm run storybook

Подробнее о Storybook

Пример:

import React from 'react';
import { ComponentStory, ComponentMeta } from '@storybook/react';

import { ThemeDecorator } from '@/shared/config/storybook/ThemeDecorator/ThemeDecorator';
import { Button, ButtonSize, ButtonTheme } from './Button';
import { Theme } from '@/shared/const/theme';

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

const Template: ComponentStory<typeof Button> = (args) => <Button {...args} />;

export const Primary = Template.bind({});
Primary.args = {
  children: 'Text',
};

export const Clear = Template.bind({});
Clear.args = {
  children: 'Text',
  theme: ButtonTheme.CLEAR,
};

---

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

Для разработки проект содержит 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 в него передается объект с опциями { name: название фича-флага, on: функция которая отработает после включения фича флага, off: функция которая отработает после выключения фича флага }

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

1. Название удаляемого фича-флага
2. Состояние (on/off)

---

Описание по слоям

Общее (shared)

Переиспользуемый код, не имеющий отношения к специфике приложения

• api
• assets
  • icons: папка с необходимыми для приложения иконками
  • tests: папка с иконкой для модуля тестов
• config
  • i18n: настроки плагина для многоязычности i18n
  • storybook - декораторы
• const
  • localstorage.ts: разные константы localstorage
  • router.ts: настройки маршрутизации
  • theme.ts: темы приложения
• layouts
• lib
  • classNames: Функция объединяет имена классов в одну строку и возвращает результат
  • components: Функции для оптимизации работы компонентов
  • context
  • features: функционал касающийся фича-флагов
  • hooks: различные хуки
  • render: функции связанные с рендером
  • router: функции связанные с роутингом
  • store: работа со стором
  • tests: вспомогательные функции для тестов
  • url: работа с url-ами
• types: определение типов
• ui: UI компоненты которые используются во всем приложении

Сущности (entities)

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

Фичи (features)

• addCommentForm
• articleEditForm
• articlePageGreeting
• articleRating
• articleRecommendationsList
• articleSortSelector
• articleViewSelector
• articleTypeTabs
• authByUsername
• avatarDropdown
• editableProfileCard
• LangSwitcher
• notificationButton
• scrollSave
• scrollToTopButton
• profileRating
• ThemeSwitcher
• uiDesignSwitcher

Виджеты (Widgets)

ArticleAdditionalInfo ArticlesFilters Navbar Page PageError PageLoader ScrollToolbar Sidebar

Страницы (Pages)

• AboutPage
• AdminPanelPage
• ArticleDetailsPage
• ArticleEditPage
• ArticlesPage
• ForbiddenPage
• MainPage
• NotFoundPage
• ProfilePage
• SettingsPage

Приложение (App)

• lib
• providers
• styles
• types
• App.tsx