@csssr/core-scripts
v4.0.0
Published
Утилита для развертывания нового проекта на [Next.js](https://nextjs.org/) c использованием библиотеки [Core Design](https://github.com/CSSSR/core-design).
Downloads
16
Keywords
Readme
core-scripts
Утилита для развертывания нового проекта на Next.js c использованием библиотеки Core Design.
Требования
- Для работы необходимо установить Node.js. Если не установлено, лучше установить LTS версию;
- Git. На macOS и Ubuntu он уже должен быть предустановлен по-умолчанию;
- Редактор кода. Советуем использовать VSCode;
- Для удобной работы со стилями советуется установить плагины vscode-styled-components и eslint.
Для публикации кода в git нужно иметь ssh-ключ (как сделать описано в куче статей, например в этой) и добавить публичный ключ в настройках GitHub-a.
Стоит также задать имя и e-mail, которые будут указываться в коммитах:
$ git config --global user.email '[email protected]'
$ git config --global user.name 'John Doe'
Развертывание проекта
- Подразумевается, что каждый проект должен храниться в отдельном репозитории. Поэтому следует начать с создания чистого репозитория на GitHub;
- С помощью терминала перейти в директорию, в которой будут храниться проекты;
$ cd projects
- Выполнить команду:
$ npx -p @csssr/core-scripts core-design create my-project
В терминале будут задаваться вопросы. На одном из этапов будет запрошен адрес репозитория (п. 1), в котором будет храниться код проекта.
В директории my-project
развернётся новый проект. Его нужно открыть в редакторе кода.
Публикация кода
Можно сразу опубликовать код в репозиторий. Это делается таким образом:
$ cd my-project
$ git add .
$ git commit -m 'initial commit'
$ git push
Деплой
Также можно сразу опубликовать код в GitHub Pages. Для этого нужно выполнить эту команду в директории проекта:
$ npm run deploy
Подробнее про деплой на GitHub Pages рассказано в этом видео.
Процесс деплоя делится на 3 стадии:
- Сборка (
npm run build
); - Экспорт (
npm run export
) — экспортируются страницы, указанные вnext.config.js
; - Деплой (
./scripts/deploy.sh
) — в файле есть комментарии о том, что вообще происходит.
Запуск сервера для разработки
- Перейти в директорию с проектом и запустить команду:
$ cd my-project
$ npm run dev
Далее в браузере нужно перейти по адресу http://localhost:3000, где, если всё прошло успешно, будет находится страница примера.
Структура проекта
Для создания новой страницы нужно создать новый jsx-файл в директории ./pages
директории проекта.
Название файла является также путем к странице. К примеру, если создать файл с именем blank.jsx
, c примерно следующим содержанием:
const NewPage = () => <div>Hello world!</div>
export default NewPage
то полученная страница будет находится по адресу http://localhost:3000/blank.
Создание прототипов
После создания страницы можно приступать к прототипированию. Если вам нужен какой либо-компонент из нашей библиотеки то его нужно импортировать на страницу прототипа, для этого в начале файла нужно добавить строчку:
import { Button } from '@csssr/core-design'
Если вам нужно несколько компонентов, то укажите их названия через запятую.
После импорта компонента его нужно вставить на страницу. Для этого поместите его на в объект страницы:
const NewPage = () => <Button>Кнопка</Button>
export default NewPage
Теперь у вас на странице появится компонент кнопки.
Изменение состояний компонентов
У компонентов есть пропсы, с помощью которых можно изменять их состояние. Пропсы бывают дефолтными, это те, которые компонент имеет сам по себе в зависимости от своего типа, и кастомными, это те, которые определяют разработчики. Кастомные пропсы каждого компонента свои, их количество, названия и их значиня устанавливают разработчики на этапе проектирования компонента, после обсуждения его с дизайнерами.
Кроме того, ваш редактор кода может подсказывать какие пропсы имеет компонент и какие значения они могу принимать
Пропсы для компонента записываются сразу после его названия внутри угловых скобок:
<Button kind="secondary">Кнопка</Button>
Пропс kind
меняет тему кнопки, попробуйте ввести эту запись и посмотреть что получится.
Изменение стилей компонентов
Все компоненты, будут принимать пропс css
. В этом пропсе можно будет описать css для компонента, если вам нужно что-то поменять в нём на месте, например:
<Button
css={css`
margin-top: 40px;
color: red;
outline: 1px solid red;
background-color: transparent;
`}
>
Кнопка
</Button>
Обратите внимание что пропс должен css принимать функцию css
, которая в свою очеред принимает строку с описаными css правилами. Эту функцию нужно импортировать так же как компоненты на страницу где вы её собираетесь приминять:
import { css } from '@emotion/react'
Создание новых компонентов
Вы можете создать новый компонент командой:
$ npx -p @csssr/core-scripts core-design create-component _НазваниеКомпонента_
Название компонента должно быть написано в PascalCase. После исполнения команды в папке components будет создана директория с файлом компонента:
import * as React from 'react'
import styled from '@emotion/styled'
import styles from './MyNewComponent.styles'
// import { Название_компонента_из_нашей_библиотеки_компонентов } from '@csssr/core-design'
const OriginMyNewComponent = props => <div className={props.className}>{props.children}</div>
const MyNewComponent = styled(OriginMyNewComponent)`
${styles.base}
`
export { MyNewComponent }
export default MyNewComponent
и стилями для него:
import { css } from '@emotion/react'
export default {
base: css`
display: block;
`,
}
В примере файла компонента OriginMyNewComponent
нужен для описания верстки нового компоннета. В MyNewComponent
указывается какие стили будут применятся для нового компонента. Стили делятся на логические блоки:
base
— для общих и статичных стилей компонента, т.e. тех, которые у компонента будут всегда не смотря на передаваемые ему пропсы;font
— для стилей шрифтов;themes
— для стилей описывающие компонент при различных темах;- и любые другие кастомные блоки, которые вы считаете уместными (с течением времени этот список будет пополнятся укрепившимеся паттернами).
Если вам в новом компонент понадобится какой-либо другой компонент из дизайн-системы, вы можете его импортировать и вставить в вёрстку нового компонента, например:
import { Button } from '@csssr/core-design'
const OriginMyNewComponent = props => (
<div className={props.className}>
<Button>Кнопка</Button>
</div>
)
Список всех компонентов дизайн системы и перечень их свойств вы можете найти на http://core-design.csssr.ru
Работа с темами
Объект темы
Тема это объект в котором хранятся переменные цветов, брейкпоинтов, размеров. Все компоненты построены на основании этих переменных. Вот так выглядит дефолтная тема:
const theme = {
colors: {
primary: {
origin: primaryOrigin.hex(),
darken15: primaryOrigin.darken(0.15).hex(),
},
secondary: {
origin: secondaryOrigin.hex(),
darken100: secondaryOrigin.darken(1).hex(),
},
},
baseSize: 16,
breakpoints: {
desktop: {
all: '@media (min-width: 1280px)',
m: '@media (min-width: 1360px) and (max-width: 1919px)',
s: '@media (min-width: 1280px) and (max-width: 1359px)',
},
tablet: {
all: '@media (min-width: 768px) and (max-width: 1279px)',
m: '@media (min-width: 1024px) and (max-width: 1279px)',
s: '@media (min-width: 768px) and (max-width: 1023px)',
},
mobile: {
all: '@media (max-width: 767px)',
},
below: {
desktop: '@media (max-width: 1279px)',
},
},
}
Где:
colors
— это различные цвета их оттенки, генерируемые из исходного значения цвета.baseSize
— это размер шрифта уhtml
тега страницы. Все расстояния и размеры в компонентах задаются c помощью относительной единицыrem
.breakpoints
— это медиа-выражения. Они поделены на несколько подтиповdesktop
,tablet
,mobile
иbelow
. Первые три содержат в себе различные медиа-выражения для соответствующих устройств и разрешений экранов. Размерыs
,m
условны, их можно задвать произвольно, главное что бы они между собой не пересикались,all
охватывает все разрешения подтипа.below
содержит в себе медиавыражения, которые охватывают разрешения от заданного и ниже.
Если вы захотите поменять какой-либо из дефолтных параметров темы, то вам нужно будет создать новый файл темы в директории themes
(если её ещё нет, то создайте в рутовской директории), а в новую переменную темы, скопировать туда старую и изменить нужные вам поля. После переменную новой темы нужно передать в пропс theme
компонента Root
, который находится в pages/_app.jsx
:
<Root theme={myNewtheme}>
<Component {...pageProps} />
</Root>
Использование переменных темы
Что бы использовать переменные темы в CSS вам нужно передать объект props
и указать путь до соответствующей переменной. Например, у вас есть следующие стили:
export default {
base: css`
color: blue;
`,
}
но вы хотите что бы цвет был как primary
из дефолтной темы, тогда вам нужно написать стили следующим образом:
export default {
base: props => css`
color: ${props.theme.colors.primary.origin};
`,
}
Работа с цветами
Для манипуляций с цветами у нас используется библиотека color. Цвета в темах можно называть как угодно, но желательно максимально абстракто без ссылок на название цвета или состояний, например: primary
, secondary
, danger
, success
и т.д. У каждого цевета должен быть объевлен origin
, это его исходное состояние. Оттенки цветов генерируются из origin
и называются по методу генерации и его значения, например:
const primaryOrigin = color('#0076ff')
const theme = {
colors: {
primary: {
origin: primaryOrigin.hex(),
darken15: primaryOrigin.darken(0.15).hex(),
darken30: primaryOrigin.darken(0.3).hex(),
lighten45: primaryOrigin.lighten(0.45).hex(),
},
},
}
Список всех доступных методов находится тут