Getting Started

Installation

Скачайте код ui-library-starter-2open in new window и оформите его в отдельный репозиторий. При выборе имени для нового репозитория необходимо сразу убедиться в том, что оно не занято на npmjs.comopen in new window. Пусть это будет ui-library-starter-2-test.

$ npm install

Customization

README.md

Поправьте первую строчку в @/README.md:

# Ui-library-starter 2 test project

package.json

Далее в @/package.json вам необходимо крайне аккуратно переписать актуальной информацией следующие поля, ничего не пропустив:

{
  "name": "ui-library-starter-2-test",
  "description": "UI Library Starter 2 Demonstration",
  "version": "0.1.0",
  "main": "dist/ui-library-starter-2-test.umd.min.js",
  "unpkg": "dist/ui-library-starter-2-test.umd.min.js",
  "jsdelivr": "dist/ui-library-starter-2-test.umd.min.js",
  "scripts": {
    "build": "vue-cli-service build --target lib --name ui-library-starter-2 src/main.ts",
  },
  "author": "Levon Gambaryan",
  "license": "MIT",
  "homepage": "",
  "repository": {
    "type": "git",
    "url": "https://github.com/ushliypakostnik/ui-library-starter-2-test"
  },
  "bugs": {
    "url": "https://github.com/ushliypakostnik/ui-library-starter-2-test/issues"
  },
  "keywords": []
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

Обратите внимание на имя проекта в конце команды деплоя build!

Documentation config

Перейдите к документации на VuePress и сконфигурируйте ее под себя @/docs/.vuepress/config.js:

Connecting fonts

Исходный проект библиотеки использует шрифт Ubuntu и вам необходимо подключить шрифт который диктует ваше руководство по стилю. Предположим, это Open Sans и у вас есть его веб-фонт.

Перепишите имя шрифта и переменные начертаний если требуется в файле ~/src/stylus/utils/_typography.styl:

$font-family = "Open Sans"

$font-weight = {
  regular: 400,
  bold: 700,
}

1
2
3
4
5
6

Поместите папку с правильным шрифтом рядом с папкой /Ubuntu в @/src/static/fonts/.

Пропишите правильные пути импорта и имя шрифта в таге body в секции стилей компонента для разработки @/src/Development.vue:

...

<style lang="stylus">
@import "./stylus/_stylebase.styl";

// Import UI Library fonts

@font-face {
  font-family: $font-family;
  src: url('./static/fonts/Ubuntu/Ubuntu-Regular.eot');
  src: local('Ubuntu Regular'), local('Ubuntu-Regular'),
    url('./static/fonts/Ubuntu/Ubuntu-Regular.eot?#iefix') format('embedded-opentype'),
    url('./static/fonts/Ubuntu/Ubuntu-Regular.woff2') format('woff2'),
    url('./static/fonts/Ubuntu/Ubuntu-Regular.woff') format('woff'),
    url('./static/fonts/Ubuntu/Ubuntu-Regular.ttf') format('truetype');
  font-weight: $font-weight.regular;
  font-style: normal;
}

@font-face {
  font-family: $font-family;
  src: url('./static/fonts/Ubuntu/Ubuntu-Bold.eot');
  src: local('Ubuntu Bold'), local('Ubuntu-Bold'),
    url('./static/fonts/Ubuntu/Ubuntu-Bold.eot?#iefix') format('embedded-opentype'),
    url('./static/fonts/Ubuntu/Ubuntu-Bold.woff2') format('woff2'),
    url('./static/fonts/Ubuntu/Ubuntu-Bold.woff') format('woff'),
    url('./static/fonts/Ubuntu/Ubuntu-Bold.ttf') format('truetype');
  font-weight: $font-weight.bold;
  font-style: bold;
}

...
</style>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

Удалите директорию со старым шрифтом @/src/static/fonts/Ubuntu.

Сleaning project

Если вы хотите получить полностью чистую документацию - произведите следующую очистку папок и файлов.

Удалите все папки и файлы в @/docs/ кроме директории @/docs/.vuepress и файла @/docs/README.md, который нужно оставить, но очистить:

# UI Library

...

1
2
3

Вернитесь к конфигурации документации и отразите изменения в @/docs/.vuepress/config.js.

Style setting

Запустите разработку документации командой:

$ npm run docs:dev

Ознакомьтесь с разделом Constantsopen in new window документации к исходному проекту.

Вам необходимо настроить препроцессор вашей библиотеки в точном соответсвии с вашим руководством по фирменному стилю.

Adding a component

После того как стили библиотеки настроены вы можете добавлять свои специфические компоненты.

Выберете имя для компонента в PascalCase стиле написания, предположим это ComponentName.

Добавьте директорию @/src/components/ComponentName.

Добавьте в нее индексный файл c импортом-экспортом:

@/src/components/ComponentName/index.ts

import ComponentName from './ComponentName.vue';

export default ComponentName;

1
2
3

И сам компонент:

@/src/components/ComponentName/ComponentName.vue

<template>
  <div
    class="component-name"
    :class="{
      '.component-name__element--modifier1': prop1,
      '.component-name__element--modifier2': prop2,
    }"
  >
    This is test component!!!
  </div>
