Фронтенд-репозиторий для стажировки

Клонируем репозиторий. После клонирования, необходимо запустить установку npm-пакетов:

npm install

• npm run dev - пример команды для запуска
• dev — запуск конфига для разработки.
• build — сборка всех файлов в папку /build.
• watch — запускает слежение за файлами, так что при изменении они автоматически пересобираются.
• page:create — создание новой страницы.
• page:remove — удаление существующей страницы.
• component:create — создание нового компонента.
• component:remove — удаление существующего компонента.
• fonts:refresh — автоматическое подключение шрифтов из папки src/fonts в файл src/common/scss/fonts.scss.
• lintfix — автоисправление js-файла с помощью линтера.

only-template
├── scripts
│   ├── components
│   │   ├── templates
│   │   │   └── component.jstpl
│   │   ├── create.js
│   │   └── remove.js
│   ├── page
│   │   ├── templates
│   │   │   ├── page.jstpl
│   │   │   └── page.pugtpl
│   │   ├── create.js
│   │   └── remove.js
│   └── refresh-fonts.js
├── src
│   ├── common
│   │   ├── css
│   │   │   └── common.css
│   │   ├── icons
│   │   │   └── .keep
│   │   ├── images
│   │   │   └── .keep
│   │   ├── js
│   │   │   ├── common.js
│   │   │   ├── variables.js
│   │   └── pug
│   │   │   ├── helpers.pug
│   │   │   └── mixins.pug
│   │   └── scss
│   │   │   ├── colors.scss
│   │   │   ├── common.scss
│   │   │   ├── custom.scss
│   │   │   ├── fonts.scss
│   │   │   ├── functions.scss
│   │   │   ├── typography.scss
│   │   │   ├── utils.scss
│   │   │   └── variables.scss
│   ├── components
│   │   ├── components.json
│   │   └── component-name
│   │   │   ├── animations.js
│   │   │   ├── component-name.js
│   │   │   ├── component-name.pug
│   │   │   └── component-name.scss
│   ├── data
│   │   └── dataName.json
│   ├── fonts
│   │   └── fonts-name
│   │   │   ├── fonts-name.ttf
│   │   │   ├── fonts-name.woff
│   │   │   └── fonts-name.woff2
│   ├── layout
│   │   ├── layout.pug
│   │   └── layout.scss
│   ├── pages
│   │   └── page-name
│   │   │   ├── images
│   │   │   │   └── .keep
│   │   │   ├── animations.js
│   │   │   ├── page-name.js
│   │   │   ├── page-name.pug
│   │   │   └── page-name.scss
│   └── vendor
│   │   └── .keep
├── .babelrc
├── .eslintrc.json
├── .gitignore
├── package.json
├── pages.json
├── postcss.config.js
└── webpack.config.js

В папке scripts хранятся скрипты для автоматизации некоторых задач (создание/удаление страниц и компонентов, подключение шрифтов)

В папке src хранятся исходные файлы проекта.

Папка src/common/css предназначена для хранения стилей на чистом css.

Файл src/common/css/common.css предназначен для хранения основных стилей сайта на чистом css.

При сборке данный файл сохраняется в build/css/common[hash:8].css

Папка src/common/icons предназначена для хранения векторных иконок.

При сборке файлы из данной папки объединяются в один спрайт.

Папка src/common/images предназначена для хранения изображений.

При сборке файлы из данной папки попадают в build/images.

Папка src/common/js предназначена для хранения скриптов.

Файл src/common/js/common.js предназначен для хранения основной логики сайта.

При сборке данный файл попадает в build/js/vendors[hash:8].js.

Папка src/common/pug предназначена для хранения шаблонов.

Файл src/common/pug/helpers.pug предназначен для хранения готовых функций-помощников..

Файл src/common/pug/mixins.pug предназначен для хранения Pug-миксин.

Папка src/common/scss предназначена для хранения стилей.

Файл src/common/scss/colors.scss предназначен для хранения всех цветов проекта.

Файл src/common/scss/common.scss предназначен для подключения основных стилей сайта, стилей компонентов и страниц.

При сборке данный файл преобразуется в CSS и сохраняется в build/css/common[hash:8].css.

Файл src/common/scss/custom.scss предназначен для подключения стилей сторонней библиотеки Bootstrap.

Файл src/common/scss/fonts.scss предназначен для подключения шрифтов.

Файл src/common/scss/functions.scss предназначен для хранения SCSS-функций.

Файл src/common/scss/typography.scss предназначен для хранения текстовых SCSS-миксин и классов.

Файл src/common/scss/utils.scss предназначен для хранения поведенческих SCSS-миксин и классов.

Файл src/common/scss/variables.scss предназначен для хранения SCSS-переменных.

