Algorithms playground

---

Live demo

О проекте

Учебный проект. Визуализация работы некоторых алгоритмов и структур данных. Я постарался организовать проект максимально близко к продакшену. Код покрыт тестами, настроены линтеры и CI.

Дизайн макет, но я изменил цветовую схему на более строгую.

Сайт корректно отображается на всех размерах экранов.

Технические решения

Сборка

Проект собирается с помощью vite, потому что CRA уже не рекомендовался для создания нового проекта React. Запуск с помощью докера

Архитектура

• Использовал относительо новую, но набирающую популярность, методологию FSD для организации кода фронтенда.

• Использую новый React Router v6 и ленивую загрузку роутов.

Pre-commit actions

1. ESLint и Stylelint проверяют TS/SCSS staged файлы.
2. Prettier автоматически форматирует код.
3. Запускаются все тесты jest
4. Commitlint проверяет коммит на соответствие Conventional Commits. Можно пошагово создать корректное сообщение коммита с помощь cli commitizen: скрипт yarn cz
   
   

Если любой из этапов не проходит, коздание коммита отменяется. Это минизирует попадание ошибочного кода в коммит и унифицирует сообщения коммитов.

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

Код покрыт тестами:

• юнит-тесты jest для проверки работы алгоритмов.
• e2e тесты cypress для проверки правильной визуализации всех страниц.
• тесты компонентов React с помощью Cypress Component Testing. Отностиельно новый инструмент для разработки и тестирования компонентов.

Настроена интеграция с cypress cloud для визуализации и мониторинга результатов тестирования.

CI

1. Настроил github workflow для запуска всех тестов при пуше в любую ветку, кроме main. Разделил стадию билда от тестов, чтобы оптимизировать прогон тестов.
   
   
   
   
2. Защитил ветку main от прямого пуша. Обновить ветку main можно только через PR. Причём должны обязательно успешно завершиться все actions по тестированию в рабочей ветке. Таким образом нерабочий код не может (но это не точно) попасть в main.
3. Настроил автоматическую публикацию сайта на gh-pages при вливании PR в main.

Tech stack

• React with TS
• SCSS
• Vite bundler
• Jest
• Cypress

Local Development with Docker

git clone git@github.com:gvozdenkov/algoschool.git
cd algoschool
docker compose -f compose.dev.yaml up

# or use Makefile
make run-dev

# open http://localhost:3010

# create new branch and work in it. Merge to main only via PR

Local Development

use node 18 and above

git clone git@github.com:gvozdenkov/algoschool.git
cd algoschool
yarn

# or npm install
yarn dev
# or npm run dev

# open http://localhost:5173

script	Description
dev	Запускает vite dev server без cypress
dev-ct	Запускает vite dev server и cypress open --component для разработки и тестирования компонентов
dev-e2e	Запускает vite dev server и cypress open --e2e для e2e тестирования
build	билд проекта
lint	проверки eslint
typecheck	проверка typescript компилятором tsc
prettier:write	исправляет ошибки форматирования
prettier:check	проверяет ошибки форматирования (используется в CI перед тестами cypress.yaml)
stylelint:fix	stylelint исправляет .scss стили
test:cy	запуск всех тестов cypress
test:jest	запуск всех тестов jest
cz	cli утилита для созадния коммита по рекомендациям Conventional Commits

Дальнейшие планы

1. Добавить линтер для методологии FSD
2. Перевезти проект на Remix.run фреймворк. Лучше CEO, быстрее индексация.
3. Внедрить Storybook для разработки и тестирования компонентов в изоляции. Уже добавлены зависимости и скрипты запуска. Но пока там пусто.

Workflow setup details

Lint staged files

Used husky & lint-staged packages to lint & format staged files only

# .husky/_/pre-commit
yarn lint-staged && yarn test:jest -o

.lintstagedrc.json setup sequential running commands for .js|ts|jsx|tsx files in order of array items