</template>

<script>
import { defineComponent } from 'vue';

export default defineComponent({
  name: 'ComponentName',

  props: {
    prop1: {
      type: Boolean,
      required: true,
    },
    prop2: {
      type: Boolean,
      required: false,
      default: false,
    },
  },
});
</script>

<style lang="stylus" scoped>
@import "~/src/stylus/_stylebase.styl";

.component-name
  background $colors.primary // test styles
  // add adaptive
  +$mobile()
    display block

  &__element
    $text("natasha") // add typography

    &--modifier1
      color $colors.primary // add good color

    &--modifier2
      color $colors.secondary
</style>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50

Добавьте экспорт в индексный файл библиотеки @/src/components/index.ts:

export { default as ComponentName } from './ComponentName';

Добавьте документацию компонента в файл @/docs/components/component-name.md:

# ComponentName

## Description

This is new custom component.

## Connection

<template>
  <ComponentName prop1="Boolean(required)" />
</template>

## API

### Props

| **Name**  | **Type** | **Description** | **Default** |
| :-------- | :------- | :-------------- | ----------: |
| **prop1** | Boolean  | -               |  (required) |
| **prop2** | Boolean  | -               |     `false` |

...

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

Добавьте компонент в конфигурацию VuePress @/docs/.vuepress/config.js:

module.exports = {
  themeConfig: {
    sidebar: [
      {
        text: `Components`,
        collapsible: true,
        children: [
          {
            text: `ComponentName`,
            link: '/components/component-name',
          },
        ],
      },
    ],
  },
};

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

Using third party modules

WARNING

Используйте только относительные пути для импорта чего-либо в typescript ваших компонентов или модулей хранилища Vuex. Не используйте «абсолютные» алиасы (в контексте дочернего проекта, данный импорт будет искать зависимость в директории @/... проекта, а не библиотеки):

<script>
import Icon from '../Icon/Icon';

export default defineComponent({
  name: 'ComponentName',

  components: {
    Icon,
  },
});
</script>

1
2
3
4
5
6
7
8
9
10
11

import { Module } from 'vuex';

// Types
import { IStore, ILayout } from '../../models/store';

const initialState: ILayout = {
  // ...
};

const ModuleName: Module<ILayout, IStore> = {
  namespaced: true,

  state: initialState,

  getters: {
    // ...
  },

  actions: {
    // ...
  },

  mutations: {
    // ...
  },
};

export default ModuleName;

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

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

Так как мы используем глобальные стили собственной кастомизации модуля - невозможно будет защитить стили перекастомизации в SFC-обертке с помощью scoped:

<style lang="stylus">
@import "~/src/stylus/_stylebase.styl";

// Customization
// ...
</style>

1
2
3
4
5
6

Use the sandbox (not documentation)

Используйте специальный режим для разработки и тестирования модуля-библиотеки. Для того чтобы переключиться в него - выставите флаг isDevelopmentModuleMode в значение true главном файле проекта @/src/main.ts:

// ATTENTION! Set to true if you want
// to develop a module (not documentation)
// and false before publishing for use in projects
const isDevelopmentModuleMode = true;
if (isDevelopmentModuleMode) {
  console.log('Start development module!');
  ...
}

1
2
3
4
5
6
7
8

Library publishing

Зарегистрируйтесь на npmjs.comopen in new window и подтвердите регистрацию (дождитесь письма на почту).

Перед публикацией не забудьте отключить режим разработки модуля.

$ npm run build
$ npm version patch
$ npm publish

1
2
3

Connecting to projects