В папке src/components/${componentName} хранятся переиспользуемые изолированные шаблоны компонентов для дальнейшего их подключения на страницах проекта.

src/components/${componentName}/images — изображения для компонента.

src/components/${componentName}/animations.js — анимации компонента.

src/components/${componentName}/${componentName}.js — скрипты компонента.

src/components/${componentName}/${componentName}.pug — pug-шаблон компонента.

src/components/${componentName}/${componentName}.scss — стили компонента.

Папка src/data преднзначена для хранения json-файлов, которые содержат текстовый контент для компонентов. Полезно для сокращения строк кода в pug-шаблонах.

Папка src/fonts предназначена для хранения шрифтов.

При сборке файлы из данной папки попадают в build/fonts.

Папка src/layout предназначена для хранения базового шаблона.

Файл src/layout/layout.scss автоматически подключен в файле src/common/css/common.css

Файл src/layout/layout.pug автоматически подключен в начале шаблона страницы, сгенерируемой с помощью готовой команды page:create

В папке src/pages/${pageName} хранятся шаблоны страниц проекта

src/pages/${pageName}/images — изображения для страницы.

src/pages/${pageName}/animations.js — анимации страницы.

src/pages/${pageName}/${pageName}.js — скрипты страницы.

src/pages/${pageName}/${pageName}.pug — pug-шаблон страницы.

src/pages/${pageName}/${pageName}.scss — стили страницы.

При сборке все Pug-файлы из папки src/pages/${pageName} преобразуются в HTML и сохраняются в build/html.

Папка src/vendor предназначена для хранения сторонних библиотек, которых нет в репозитории npm.

.babelrc — файл настроек JavaScript-транспайлера Babel.

.eslintrc — файл настроек ESLint.

.gitignore — файл настроек Git для игнорирования файлов.

package.json — файл, содержащий базовую информацию о проекте, список требуемых библиотек и автоматизированные задачи

webpack.config.js — файл настроек webpack.

Библиотеки подключаются с помощью npm. При установке следует указывать ключ --save / -P или --save-dev / -D.

Пример:

npm i --save bootstrap
npm i --save-dev webpack

--save указывается для библиотек, код которых попадает в итоговую сборку (папку build) и будет использоваться на сайте.

--save-dev указывается для библиотек, которые используются только для сборки.

После установки необходимо подключить нужные файлы библиотеки:

• скрипты — в src/components/${componentName}/${componentName}.js или src/pages/${pageName}/${pageName}.js.
• стили — в src/common/scss/common.scss.

Полный пример, описывающий установку библиотеки swiper:

1. Установка:

   npm i swiper -P

2. Подключение скриптов в файл src/components/${componentName}/${componentName}.js:

   import Swiper from 'swiper/dist/js/swiper.min';

3. Подключение стилей в файл src/common/scss/common.scss:

   @import '~swiper/dist/css/swiper.min';

Если библиотека отсутствует в npm, либо её нужно модифицировать, то файлы следует скачать и закинуть в папку src/vendor.

Изображения следует хранить в папках src/common/images, src/components/${componentName}/images или src/pages/${pageName}/images.

В сборке содержится Pug-миксин для подключения изображений.
src/common/pug/mixins.pug:

mixin img(args)
 img(
     src='data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7'
 )(data-src=args.path)&attributes(attributes)

Подключение изображения в Pug:

div
    +img({path: './images/image.jpg'})

При сборке подключенные файлы из перечисленных папок копируются в build/images.

only-template
├── build
│   └── images
└── src
    ├── common
    │   └── images
    │
    ├── components
    │   └── component-name
    │       └── images
    │
    └── pages
        └── page-name
            └── images

Оптимизация изображений выполняется автоматически в режимах dev и build с помощью плагина Imagemin.

Принцип работы с SVG-спрайтами:

1. Получаем векторные иконки в формате .svg (экспортируем из Figma). Сохраняем в папку src/common/icons:

   only-template
   └── src
       └── common
           └── icons
               └── only.svg
   

2. SVG sprite loader оптимизирует и объединяет иконки в один спрайт.

   В сборке содержится Pug-миксин для подключения SVG-спрайтов.
   src/common/pug/mixins.pug:

    mixin svg(args)
        svg&attributes(attributes)
            use(xlink:href=`#${args.name}`)

3. Подключаем иконку в Pug:

   div
       +svg({name: 'only'})

   При необходимости иконку можно стилизовать:

   & > svg {
       width: 15px;
       height: 15px;
       fill: $color-1;
   }

   Если цвет заливки или обводки не удается изменить с помощью CSS, то необходимо открыть SVG-файл иконки в редакторе и удалить соответствующие атрибуты (fill, stroke) из кода.