{
  "*.(js|ts|jsx|tsx)": ["yarn prettier:write", "yarn lint"],
  "*.md": "yarn prettier:write"
}

Commit messages

This project is Commitizen friendly. So you can easy create commits in a step by step guide by run:

If you are mannually create commit message it will be linted with commitlint to lint commit messages acording with Conventional Commits.

yarn cz
# or
npm run cz

Commitizen & commitlint setup:

1. Used ligthweight cz-git adapter for commitizen to generate cli interface for yarn cz
2. Setup cz-git with .czrc file
3. Setup commitlint with commitlint.config.ts

"devDependencies": {
  "@commitlint/cli": "^18.4.3",
  "@commitlint/config-conventional": "^18.4.3",
  "@commitlint/format": "^18.4.3",

  "commitizen": "^4.3.0",
  "cz-git": "^1.8.0",
}

Code formating

Used Prettier (exact 2.8.7 version) for formatting and Eslint for linting only. So setup

"devDependencies": {
  "eslint": "^8.53.0",
  "prettier": "2.8.7",
  "eslint-plugin-prettier": "4.2.1",
  "eslint-config-prettier": "^9.0.0",
}

Settup eslint to highlight style errors with prettier:

// .eslintrc.cjs
module.exports = {
  // ...
  extends: [
    'eslint:recommended',
    'plugin:@typescript-eslint/recommended-type-checked',
    // ...
    // prettier must be the last in extends
    'prettier',
  ],
  // ...
  plugins: ['prettier'],
  rules: {
    'prettier/prettier': ['error'],
    // ...
  },
};

Setup CI to check code formating

# cypress.yaml

- run: yarn lint

# only check format, not write
- run: yarn prettier:check

Import order sorting:

Used prettier-plugin-sort-imports package for prettier to format order of imports

//https://chriscoyier.net/2022/08/09/javascript-import-sorting/

// .prettierrc
"importOrder": [
    "react",
    "<THIRD_PARTY_MODULES>",
    "^(#shared/(config|constants|types|hooks|lib)).*$",
    "^(#shared/ui).*$",
    // Any local imports that AREN'T styles.
    "^(\\.|\\.\\.)/(.(?!.(css|scss)))*$",
    // Styles
    ".(css|scss)$"
  ],
  "importOrderSeparation": true,
  "importOrderSortSpecifiers": true,
  "importOrderCaseInsensitive": true,

Stylelint .scss

1. Install:

yarn add -D stylelint stylelint-config-standard-scss stylelint-config-prettier-scss stylelint-config-clean-order

2. Setup stylelint .stylelintrc.json:

{
  "extends": [
    "stylelint-config-standard-scss",
    "stylelint-config-clean-order/error",
    "stylelint-config-prettier-scss"
  ],
  "rules": {
    "selector-class-pattern": "^(?:[a-z][a-z0-9]*)(?:(__|_|-)[a-z0-9]+)*$",
    "scss/at-extend-no-missing-placeholder": null
  }
}

selector-class-pattern to check BEM style names

3. Add script in package.json to lint and autofix fixable issues

+ "stylelint:fix": "stylelint '**/*.scss' --fix",

4. Edit .lintstagedrc.json to automatic fix all fixable style issues in pre-commit acion

{
  "*.(js|ts|jsx|tsx)": ["yarn prettier:write", "yarn lint"],
  "*.md": "yarn prettier:write"
  # suddenly `yarn stylelint:fix` don't work:( it crash lint-staged with empty-commit error
+ "*.{css,scss}": "stylelint '**/*.scss' --fix",
}

5. Setup VS Code settings.json to autofix stylelint issues on save

Install official Stylelint extenstion!

+  "editor.codeActionsOnSave": {
+     "source.fixAll.stylelint": true
+  },
+  "css.validate": false,
+  "scss.validate": false,
+  "less.validate": false,
+  "stylelint.validate": ["css", "less", "postcss", "scss"],
+  "stylelint.config": null, //use settings from .stylelintrc.json