Вы можете либо использовать стартовый шаблон для новых проектов ui-library-2-testopen in new window, тогда вам придется заменить библиотеку:

$ npm uninstall ui-library-starter-2 --save-dev
$ npm install ui-library-starter-2-test --save-dev

1
2

Либо установить библиотеку как любой другой модуль в любой другой проект:

$ npm install ui-library-starter-2-test --save-dev

Организация стилей дочерних проектов может или иметь подобную библиотеке структуру или любую другую (например, если вы внедряете бибилиотеку в старый проект). Единственное требование: первый импорт в основном файле - основного файла библиотеки. Второй - подключение шрифтов и стилизация :root и body.

@/src/stylus/_stylebase.styl проекта использующего библиотеку:

// Import UI Library stylebase
@import '~ui-library-starter-2-test/src/stylus/_stylebase.styl';

// core
@import "core/_base"; // normalize

1
2
3
4
5

@/src/stylus/core/_base.styl проекта использующего библиотеку:

// Import UI Library fonts

@font-face {
  font-family: $font-family;
  src: url('~ui-library-starter-2-test/src/static/fonts/Ubuntu/Ubuntu-Regular.eot');
  src: local('Ubuntu Regular'), local('Ubuntu-Regular'),
    url('~ui-library-starter-2-test/src/static/fonts/Ubuntu/Ubuntu-Regular.eot?#iefix') format('embedded-opentype'),
    url('~ui-library-starter-2-test/src/static/fonts/Ubuntu/Ubuntu-Regular.woff2') format('woff2'),
    url('~ui-library-starter-2-test/src/static/fonts/Ubuntu/Ubuntu-Regular.woff') format('woff'),
    url('~ui-library-starter-2-test/src/static/fonts/Ubuntu/Ubuntu-Regular.ttf') format('truetype');
  font-weight: $font-weight.regular;
  font-style: normal;
}

@font-face {
  font-family: $font-family;
  src: url('~ui-library-starter-2-test/src/static/fonts/Ubuntu/Ubuntu-Bold.eot');
  src: local('Ubuntu Bold'), local('Ubuntu-Bold'),
    url('~ui-library-starter-2-test/src/static/fonts/Ubuntu/Ubuntu-Bold.eot?#iefix') format('embedded-opentype'),
    url('~ui-library-starter-2-test/src/static/fonts/Ubuntu/Ubuntu-Bold.woff2') format('woff2'),
    url('~ui-library-starter-2-test/src/static/fonts/Ubuntu/Ubuntu-Bold.woff') format('woff'),
    url('~ui-library-starter-2-test/src/static/fonts/Ubuntu/Ubuntu-Bold.ttf') format('truetype');
  font-weight: $font-weight.bold;
  font-style: bold;
}

// Base normalize

:root
  scroll-behavior smooth

body
  font-family $font-family, sans-serif
  -moz-osx-font-smoothing grayscale
  -webkit-font-smoothing antialiased
  text-rendering: optimizeSpeed
  color $colors.text
  overflow-x hidden

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

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

Подключите все это к главному шаблону @/src/App.vue:

...

<style lang="stylus">
@import "~/src/stylus/_stylebase.styl";
</style>

1
2
3
4
5

Исправьте имя библиотеки в импортах в точку входа @/src/main.js если вы брали готовый репо или подключите:

import { createApp } from 'vue';
import App from './App.vue';

import ComponentLibrary from 'ui-library-starter-2-test';
import 'ui-library-starter-2-test/dist/ui-library-starter-2-test.css';

...

1
2
3
4
5
6
7

Исправьте имя или добавьте команду update в @/package.json:

{
  "name": "ui-library-start-test",
  "scripts": {
    "update": "npm install ui-library-starter-2-test@latest"
  },
}

1
2
3
4
5
6

Updating in projects

Обновляйте библиотеку до последней версии в проектах:

$ npm run update

# Getting Started

# Installation

# Customization

# README.md

# package.json

# Documentation config

# Connecting fonts

# Сleaning project

# Style setting

# Adding a component

# Using third party modules

# Use the sandbox (not documentation)

# Library publishing

# Connecting to projects

# Updating in projects

Getting Started

Installation

Customization

README.md

package.json

Documentation config

Connecting fonts

Сleaning project

Style setting

Adding a component

Using third party modules

Use the sandbox (not documentation)

Library publishing

Connecting to projects

Updating in projects