В сборке используется шаблонизатор Pug.

Pug предоставляет множество возможностей, упрощающих работу с шаблонами:

• Переменные.
• Циклы.
• Условия.
• Фильтры.
• Наследование шаблонов.
• Миксины.

Шаблоны страниц размещаются в src/pages/${pageName}, шаблоны компонентов в src/components/${componentsName}, а дополнительные файлы и миксины в src/common/pug:

only-template
└── src
    ├── common
    │   └── pug
    │       ├── helpers.pug
    │       └── mixins.pug
    └── pages
        └── page-name
            └──page-name.pug

За сборку и преобразование Pug в HTML отвечают плагины html-loader и pug-html-loader:

После выполнения сборки в папке build/html появятся HTML-файлы:

only-template
└── build
    └── html
        └── index.html

В качестве базового шаблона используется src/layout/layout.pug.

Пример наследования и использования шаблона:

extends ../../layout/layout

block content
    // Содержимое страницы

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

В сборке используется препроцессор SCSS и PostCSS-плагин Autoprefixer.

Основные стили размещаются в папке src/common/scss, стили страниц в src/pages/${pageName}, стили компонентов в src/components/${componentsName}:

only-template
└── src
    ├── common
    │    └── scss
    │        ├── colors.scss
    │        ├── common.scss
    │        ├── custom.scss
    │        ├── fonts.scss
    │        ├── functions.scss
    │        ├── typography.scss
    │        ├── utils.scss
    │        └── variables.scss
    ├── components
    │    └── component-name
    │        └── component-name.scss
    └── pages
        └── page-name
            └── page-name.scss

После выполнения сборки в папке build/css появится файл common[hash:8].css:

only-template
└── build
    └── css
        └── common[hash:8].css

Для именования классов рекомендуется использовать БЭМ-нотацию.

.block {
    &__element {
        &--modificator {
            // ...
        }
    }
}

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

.is-active {
    // ...
}

.is-current {
    // ...
}

.is-open {
    // ...
}

.is-hidden {
    // ...
}

В файл src/common/scss/variables.scss следует выносить лишь основные переменные:

В файл src/common/scss/colors.scss следует выносить лишь используемые цвета в проекте:

• Пример:

  $color-1: #005741;
  $color-2: #000;
  $color-3: #fff;

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

В файл src/common/scss/typography.scss следует выносить лишь миксины по типографике:

• Пример:

  @mixin font-1 {
    $fhd-base-size: 60px;
    $tablet-base-size: $fhd-base-size * 0.6;
    font-family: Gilroy, sans-serif;
    font-size: calc(#{smooth-value($tablet-base-size / 2, $fhd-base-size / 2, $screen-md-min, $fhd-width, "w")} +
    #{smooth-value($tablet-base-size / 2, $fhd-base-size / 2, $mobile-min-height, $fhd-height, "h")});
  
    @include media-breakpoint-up(fhd) {
        font-size: $fhd-base-size;
    }
    @include media-breakpoint-down(sm) {
        font-size: 38px;
    }
  }

Повторяющиеся участки кода (20-30 строк и более), отличающиеся лишь значениями, следует выносить в отдельные миксины.

В SCSS-коде не должно присутствовать вендорных префиксов. Они автоматически расставляются в процессе сборки.

Неправильно:

input {
    display: -webkit-box;
    display: -ms-flexbox;
    display: flex;
}

Правильно:

input {
    display: flex;
}

Основные скрипты размещаются в папке src/common/js, скрипты страниц в src/pages/${pageName}, скрипты компонентов в src/components/${componentsName}:

only-template
└── src
    ├── common
    │   └── js
    │       ├── barbaInit.js
    │       ├── common.js
    │       ├── commonComponents.js
    │       ├── component.js
    │       ├── helpers.js
    │       ├── inner.js
    │       ├── transitions.js
    │       ├── variables.js
    │       └── views.js
    ├── components
    │    └── component-name
    │        └── component-name.js
    └── pages
        └── page-name
            └── page-name.js

После выполнения сборки в папке build/js появятся файлы common[hash:8].js и vendors[hash:8].js:

only-template
└── build
    └── js
        ├── common[hash:8].js
        └── vendors[hash:8].js

Используем одиночные кавычки.

Отступы делать с помощью 4 пробелов.

Использовать LF переводы строк.

Имена переменных в camelCase

Если переменная содержит элемент DOM, то такая переменная должна начинаться с префикса n.

Неправильно:

let container = document.querySelector('element');

Правильно:

let nContainer = document.querySelector('element');

В сборку интегрирован линтер ESLint.

Файл настроек — .eslintrc.

Данный линтер позволяет поддерживать JS-код в соответствии с заданным регламентом.