From e009f2cd2b337b10792a262fd13d8589c31275e7 Mon Sep 17 00:00:00 2001 From: Alex Sokolov <4497128+Alex-Sokolov@users.noreply.github.com> Date: Wed, 28 Nov 2018 21:28:13 +0300 Subject: [PATCH 01/31] docs: (ru) config/README.md update devServer example --- docs/ru/config/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/ru/config/README.md b/docs/ru/config/README.md index a8caf124c2..90ad9c6345 100644 --- a/docs/ru/config/README.md +++ b/docs/ru/config/README.md @@ -330,12 +330,12 @@ module.exports = { module.exports = { devServer: { proxy: { - '/api': { + '^/api': { target: '', ws: true, changeOrigin: true }, - '/foo': { + '^/foo': { target: '' } } From 8cf3414e39b24e7c5daae47e56da05c60479a94d Mon Sep 17 00:00:00 2001 From: Alex Sokolov <4497128+Alex-Sokolov@users.noreply.github.com> Date: Wed, 28 Nov 2018 21:28:26 +0300 Subject: [PATCH 02/31] docs: (ru) creating-a-project.md update --- docs/ru/guide/creating-a-project.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/ru/guide/creating-a-project.md b/docs/ru/guide/creating-a-project.md index fe75cfc88c..be5fdb9bf0 100644 --- a/docs/ru/guide/creating-a-project.md +++ b/docs/ru/guide/creating-a-project.md @@ -10,6 +10,9 @@ vue create hello-world ::: warning Предупреждение Если используете Git Bash с minTTY на Windows, то интерактивные подсказки не будут работать. Запускайте команды таким образом `winpty vue.cmd create hello-world`. +При желании использовать синтаксис `vue create hello-world` можно создать псевдоним для команды, добавив следующую строку в ваш файл `~/.bashrc`. +`alias vue='winpty vue.cmd'` +Необходимо будет перезапустить сеанс терминала Git Bash для использования обновлённого файла bashrc. ::: Вам будет предложено выбрать пресет настроек. Можно выбрать пресет по умолчанию (default), который добавляет Babel + ESLint, или настройку вручную («Manually select features») для выбора требуемых возможностей в новом проекте. From 45e4ff34d3d06e90b879f1c018ad140141695e3e Mon Sep 17 00:00:00 2001 From: Alex Sokolov <4497128+Alex-Sokolov@users.noreply.github.com> Date: Wed, 9 Jan 2019 23:56:10 +0300 Subject: [PATCH 03/31] docs: css.md add less examples --- docs/ru/guide/css.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/docs/ru/guide/css.md b/docs/ru/guide/css.md index 526d9500af..765402b815 100644 --- a/docs/ru/guide/css.md +++ b/docs/ru/guide/css.md @@ -110,7 +110,7 @@ module.exports = { ## Передача настроек в загрузчики пре-процессоров -Иногда может возникнуть необходимость передать настройки в загрузчик пре-процессора для webpack. Вы можете сделать это с помощью опции `css.loaderOptions` в `vue.config.js`. Например, для передачи глобальных переменных во все стили Sass: +Иногда может возникнуть необходимость передать настройки в загрузчик пре-процессора для webpack. Вы можете сделать это с помощью опции `css.loaderOptions` в `vue.config.js`. Например, для передачи глобальных переменных во все стили Sass/Less: ``` js // vue.config.js @@ -122,6 +122,14 @@ module.exports = { // @/ это псевдоним к каталогу src/ поэтому предполагается, // что у вас в проекте есть файл `src/variables.scss` data: `@import "@/variables.scss";` + }, + // передача настроек Less.js в less-loader + less:{ + // http://lesscss.org/usage/#less-options-strict-units `Global Variables` + // `primary` — имя поля глобальных переменных + globalVars: { + primary: '#fff' + } } } } From ddcbe7748eff2a9a7b4028c286fea0fac2aa86e6 Mon Sep 17 00:00:00 2001 From: Alex Sokolov <4497128+Alex-Sokolov@users.noreply.github.com> Date: Thu, 10 Jan 2019 00:07:40 +0300 Subject: [PATCH 04/31] docs: browser-compatibility.md update --- docs/ru/guide/browser-compatibility.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/ru/guide/browser-compatibility.md b/docs/ru/guide/browser-compatibility.md index b8456daccd..2151c92223 100644 --- a/docs/ru/guide/browser-compatibility.md +++ b/docs/ru/guide/browser-compatibility.md @@ -70,6 +70,23 @@ Vue CLI будет собирать **две версии** вашего при ::: tip Совет ` @@ -127,7 +123,7 @@ dist/foo.1.js 5.24 kb 1.64 kb Теперь на странице пользователю необходимо только подключить Vue и файл точки входа: -``` html +```html diff --git a/docs/ru/guide/cli-service.md b/docs/ru/guide/cli-service.md index 5f929298c1..892aa2e1a7 100644 --- a/docs/ru/guide/cli-service.md +++ b/docs/ru/guide/cli-service.md @@ -6,7 +6,7 @@ Это то, что вы увидите в `package.json` проекта с пресетом настроек по умолчанию: -``` json +```json { "scripts": { "serve": "vue-cli-service serve", @@ -17,15 +17,15 @@ Вы можете вызвать эти команды с помощью npm или Yarn: -``` bash +```bash npm run serve # ИЛИ yarn serve ``` -Если у вас установлен [npx](https://github.com/zkat/npx) (должен поставляться в комплекте с последней версией npm), то вы также можете запустить бинарник напрямую: +Если у вас установлен [npx](https://github.com/npm/npx) (должен поставляться в комплекте с последней версией npm), то вы также можете запустить бинарник напрямую: -``` bash +```bash npx vue-cli-service serve ``` @@ -52,10 +52,16 @@ npx vue-cli-service serve --https использовать https (по умолчанию: false) ``` +::: tip --copy +Копирование в буфер обмена может не работать на некоторых платформах. Если копирование выполнилось успешно, то рядом с URL-адресом локального сервера разработки будет отображено `(copied to clipboard)`. +::: + Команда `vue-cli-service serve` запускает сервер для разработки (основанный на [webpack-dev-server](https://github.com/webpack/webpack-dev-server)), предоставляющий из коробки функцию горячей замены модулей. Кроме флагов командной строки, также можно настраивать сервер для разработки с помощью поля [devServer](../config/#devserver) в файле `vue.config.js`. +В команде CLI `[entry]` означает *входной файл*, а не *дополнительный входной файл*. Если вы перезапишете запись в CLI, тогда записи из `config.pages` больше не будут учитываться, что может привести к ошибке. + ## vue-cli-service build ``` @@ -67,6 +73,7 @@ npx vue-cli-service serve --dest определить каталог сборки (по умолчанию: dist) --modern собирать приложение для современных браузеров с авто-фоллбэком для старых --target app | lib | wc | wc-async (по умолчанию: app) + --formats список выходных форматов для сборок библиотек (по умолчанию: commonjs,umd,umd-min) --name имя библиотеки или режим веб-компонента (по умолчанию: "name" в package.json или имя файла точки входа) --no-clean не удалять каталог dist перед сборкой проекта --report сгенерировать report.html для анализа содержимого сборки @@ -100,13 +107,13 @@ npx vue-cli-service serve Некоторые плагины CLI добавляют собственные команды в `vue-cli-service`. Например, `@vue/cli-plugin-eslint` внедряет команду `vue-cli-service lint`. Вы можете посмотреть весь список команд запустив: -``` bash +```bash npx vue-cli-service help ``` Вы также можете узнать о доступных параметрах каждой команды с помощью: -``` bash +```bash npx vue-cli-service help [command] ``` @@ -120,7 +127,7 @@ npx vue-cli-service help [command] После установки `@vue/cli-service` также добавляется [yorkie](https://github.com/yyx990803/yorkie), который позволяет легко указывать Git хуки, используя поле `gitHooks` в файле `package.json`: -``` json +```json { "gitHooks": { "pre-commit": "lint-staged" diff --git a/docs/ru/guide/creating-a-project.md b/docs/ru/guide/creating-a-project.md index fbfebcfef6..dd5123a653 100644 --- a/docs/ru/guide/creating-a-project.md +++ b/docs/ru/guide/creating-a-project.md @@ -4,7 +4,7 @@ Для создания нового проекта запустите команду: -``` bash +```bash vue create hello-world ``` @@ -33,7 +33,7 @@ vue create hello-world Команда `vue create` предоставляет множество опций — вы можете изучить их все выполнив: -``` bash +```bash vue create --help ``` @@ -63,7 +63,7 @@ vue create --help Вы можете создавать и управлять проектами через графический интерфейс командой `vue ui`: -``` bash +```bash vue ui ``` @@ -75,7 +75,7 @@ vue ui Vue CLI >= 3 использует команду `vue`, поэтому он перезаписывает Vue CLI 2 (`vue-cli`). Если вам по-прежнему необходимо старое поведение и функциональность команды `vue init`, нужно лишь установить глобально дополнительный плагин `@vue/cli-init`: -``` bash +```bash npm install -g @vue/cli-init # vue init теперь работает точно также, как и в vue-cli@2.x vue init webpack my-project diff --git a/docs/ru/guide/css.md b/docs/ru/guide/css.md index 92d3a06a14..cf03cf216f 100644 --- a/docs/ru/guide/css.md +++ b/docs/ru/guide/css.md @@ -10,9 +10,9 @@ Вы можете выбрать пре-процессоры (Sass/Less/Stylus) при создании проекта. Если вы этого не сделали, то внутренняя конфигурация webpack всё равно настроена для их использования. Вам лишь требуется вручную доустановить соответствующие загрузчики для webpack: -``` bash +```bash # Sass -npm install -D sass-loader node-sass +npm install -D sass-loader sass # Less npm install -D less-loader less @@ -23,12 +23,22 @@ npm install -D stylus-loader stylus Теперь вы можете импортировать соответствующие типы файлов, или использовать их синтаксис внутри файлов `*.vue` с помощью: -``` vue +```vue ``` +::: tip Совет по производительности Sass +Обратите внимание, при использовании Dart Sass **синхронная компиляция вдвое быстрее асинхронной** по умолчанию, из-за накладных расходов на асинхронные коллбэки. Чтобы избежать их можно воспользоваться пакетом [fibers](https://www.npmjs.com/package/fibers) для вызова асинхронных импортёров по пути синхронного кода. Для этого просто установите `fibers` в качестве зависимости проекта: + +``` +npm install -D fibers +``` + +Также имейте в виду, поскольку это нативный модуль, то могут возникнуть различные проблемы совместимости, в зависимости от ОС и окружения сборки. В таких случаях выполните `npm uninstall -D fibers` для устранения проблемы. +::: + ### Автоматические импорты Если вы хотите автоматически импортировать файлы (для цветов, переменных, примесей...), можно использовать [style-resources-loader](https://github.com/yenshih/style-resources-loader). Вот пример для stylus, который импортирует `./src/styles/imports.styl` в каждый однофайловый компонент и в каждый файл stylus: @@ -75,33 +85,38 @@ Vue CLI использует PostCSS внутри себя. Для импорта CSS или других файлов пре-процессоров в качестве CSS-модулей в JavaScript, необходимо чтобы имя файла заканчивалось на `.module.(css|less|sass|scss|styl)`: -``` js +```js import styles from './foo.module.css' // работает для всех поддерживаемых пре-процессоров import sassStyles from './foo.module.scss' ``` -Если вы не хотите указывать `.module` в именах файлов, установите `css.modules` в `true` внутри файла `vue.config.js`: +Если вы не хотите указывать `.module` в именах файлов, установите `css.requireModuleExtension` в `false` внутри файла `vue.config.js`: -``` js +```js // vue.config.js module.exports = { css: { - modules: true + requireModuleExtension: false } } ``` Если вы хотите настроить генерируемые имена классов для CSS-модулей, вы можете сделать это с помощью опции `css.loaderOptions.css` в `vue.config.js`. Все настройки `css-loader` поддерживаются, например `localIdentName` и `camelCase`: -``` js +```js // vue.config.js module.exports = { css: { loaderOptions: { css: { - localIdentName: '[name]-[hash]', - camelCase: 'only' + // Примечание: формат конфигурации отличается между Vue CLI v4 и v3 + // Для пользователей Vue CLI v3, обратитесь к документации css-loader v1 + // https://github.com/webpack-contrib/css-loader/tree/v1.0.1 + modules: { + localIdentName: '[name]-[hash]', + localsConvention: 'camelCaseOnly' + } } } } @@ -112,15 +127,23 @@ module.exports = { Иногда может возникнуть необходимость передать настройки в загрузчик пре-процессора для webpack. Вы можете сделать это с помощью опции `css.loaderOptions` в `vue.config.js`. Например, для передачи глобальных переменных во все стили Sass/Less: -``` js +```js // vue.config.js module.exports = { css: { loaderOptions: { // передача настроек в sass-loader + // @/ это псевдоним к каталогу src/ поэтому предполагается, + // что у вас в проекте есть файл `src/variables.scss` sass: { - // @/ это псевдоним к каталогу src/ поэтому предполагается, - // что у вас в проекте есть файл `src/variables.scss` + data: `@import "~@/variables.sass"` + }, + // по умолчанию опция `sass` будет применяться к обоим синтаксисам + // потому что синтаксис `scss` по сути также обрабатывается sass-loader + // но при настройке опции `data` синтаксис `scss` требует точку с запятой + // в конце оператора, в то время как для `sass` точки с запятой не требуется + // в этом случае синтаксис `scss` можно настроить отдельно с помощью опции `scss` + scss: { data: `@import "~@/variables.scss";` }, // передача настроек Less.js в less-loader diff --git a/docs/ru/guide/deployment.md b/docs/ru/guide/deployment.md index 8d9bb722f2..246ea1d69a 100644 --- a/docs/ru/guide/deployment.md +++ b/docs/ru/guide/deployment.md @@ -10,7 +10,7 @@ Каталог `dist` предназначен для обслуживания HTTP-сервером (если не задали `publicPath` относительным значением), поэтому не сработает если напрямую открыть `dist/index.html` через `file://` протокол. Самый простой способ предпросмотра вашей сборки для production локально — использовать статический файловый сервер Node.js, например [serve](https://github.com/zeit/serve): -``` bash +```bash npm install -g serve # флаг -s означает запуск serve в режиме одностраничного приложения (SPA) # который решает проблему маршрутизации, описанную ниже @@ -35,13 +35,15 @@ serve -s dist ### GitHub Pages +#### Публикация обновлений вручную + 1. Установите корректное значение `publicPath` в `vue.config.js`. Если вы публикуете по адресу `https://.github.io/`, вы можете опустить `publicPath`, так как оно по умолчанию `"/"`. Если вы публикуете по адресу `https://.github.io//`, (т.е. ваш репозиторий находится по адресу `https://github.com//`), установите `publicPath` в значение `"//"`. Например, если ваш репозиторий называется "my-project", то ваш `vue.config.js` будет выглядеть примерно так: - ``` js + ```js module.exports = { publicPath: process.env.NODE_ENV === 'production' ? '/my-project/' @@ -51,7 +53,7 @@ serve -s dist 2. Внутри вашего проекта создайте `deploy.sh` со следующим содержимым (при необходимости раскомментировав подсвеченные строки) и запустите его для публикации: - ``` bash{13,20,23} + ```bash{13,20,23} #!/usr/bin/env sh # остановить публикацию при ошибках @@ -79,9 +81,34 @@ serve -s dist cd - ``` - ::: tip Совет - Вы также можете запустить скрипт выше в вашей конфигурации CI чтобы включить автоматическую публикацию на каждый push в репозиторий. - ::: +#### Использование Travis CI для автоматических обновлений + +1. Установите правильный `publicPath` в `vue.config.js`, как описано выше. + +2. Установите клиент Travis CLI: `gem install travis && travis --login` + +3. Сгенерируйте [токен доступа](https://help.github.com/en/articles/creating-a-personal-access-token-for-the-command-line) на GitHub с правами доступа к репозиторию. + +4. Разрешите доступ Travis к репозиторию: `travis set GITHUB_TOKEN=xxx` (`xxx` — это персональный токен доступа из шага 3.) + +5. Создайте файл `.travis.yml` в корневом каталоге проекта. + + ```yaml + language: node_js + node_js: + - "node" + cache: npm + script: npm run build + deploy: + provider: pages + skip_cleanup: true + github_token: $GITHUB_TOKEN + local_dir: dist + on: + branch: master + ``` + +6. Добавьте файл `.travis.yml` в репозиторий, чтобы запустить первую сборку. ### GitLab Pages @@ -126,14 +153,14 @@ module.exports = { 1. На сайте Netlify добавьте новый проект из GitHub со следующими настройками: - - **Build Command:** `npm run build` или `yarn build` - - **Publish directory:** `dist` + - **Build Command:** `npm run build` или `yarn build` + - **Publish directory:** `dist` 2. Нажмите кнопку публикации! Также посмотрите [vue-cli-plugin-netlify-lambda](https://github.com/netlify/vue-cli-plugin-netlify-lambda). -Для получения прямых хитов при использовании `режима history` во Vue Router, необходимо создавть файл `_redirects` в каталоге `/public` со следующим содержимым: +Для получения прямых хитов при использовании `режима history` во Vue Router, необходимо создавать файл `_redirects` в каталоге `/public` со следующим содержимым: ``` # Настройки Netlify для одностраничных приложений (SPA) @@ -142,6 +169,28 @@ module.exports = { Подробнее можно изучить в [документации Netlify по перенаправлениям](https://www.netlify.com/docs/redirects/#history-pushstate-and-single-page-apps). +### Render + +[Render](https://render.com) предлагает [бесплатный хостинг статических сайтов](https://render.com/docs/static-sites) с полностью управляемым SSL, глобальным CDN и непрерывным автоматическим развёртыванием из GitHub. + +1. Создайте новый Web Service в Render, и предоставьте доступ для GitHub-приложения Render в репозиторий. + +2. При создании используйте следующие значения: + + - **Окружение:** `Static Site` + - **Команда сборки:** `npm run build` или `yarn build` + - **Каталог публикации:** `dist` + +Всё! Приложение будет доступно по URL-адресу Render сразу, как только завершится сборка. + +Для того, чтобы получать прямые хиты при использовании режима history во Vue Router, необходимо добавить следующее правило на вкладке `Redirects/Rewrites` вашего сайта. + + - **Источник:** `/*` + - **Назначение:** `/index.html` + - **Статус** `Rewrite` + +Узнайте больше о настройке [перенаправлений, перезаписей](https://render.com/docs/redirects-rewrites) и [пользовательских доменах](https://render.com/docs/custom-domains) на Render. + ### Amazon S3 Плагин [vue-cli-plugin-s3-deploy](https://github.com/multiplegeorges/vue-cli-plugin-s3-deploy). @@ -211,49 +260,75 @@ firebase deploy --only hosting ### Now -1. Установите глобально Now CLI: +1. Установите Now CLI: -```bash -npm install -g now -``` + ```bash + npm install -g now + + # Или если предпочитаете локальную установку + npm install now + ``` 2. Добавьте файл `now.json` в корневой каталог проекта: ```json { "name": "my-example-app", - "type": "static", - "static": { - "public": "dist", - "rewrites": [ - { - "source": "**", - "destination": "/index.html" - } - ] - }, - "alias": "vue-example", - "files": [ - "dist" - ] + "version": 2, + "builds": [ + { + "src": "package.json", + "use": "@now/static-build" + } + ], + "routes": [ + { + "src": "/(js|css|img)/.*", + "headers": { "cache-control": "max-age=31536000, immutable" } + }, + { "handle": "filesystem" }, + { "src": ".*", "dest": "/" } + ], + "alias": "example.com" } ``` - Можно детальнее настроить статическую публикацию, обратившись к [документации Now](https://zeit.co/docs/deployment-types/static). - -3. Добавьте скрипт для публикации в `package.json`: + Если у вас есть другие/дополнительные каталоги, измените маршрут соответствующим образом: + + ```diff + - { + - "src": "/(js|css|img)/.*", + - "headers": { "cache-control": "max-age=31536000, immutable" } + - } + + { + + "src": "/(js|css|img|fonts|media)/.*", + + "headers": { "cache-control": "max-age=31536000, immutable" } + + } + ``` - ```json - "deploy": "npm run build && now && now alias" + Когда значение `outputDir` вместо стандартного `dist` указано `build`: + + ```diff + - { + - "src": "package.json", + - "use": "@now/static-build" + - } + + { + + "src": "package.json", + + "use": "@now/static-build", + + "config": { "distDir": "build" } + + } ``` - Если вы хотите по умолчанию публиковать публично, то измените команду на следующую: +3. Добавьте `now-build` скрипт для публикации в `package.json`: ```json - "deploy": "npm run build && now --public && now alias" + "now-build": "npm run build" ``` - Это автоматически установит псевдоним сайта на последнюю публикацию. Теперь просто запустите команду `npm run deploy` для публикации приложения. + Для публикации запустите `now`. + + Если необходим псевдоним публикации, запустите `now --target production`. ### Stdlib @@ -261,7 +336,38 @@ npm install -g now ### Heroku -> TODO | Присылайте пулл-реквесты. +1. [Установите Heroku CLI](https://devcenter.heroku.com/articles/heroku-cli) + +2. Создайте файл `static.json`: + + ```json + { + "root": "dist", + "clean_urls": true, + "routes": { + "/**": "index.html" + } + } + ``` + +3. Добавьте файл `static.json` в git + + ```bash + git add static.json + git commit -m "add static configuration" + ``` + +4. Запустите публикацию на Heroku + + ```bash + heroku login + heroku create + heroku buildpacks:add heroku/nodejs + heroku buildpacks:add https://github.com/heroku/heroku-buildpack-static + git push heroku master + ``` + +Подробная информация: [https://gist.github.com/hone/24b06869b4c1eca701f9](https://gist.github.com/hone/24b06869b4c1eca701f9) ### Surge @@ -299,7 +405,7 @@ npm install --global surge 3. В проекте создайте `deploy.sh` с указанным содержимым и запустите его для публикации: - ``` bash{13,20,23} + ```bash{13,20,23} #!/usr/bin/env sh # остановиться при ошибках @@ -319,3 +425,90 @@ npm install --global surge cd - ``` + +### Docker (Nginx) + +Deploy your application using nginx inside of a docker container. + +1. Установите [docker](https://www.docker.com/get-started) + +2. Создайте файл `Dockerfile` в корневом каталоге проекта + + ```Dockerfile + FROM node:10 + COPY ./ /app + WORKDIR /app + RUN npm install && npm run build + FROM nginx + RUN mkdir /app + COPY --from=0 /app/dist /app + COPY nginx.conf /etc/nginx/nginx.conf + ``` + +3. Создайте файл `.dockerignore` в корневом каталоге проекта + + Настройка файла `.dockerignore` предотвращает копирование `node_modules` и любых промежуточных артефактов сборки в образ, что может вызывать проблемы при сборке. + + ```gitignore + **/node_modules + **/dist + ``` + +4. Создайте файл `nginx.conf` в корневом каталоге проекта + + `Nginx` — это HTTP(s)-сервер, который будет работать в вашем контейнере docker. Он использует конфигурационный файл для определения того как предоставлять содержимое / какие порты прослушивать / и так далее. См. [документацию по конфигурации nginx](https://www.nginx.com/resources/wiki/start/topics/examples/full/) для ознакомления со всеми возможными примерами конфигураций. + + Ниже приведена простая конфигурация `nginx`, которая обслуживает ваш vue-проект на порту `80`. Корневой `index.html` служит для `page not found` / `404` ошибок, что позволяет использовать маршрутизации, основанной на `pushState()`. + + ```text + user nginx; + worker_processes 1; + error_log /var/log/nginx/error.log warn; + pid /var/run/nginx.pid; + events { + worker_connections 1024; + } + http { + include /etc/nginx/mime.types; + default_type application/octet-stream; + log_format main '$remote_addr - $remote_user [$time_local] "$request" ' + '$status $body_bytes_sent "$http_referer" ' + '"$http_user_agent" "$http_x_forwarded_for"'; + access_log /var/log/nginx/access.log main; + sendfile on; + keepalive_timeout 65; + server { + listen 80; + server_name localhost; + location / { + root /app; + index index.html; + try_files $uri $uri/ /index.html; + } + error_page 500 502 503 504 /50x.html; + location = /50x.html { + root /usr/share/nginx/html; + } + } + } + ``` + +5. Соберите образ docker + + ```bash + docker build . -t my-app + # Sending build context to Docker daemon 884.7kB + # ... + # Successfully built 4b00e5ee82ae + # Successfully tagged my-app:latest + ``` + +6. Запустите образ docker + + Эта сборка основана на официальном образе `nginx`, поэтому перенаправление логов уже настроено и само-демонтизация (self daemonizing) отключена. Для улучшения работы nginx в контейнере docker были установлены некоторые другие настройки по умолчанию. Подробнее см. в [репозитории nginx docker](https://hub.docker.com/_/nginx). + + ```bash + docker run -d -p 8080:80 my-app + curl localhost:8080 + # ... + ``` diff --git a/docs/ru/guide/html-and-static-assets.md b/docs/ru/guide/html-and-static-assets.md index c7d61fc1d6..938e4a7006 100644 --- a/docs/ru/guide/html-and-static-assets.md +++ b/docs/ru/guide/html-and-static-assets.md @@ -16,7 +16,7 @@ В дополнение к [значениям по умолчанию, предоставляемым `html-webpack-plugin`](https://github.com/jantimon/html-webpack-plugin#writing-your-own-templates), все [переменные окружения в клиентском коде](./mode-and-env.md#испоnьзование-переменных-окружения-в-кnиентском-коде) также доступны напрямую. Например, чтобы использовать значение `BASE_URL`: -``` html +```html ``` @@ -39,9 +39,13 @@ Эти подсказки внедряются [@vue/preload-webpack-plugin](https://github.com/vuejs/preload-webpack-plugin) и могут быть изменены / удалены с помощью `chainWebpack` через `config.plugin('prefetch')`. +::: tip Примечание для многостраничных конфигураций +При использовании многостраничной конфигурации имя плагина нужно изменить в соответствии со структурой `prefetch-{pagename}`, например `prefetch-app`. +::: + Например: -``` js +```js // vue.config.js module.exports = { chainWebpack: config => { @@ -61,7 +65,7 @@ module.exports = { Когда prefetch плагин отключён, вы можете вручную указывать необходимые фрагменты для prefetch с помощью инлайновых комментариев для webpack: -``` js +```js import(/* webpackPrefetch: true */ './someAsyncComponent.vue') ``` @@ -75,7 +79,7 @@ Webpack добавит prefetch-ссылки когда родительский При использовании Vue CLI с существующим бэкендом, вам может потребоваться отключить генерацию `index.html`, чтобы сгенерированные ресурсы могли быть использованы с другим документом по умолчанию. Для этого добавьте в файл [`vue.config.js`](../config/#vue-config-js) следующее: -``` js +```js // vue.config.js module.exports = { // отключение хэшей в именах файлов @@ -115,13 +119,13 @@ module.exports = { Например, `url(./image.png)` будет преобразован в `require('./image.png')`, а тег шаблона -``` html +```html ``` будет скомпилирован в: -``` js +```js h('img', { attrs: { src: require('./image.png') }}) ``` @@ -129,7 +133,7 @@ h('img', { attrs: { src: require('./image.png') }}) Изменить размер можно через [chainWebpack](../config/#chainwebpack). Например, чтобы установить лимит в 10 КБайт: -``` js +```js // vue.config.js module.exports = { chainWebpack: config => { @@ -150,7 +154,7 @@ module.exports = { - Если URL начинается с `~`, то всё что после него будет интерпретироваться как запрос модуля. Это означает, что вы можете ссылаться на ресурсы даже внутри `node_modules`: - ``` html + ```html ``` @@ -170,13 +174,13 @@ module.exports = { - В `public/index.html` или других HTML-файлах, используемых `html-webpack-plugin` в качестве шаблонов, необходимо добавлять префикс в ссылки с помощью `<%= BASE_URL %>`: - ``` html + ```html ``` - В шаблонах потребуется сначала передать `BASE_URL` в компонент: - ``` js + ```js data () { return { publicPath: process.env.BASE_URL @@ -186,7 +190,7 @@ module.exports = { А затем использовать в шаблоне: - ``` html + ```html ``` diff --git a/docs/ru/guide/installation.md b/docs/ru/guide/installation.md index f9784b57a4..980b126f69 100644 --- a/docs/ru/guide/installation.md +++ b/docs/ru/guide/installation.md @@ -9,9 +9,9 @@ Vue CLI требуется [Node.js](https://nodejs.org/) версии 8.9 или выше (рекомендуется 8.11.0+). Управлять несколькими версиями Node на машине можно с помощью [nvm](https://github.com/creationix/nvm) или [nvm-windows](https://github.com/coreybutler/nvm-windows). ::: -Для установки новых версий пакетов используйте одну из этих команд: +Для установки нового пакета используйте одну из следующих команд. Для их выполнения потребуются права администратора, если только npm не был установлен в системе через менеджер версий Node.js (например, n или nvm). -``` bash +```bash npm install -g @vue/cli # ИЛИ yarn global add @vue/cli diff --git a/docs/ru/guide/mode-and-env.md b/docs/ru/guide/mode-and-env.md index c6a8576674..424dd48efa 100644 --- a/docs/ru/guide/mode-and-env.md +++ b/docs/ru/guide/mode-and-env.md @@ -1,8 +1,38 @@ -# Переменные окружения и режимы работы +# Режимы работы и переменные окружения -Вы можете указать переменные окружения в специальных файлах в корне вашего проекта: +## Режимы работы + +**Режимы работы** — важная часть проектов Vue CLI. По умолчанию есть три режима работы: + +- `development` используется `vue-cli-service serve` +- `test` используется `vue-cli-service test:unit` +- `production` используется `vue-cli-service build` и `vue-cli-service test:e2e` + +Можно переопределять используемый для команды режим по умолчанию опцией `--mode`. Например, если необходимо использовать переменные для разработки в команде сборки: + +``` +vue-cli-service build --mode development +``` + +При запуске `vue-cli-service` загрузит переменные окружения из всех [соответствующих файлов](#переменные-окружения). Если в них не указана переменная `NODE_ENV`, то она установится соответствующим образом. Например, `NODE_ENV` будет установлена в `"production"` в режиме production, `"test"` в режиме test, а по умолчанию `"development"` в противном случае. + +Затем `NODE_ENV` определяет основной режим работы приложения — разработка, production или тестирование — и, следовательно, какую конфигурацию webpack требуется создавать. + +Например, для `NODE_ENV=test` Vue CLI создаёт конфигурацию webpack, которая оптимизирована и предназначена для модульных тестов. В ней не обрабатываются изображения и другие ресурсы, которые не требуются для модульных тестов. + +Аналогично, при `NODE_ENV=development` создаётся конфигурация webpack, которая включает горячую перезагрузку модулей (HMR), не добавляет хэши в имена файлов ресурсов и не создаёт сборку для вендоров, чтобы обеспечить быструю пересборку при запуске сервера разработки. + +При запуске `vue-cli-service build`, значение всегда должно быть `NODE_ENV=production` для получения приложения готового к публикации, независимо от окружения куда будет осуществляться публиковаться. + +::: warning Предупреждение об использовании NODE_ENV +Если в вашем окружении по умолчанию установлен `NODE_ENV`, необходимо либо удалить его, либо явно установить `NODE_ENV` при запуске команд `vue-cli-service`. +::: + +## Переменные окружения + +Переменные окружения можно указать в специальных файлах в корне проекта: -``` bash +```bash .env # загружается во всех случаях .env.local # загружается во всех случаях, игнорируется git .env.[mode] # загружается только в указанном режиме работы @@ -16,37 +46,21 @@ FOO=bar VUE_APP_SECRET=secret ``` -Эти переменные будут доступны для всех команд `vue-cli-service`, плагинов и зависимостей. +Обратите внимание, что только переменные с префиксом `VUE_APP_` будут статически внедряться в клиентскую сборку с помощью `webpack.DefinePlugin`. + +Подробнее о правилах парсинга env можно узнать [в документации `dotenv`](https://github.com/motdotla/dotenv#rules). Мы также используем [dotenv-expand](https://github.com/motdotla/dotenv-expand) для переменных расширения (доступно в Vue CLI 3.5+). + +Загруженные переменные станут доступны всем командам `vue-cli-service`, плагинам и зависимостям. ::: tip Приоритет загрузки переменных окружения Файл с переменными для определённого режима работы (например, `.env.production`) имеет более высокий приоритет, чем общий файл (например, `.env`). -Кроме того, переменные окружения, которые уже существуют при загрузке Vue CLI имеют наивысший приоритет и не будут перезаписаны значениями из файлов `.env`. -::: +Кроме того, переменные окружения, которые уже существуют при запуске Vue CLI имеют наивысший приоритет и не будут перезаписаны значениями из файлов `.env`. -::: warning Предупреждение об использовании NODE_ENV -Если в вашем окружении по умолчанию установлен `NODE_ENV`, вы должны либо удалить его, либо явно установить `NODE_ENV` при выполнении команд `vue-cli-service`. +Файлы `.env` загружаются при запуске `vue-cli-service`. При внесении изменений в файлы необходимо перезапустить службу. ::: -## Режимы работы - -**Режимы работы** — важная часть проектов Vue CLI. По умолчанию, есть три режима работы: - -- `development` используется `vue-cli-service serve` -- `production` используется `vue-cli-service build` и `vue-cli-service test:e2e` -- `test` используется `vue-cli-service test:unit` - -Обратите внимание, что режим работы отличается от `NODE_ENV`, поскольку режим может устанавливать несколько переменных окружения. Тем не менее, каждый режим устанавливает `NODE_ENV` в такое же значение по умолчанию — например, `NODE_ENV` будет установлен в `"development"` в режиме разработки. - -Вы можете установить переменные окружения только для определённого режима работы с помощью постфикса `.env` файла. Например, если создать файл с именем `.env.development` в корне вашего проекта, тогда переменные объявленные в нём будут загружаться только в режиме development. - -Вы можете переопределить режим по умолчанию для команды, с помощью опции `--mode`. Например, если необходимо использовать переменные для разработки в команде сборки, добавьте это в свои скрипты `package.json`: - -``` -"dev-build": "vue-cli-service build --mode development", -``` - -## Пример: режим Staging +### Пример: режим Staging Предположим, что у нас есть приложение с `.env` файлом: @@ -61,23 +75,23 @@ NODE_ENV=production VUE_APP_TITLE=My App (staging) ``` -- `vue-cli-service build` собирает приложение для production, загружает `.env`, `.env.production` и `.env.production.local` если они присутствуют; +- `vue-cli-service build` собирает приложение для production, загружает `.env`, `.env.production` и `.env.production.local` если они существуют; -- `vue-cli-service build --mode staging` собирает приложение для production в режиме staging, используя `.env`, `.env.staging` и `.env.staging.local` если они присутствуют. +- `vue-cli-service build --mode staging` собирает приложение для production в режиме staging, используя `.env`, `.env.staging` и `.env.staging.local` если они существуют. В обоих случаях приложение собирается для production из-за установленного `NODE_ENV`, но в режиме staging, `process.env.VUE_APP_TITLE` будет перезаписываться другим значением. -## Использование переменных окружения в клиентском коде +### Использование переменных окружения в клиентском коде -Только переменные с префиксом `VUE_APP_` статически внедряются в клиентскую сборку используя `webpack.DefinePlugin`. К ним можно получить доступ из кода вашего приложения: +Можно получить доступ к переменным окружения из кода приложения: -``` js +```js console.log(process.env.VUE_APP_SECRET) ``` На этапе сборки `process.env.VUE_APP_SECRET` будет заменяться соответствующим значением. Когда в файле указано `VUE_APP_SECRET=secret` — после сборки значением будет `"secret"`. -В дополнение к переменным `VUE_APP_*` также есть две специальные переменные, которые всегда доступны в коде вашего приложения: +В дополнение к переменным `VUE_APP_*` есть также две специальные переменные, которые всегда доступны в коде приложения: - `NODE_ENV` — значение будет `"development"`, `"production"` или `"test"` в зависимости от [режима работы](#режимы-работы) в котором работает приложение. - `BASE_URL` — соответствует опции `publicPath` в `vue.config.js` и определяет базовый путь по которому опубликовано ваше приложение. @@ -85,11 +99,19 @@ console.log(process.env.VUE_APP_SECRET) Все разрешённые переменные окружения также будут доступны внутри `public/index.html` как обсуждалось ранее в разделе [HTML - Интерполяции](./html-and-static-assets.md#интерпоnяции). ::: tip Совет -Можно добавлять вычисляемые переменные окружения в `vue.config.js`. Они по-прежнему должны именоваться с префикса `VUE_APP_`. Это может пригодиться например для получения информации о версии `process.env.VUE_APP_VERSION = require('./package.json').version` +Можно добавлять вычисляемые переменные окружения в `vue.config.js`. Они по-прежнему должны именоваться с префикса `VUE_APP_`. Может пригодиться для получения информации о версии + +```js +process.env.VUE_APP_VERSION = require('./package.json').version + +module.exports = { + // конфигурация +} +``` ::: -## Переменные только для локального окружения +### Переменные только для локального окружения -Иногда необходимы переменные окружения, которые не должны быть привязаны к кодовой базе, особенно если ваш проект размещается в публичном репозитории. В таком случае вы должны использовать файл `.env.local`. Локальные env-файлы добавлены в `.gitignore` по умолчанию. +Иногда необходимы переменные окружения, которые не должны быть привязаны к кодовой базе, особенно если проект размещается в публичном репозитории. В таком случае следует использовать файл `.env.local`. Локальные env-файлы добавлены в `.gitignore` по умолчанию. `.local` также могут добавляться к env-файлам специфичным для режима работы, например `.env.development.local` будет загружен во время разработки, и будет игнорироваться git. diff --git a/docs/ru/guide/plugins-and-presets.md b/docs/ru/guide/plugins-and-presets.md index 93ea96960e..6d8d2ee2a1 100644 --- a/docs/ru/guide/plugins-and-presets.md +++ b/docs/ru/guide/plugins-and-presets.md @@ -2,7 +2,7 @@ ## Плагины -Архитектура Vue CLI основана на плагинах. Если изучить `package.json` в свежесозданном проекте, то вы найдёте зависимости, имена которых начинаются с `@vue/cli-plugin-`. Такие плагины могут изменять внутреннюю конфигурацию webpack и внедрять команды в `vue-cli-service`. Большинство возможностей, упоминаемых при создании проекта, реализованы ими. +Vue CLI использует архитектуру на основе плагинов. Если изучить `package.json` в только что созданном проекте, можно обнаружить зависимости, которые начинаются с `@vue/cli-plugin-`. Плагины могут модифицировать внутреннюю конфигурацию webpack и внедрять команды в `vue-cli-service`. Большинство возможностей, перечисленных в процессе создания проекта, реализованы в виде плагинов. Основанная на плагинах архитектура позволяет Vue CLI оставаться гибкой и расширяемой. Если вы хотите создать собственный плагин — изучите [руководство по созданию плагинов](../dev-guide/plugin-dev.md). @@ -14,7 +14,7 @@ Каждый плагин для CLI поставляется с генератором (который создаёт файлы) и плагином для runtime (который меняет конфигурацию webpack и внедряет команды). Когда вы используете `vue create` для создания нового проекта, некоторые плагины будут уже предустановлены, в зависимости от вашего выбора необходимых возможностей. В случае, когда необходимо установить плагин в уже существующий проект, вы должны сделать это командой `vue add`: -``` bash +```bash vue add eslint ``` @@ -28,27 +28,27 @@ vue add eslint Команда `@vue/eslint` трансформируется в полное название пакета `@vue/cli-plugin-eslint`, устанавливает его из npm, и запускает его генератор. -``` bash +```bash # это аналогично предыдущей команде vue add cli-plugin-eslint ``` Без префикса `@vue` команда будет трансформировать название к публичному пакету. Например, чтобы установить сторонний плагин `vue-cli-plugin-apollo`: -``` bash +```bash # устанавливает и запускает vue-cli-plugin-apollo vue add apollo ``` Вы можете также использовать сторонние плагины со специфичным scope. Например, если плагин назван `@foo/vue-cli-plugin-bar`, то его можно добавить командой: -``` bash +```bash vue add @foo/bar ``` Можно передавать опции генерации в установленный плагин (для пропуска интерактивного выбора): -``` bash +```bash vue add eslint --config airbnb --lintOn save ``` @@ -102,7 +102,7 @@ vue add eslint --config airbnb --lintOn save Вот пример пресета настроек: -``` json +```json { "useConfigFiles": true, "cssPreprocessor": "sass", @@ -120,7 +120,7 @@ vue add eslint --config airbnb --lintOn save Информация из пресета настроек используется генераторами плагинов для создания в проекте соответствующих файлов. Кроме того, в дополнении к полям выше, возможно добавление дополнительных настроек для встроенных инструментов: -``` json +```json { "useConfigFiles": true, "plugins": {...}, @@ -139,7 +139,7 @@ vue add eslint --config airbnb --lintOn save Вы можете явно указать версии используемых плагинов: -``` json +```json { "plugins": { "@vue/cli-plugin-eslint": { @@ -160,7 +160,7 @@ vue add eslint --config airbnb --lintOn save Для таких случаев можно указать `"prompts": true` в настройках плагина, чтобы позволить пользователю сделать свой выбор: -``` json +```json { "plugins": { "@vue/cli-plugin-eslint": { @@ -181,23 +181,27 @@ vue add eslint --config airbnb --lintOn save После публикации репозитория, при создании проекта теперь можно указать опцию `--preset` для использования пресета из удалённого репозитория: -``` bash +```bash # использование пресета из репозитория GitHub vue create --preset username/repo my-project ``` GitLab и BitBucket также поддерживаются. Убедитесь, что используете опцию `--clone` при загрузке из стороннего репозитория: -``` bash +```bash vue create --preset gitlab:username/repo --clone my-project vue create --preset bitbucket:username/repo --clone my-project + +# self-hosted repos +vue create --preset gitlab:my-gitlab-server.com:group/projectname --clone my-project +vue create --preset direct:ssh://git@my-gitlab-server.com/group/projectname.git --clone my-project ``` ### Пресет из локального файла При разработке удалённого пресета настроек может часто требоваться отправлять пресет в удалённый репозиторий для его проверки. Для упрощения разработки можно использовать локальные пресеты напрямую. Vue CLI будет загружать локальные пресеты, если путь в значении `--preset` будет относительным или абсолютным, или заканчиваться на `.json`: -``` bash +```bash # ./my-preset должен быть каталогом, содержащим preset.json vue create --preset ./my-preset my-project diff --git a/docs/ru/guide/prototyping.md b/docs/ru/guide/prototyping.md index bd553be574..f60f4b2e13 100644 --- a/docs/ru/guide/prototyping.md +++ b/docs/ru/guide/prototyping.md @@ -2,7 +2,7 @@ Вы можете быстро создавать прототип в одном файле `*.vue` с помощью команд `vue serve` и `vue build`, но для них сначала потребуется глобально установить дополнительный плагин: -``` bash +```bash npm install -g @vue/cli-service-global # или yarn global add @vue/cli-service-global @@ -20,14 +20,15 @@ yarn global add @vue/cli-service-global Опции: - -o, --open Открыть в браузере - -c, --copy Скопировать локальный URL в буфер обмена - -h, --help Вывести информацию об использовании команды + -o, --open Открыть в браузере + -c, --copy Скопировать локальный URL в буфер обмена + -p, --port Используемый сервером порт (по умолчанию: 8080 или следующий свободный порт) + -h, --help Вывести информацию об использовании команды ``` Всё что вам потребуется — файл `App.vue`: -``` vue +```vue @@ -35,13 +36,13 @@ yarn global add @vue/cli-service-global Затем, в каталоге с файлом `App.vue`, выполните команду: -``` bash +```bash vue serve ``` `vue serve` использует такую же конфигурацию по умолчанию (webpack, babel, postcss & eslint) как и проекты создаваемые с помощью `vue create`. Он автоматически выбирает стартовый файл в текущем каталоге — этот файл может быть одним из `main.js`, `index.js`, `App.vue` или `app.vue`. Можно также явно указать стартовый файл: -``` bash +```bash vue serve MyComponent.vue ``` @@ -64,7 +65,7 @@ vue serve MyComponent.vue Вы можете собрать целевой файл в режиме production для публикации с помощью `vue build`: -``` bash +```bash vue build MyComponent.vue ``` diff --git a/docs/ru/guide/troubleshooting.md b/docs/ru/guide/troubleshooting.md new file mode 100644 index 0000000000..4e73a20b30 --- /dev/null +++ b/docs/ru/guide/troubleshooting.md @@ -0,0 +1,34 @@ +# Поиск и устранение неисправностей + +В это документе рассматриваются некоторые общие проблемы, касающиеся Vue CLI, и способы их решения. Прежде чем открывать новый issue, всегда выполняйте следующие действия. + +## Запуск установки через `sudo` или как `root` + +Если устанавливаете `@vue/cli-service` как пользователь `root` или с помощью `sudo`, то могут возникнуть проблемы при запуске скриптов `postinstall` пакета. + +Это функция безопасности npm. Вы всегда должны избегать запуска npm с привилегиями root, потому что сценарии установки скриптов могут быть непреднамеренно вредоносными. + +Однако, если необходимо, то можно обойти эту ошибку, установив флаг `--unsafe-perm` для npm. Это реализуется путём добавления префикса с переменной окружения к команде: + +```bash +npm_config_unsafe_perm=true vue create my-project +``` + +## Символические ссылки в `node_modules` + +Если есть зависимости, установленные через `npm link` или `yarn link`, ESLint (а иногда и Babel) могут работать некорректно для этих слинкованных зависимостей. Это происходит потому, что [по умолчанию webpack разрешает символические ссылки на их настоящее местоположение](https://webpack.js.org/configuration/resolve/#resolvesymlinks), таким образом ломая поиск конфигурации ESLint / Babel. + +Обходным решением этой проблемы будет отключение вручную разрешения символических ссылок в webpack: + +```js +// vue.config.js +module.exports = { + chainWebpack: (config) => { + config.resolve.symlinks(false) + } +} +``` + +::: warning ПРЕДУПРЕЖДЕНИЕ +Отключение `resolve.symlinks` может сломать горячую перезагрузку модулей, если ваши зависимости устанавливались сторонними npm-клиентами, использующие символические ссылки, такие как `cnpm` или `pnpm`. +::: diff --git a/docs/ru/guide/webpack.md b/docs/ru/guide/webpack.md index 9151be65cb..0dd02a874c 100644 --- a/docs/ru/guide/webpack.md +++ b/docs/ru/guide/webpack.md @@ -4,7 +4,7 @@ Самый простой способ изменять конфигурацию webpack — использовать объект в опции `configureWebpack` в файле `vue.config.js`: -``` js +```js // vue.config.js module.exports = { configureWebpack: { @@ -23,7 +23,7 @@ module.exports = { Если необходимо условное поведение, в зависимости от окружения, или вы хотите напрямую изменять конфигурацию — используйте функцию (будет лениво выполняться после установки переменных окружения). Она получает итоговую конфигурацию в качестве аргумента. Внутри функции можно напрямую изменить конфигурацию, ИЛИ вернуть объект для объединения: -``` js +```js // vue.config.js module.exports = { configureWebpack: config => { @@ -48,7 +48,7 @@ module.exports = { ### Изменение настроек загрузчика -``` js +```js // vue.config.js module.exports = { chainWebpack: config => { @@ -70,7 +70,7 @@ module.exports = { ### Добавление нового загрузчика -``` js +```js // vue.config.js module.exports = { chainWebpack: config => { @@ -89,7 +89,7 @@ module.exports = { Если вы хотите заменить существующий [базовый загрузчик](https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-service/lib/config/base.js), например воспользоваться `vue-svg-loader` для вставки SVG-файлов инлайн вместо загрузки обычными файлами: -``` js +```js // vue.config.js module.exports = { chainWebpack: config => { @@ -110,7 +110,7 @@ module.exports = { ### Изменение настроек плагина -``` js +```js // vue.config.js module.exports = { chainWebpack: config => { @@ -127,7 +127,7 @@ module.exports = { Например, предположим, необходимо изменить местоположение `index.html` по умолчанию с `/Users/test/proj/public/index.html` на `/Users/test/proj/app/templates/index.html`. По ссылке [html-webpack-plugin](https://github.com/jantimon/html-webpack-plugin#options) перечислен список параметров, которые можем передавать. Чтобы изменить шаблон, передадим новый путь к шаблону следующей конфигурацией: -``` js +```js // vue.config.js module.exports = { chainWebpack: config => { @@ -153,7 +153,7 @@ module.exports = { Вы можете перенаправить вывод в файл для более удобного изучения: -``` bash +```bash vue inspect > output.js ``` @@ -161,21 +161,21 @@ vue inspect > output.js Вы также можете указать подмножество конфигурации для проверки, указав путь: -``` bash +```bash # показать только первое правило vue inspect module.rules.0 ``` Или указать именованное правило или плагин: -``` bash +```bash vue inspect --rule vue vue inspect --plugin html ``` Наконец, вы можете вывести все именованные правила и плагины: -``` bash +```bash vue inspect --rules vue inspect --plugins ``` From 270530e2c4450ee86f1c7a8f4cfc0a62f6893d5b Mon Sep 17 00:00:00 2001 From: Alex Sokolov <4497128+Alex-Sokolov@users.noreply.github.com> Date: Wed, 21 Aug 2019 17:23:19 +0300 Subject: [PATCH 12/31] docs: [RU] Translation update --- docs/ru/core-plugins/pwa.md | 128 +++++++++++++++++++++ docs/ru/dev-guide/generator-api.md | 179 +++++++++++++++++++++++++++++ docs/ru/dev-guide/plugin-api.md | 132 +++++++++++++++++++++ docs/ru/guide/cli-service.md | 66 ++++++++--- 4 files changed, 488 insertions(+), 17 deletions(-) create mode 100644 docs/ru/core-plugins/pwa.md create mode 100644 docs/ru/dev-guide/generator-api.md create mode 100644 docs/ru/dev-guide/plugin-api.md diff --git a/docs/ru/core-plugins/pwa.md b/docs/ru/core-plugins/pwa.md new file mode 100644 index 0000000000..973a1b745e --- /dev/null +++ b/docs/ru/core-plugins/pwa.md @@ -0,0 +1,128 @@ +# @vue/cli-plugin-pwa + +> Плагин pwa для vue-cli + +Добавляемый этим плагином service worker включается только в production окружении (к примеру, только при запуске сборки через `npm run build` или `yarn build`). Использование service worker при разработке не рекомендуется, так как может привести к ситуации, когда используются кэшированные ранее ресурсы и не учитываются последние локальные изменения. + +Вместо этого в режиме разработки добавляется файл `noopServiceWorker.js`. Этот файл service worker является эффективным 'no-op', который сбрасывает любые другие service worker, зарегистрированные ранее для такой же комбинации host:port. + +При необходимости протестировать service worker локально, соберите приложение и запустите простой HTTP-сервер из каталога сборки. Рекомендуется использовать браузер в инкогнито-режиме для избежания осложнений с кэшем вашего браузера. + +## Конфигурация + +Конфигурация осуществляется через свойство `pwa` в файле `vue.config.js`, или через поле `"vue"` в файле `package.json`. + +- **pwa.workboxPluginMode** + + Выбор один из двух режимов, поддерживаемых используемым [`workbox-webpack-plugin`](https://developers.google.com/web/tools/workbox/modules/workbox-webpack-plugin). + + - `'GenerateSW'` (по умолчанию) создание нового файла service worker каждый раз при пересборке приложения. + + - `'InjectManifest'` использование существующего файла service worker и создание копии этого файла с внедрённым в него «precache manifest». + + Руководство «[Какой плагин использовать?](https://developers.google.com/web/tools/workbox/modules/workbox-webpack-plugin#which_plugin_to_use)» поможет выбрать один из двух режимов. + +- **pwa.workboxOptions** + + Настройки, передаваемые в используемый `workbox-webpack-plugin`. + + Для получения дополнительной информации о поддерживаемых значениях обратитесь к руководству для [`GenerateSW`](https://developers.google.com/web/tools/workbox/modules/workbox-webpack-plugin#full_generatesw_config) или для [`InjectManifest`](https://developers.google.com/web/tools/workbox/modules/workbox-webpack-plugin#full_injectmanifest_config). + +- **pwa.name** + + - По умолчанию: поле "name" в файле `package.json` + + Используется в качестве значения мета-тега `apple-mobile-web-app-title` в сгенерированном HTML. Обратите внимание, необходимо отредактировать файл `public/manifest.json` для соответствия этому значению. + +- **pwa.themeColor** + + - По умолчанию: `'#4DBA87'` + +- **pwa.msTileColor** + + - По умолчанию: `'#000000'` + +- **pwa.appleMobileWebAppCapable** + + - По умолчанию: `'no'` + + По умолчанию значение `'no'`, потому что iOS до версии 11.3 не имела надлежащей поддержки PWA. См. [эту статью](https://medium.com/@firt/dont-use-ios-web-app-meta-tag-irresponsibly-in-your-progressive-web-apps-85d70f4438cb) для более подробной информации. + +- **pwa.appleMobileWebAppStatusBarStyle** + + - По умолчанию: `'default'` + +- **pwa.assetsVersion** + + - По умолчанию: `''` + + Эта опция используется, если необходимо добавить версию к иконкам и манифесту для игнорирования кэша браузера. В результате добавится `?v=` к URL-адресам иконок и манифеста. + +- **pwa.manifestPath** + + - По умолчанию: `'manifest.json'` + + Путь к манифесту приложения. + +- **pwa.manifestOptions** + + - По умолчанию: `{}` + + Объект будет использоваться для генерации `manifest.json` + + Если не определить следующие значения в объекте, то вместо них будут использованы значения опции `pwa` или значения по умолчанию. + - name: `pwa.name` + - short_name: `pwa.name` + - start_url: `'.'` + - display: `'standalone'` + - theme_color: `pwa.themeColor` + +- **pwa.iconPaths** + + - По умолчанию: + + ```js + { + favicon32: 'img/icons/favicon-32x32.png', + favicon16: 'img/icons/favicon-16x16.png', + appleTouchIcon: 'img/icons/apple-touch-icon-152x152.png', + maskIcon: 'img/icons/safari-pinned-tab.svg', + msTileImage: 'img/icons/msapplication-icon-144x144.png' + } + ``` + + Измените эти значения при необходимости использовать различные пути для иконок. + +### Пример конфигурации + +```js +// Файл vue.config.js +module.exports = { + // ...настройки других vue-cli плагинов... + pwa: { + name: 'My App', + themeColor: '#4DBA87', + msTileColor: '#000000', + appleMobileWebAppCapable: 'yes', + appleMobileWebAppStatusBarStyle: 'black', + + // настройка workbox-плагина + workboxPluginMode: 'InjectManifest', + workboxOptions: { + // swSrc необходимо в режиме InjectManifest + swSrc: 'dev/sw.js', + // ...другие настройки Workbox... + } + } +} +``` + +## Установка в уже созданный проект + +```sh +vue add pwa +``` + +## Внедряемые правила webpack-chain + +- `config.plugin('workbox')` diff --git a/docs/ru/dev-guide/generator-api.md b/docs/ru/dev-guide/generator-api.md new file mode 100644 index 0000000000..3bd4a92b09 --- /dev/null +++ b/docs/ru/dev-guide/generator-api.md @@ -0,0 +1,179 @@ +# API генератора + +## cliVersion + +Тип: `string` + +Строка **глобальной** версии `@vue/cli`, вызывающей подключаемый плагин. + +## assertCliVersion + +- **Аргументы** + - `{integer | string} range` — semver диапазон, которому должна соответствовать `@vue/cli` + +- **Использование** + + Хотя `api.version` и может быть полезным, иногда приятнее просто объявить требуемую версию. Данный API предоставляет простой способ сделать это. + + Ничего не произойдёт, если предоставленная версия устраивает. В противном случае, будет выдана ошибка. + +## cliServiceVersion + +Тип: `string` + +Строка **локальной для проекта** версии `@vue/cli-service`, вызывающей подключаемый плагин. + +## assertCliServiceVersion + +- **Аргументы** + - `{integer | string} range` — semver диапазон, которому должна соответствовать `@vue/cli-service` + +- **Использование** + + Данный API предоставляет простой способ указания требуемой локальной версии `@vue/cli-service`. + + Ничего не произойдёт, если предоставленная версия устраивает. В противном случае, будет выдана ошибка. + + Примечание: Рекомендуется использовать [поле `peerDependencies` в файле `package.json`](https://docs.npmjs.com/files/package.json#peerdependencies) в большинстве случаев. + + +## resolve + +- **Аргументы** + - `{string} _path` — относительный путь от корня проекта + +- **Возвращает** + - `{string}` — разрешённый (resolved) абсолютный путь + +- **Использование**: +Разрешение пути для текущего проекта + +## hasPlugin + +- **Аргументы** + - `{string} id` — идентификатор плагина, можно опустить префикс (@vue/|vue-|@scope/vue)-cli-plugin- + - `{string} version` — semver диапазон, опционально + +- **Возвращает** + - `{boolean}` + +- **Использование**: +Проверяет есть ли в проекте плагин с указанным идентификатором. Если указан диапазон версий, то версия плагина должна соответствовать ему. + +## addConfigTransform + +- **Аргументы** + - `{string} key` — ключ конфигурации в package.json + - `{object} options` — настройки + - `{object} options.file` — дескриптор файла. Используется для поиска существующего файла. Каждый ключ определяет тип файла (возможные значения: `['js', 'json', 'yaml', 'lines']`). Значение представляет собой список имён файлов. Например: + + ```js + { + js: ['.eslintrc.js'], + json: ['.eslintrc.json', '.eslintrc'] + } + ``` + + По умолчанию первое имя файла будет использоваться для создания файла конфигурации. + +- **Возвращает** + - `{boolean}` + +- **Использование**: +Настройка способа извлечения конфигурации. + +## extendPackage + +- **Аргументы** + - `{object | () => object} fields` — поля для объединения + +- **Использование**: +Расширение `package.json` проекта. Вложенные поля объединяются, если не передавалось `{ merge: false }`. Также используется для разрешения конфликтов зависимостей между плагинами. Поля конфигурации инструмента могут быть извлечены в отдельные файлы до того, как файлы будут записаны на диск. + +## render + +- **Аргументы** + - `{string | object | FileMiddleware} source` — может быть одним из + - относительный путь к каталогу; + - хэш объект соответствий `{ sourceTemplate: targetFile }`; + - пользовательский файл с middleware функцией + - `{object} [additionalData]` — дополнительные данные, доступные для шаблонов + - `{object} [ejsOptions]` — настройки для ejs + +- **Использование**: +Рендер файлов шаблонов в дерево виртуальных файлов. + +## postProcessFiles + +- **Аргументы** + - `{FileMiddleware} cb` — файл middleware + +- **Использование**: +Добавление файла middleware, который будет выполняться после того, как все обычные middleware были выполнены. + +## onCreateComplete + +- **Аргументы** + - `{function} cb` + +- **Использование**: +Добавление коллбэка, который будет вызываться после записи файлов на диск. + +## exitLog + +- **Аргументы** + - `{} msg` — строка или значение для отображения после завершения генерации; + - `{('log'|'info'|'done'|'warn'|'error')} [type='log']` — тип сообщения. + +- **Использование**: +Добавление сообщения для отображения по завершении генерации (после любых других стандартных сообщений). + +## genJSConfig + +- **Аргументы** + - `{any} value` + +- **Использование**: +Удобный способ создания JS файла конфигурации из JSON + +## makeJSOnlyValue + +- **Аргументы** + - `{any} str` — JS выражение в виде строки + +- **Использование**: +Преобразует строковое выражение в исполняемый JS для конфигурационных .js файлов + +## injectImports + +- **Аргументы** + - `{string} file` — целевой файл для добавления импорта + - `{string | [string]} imports` — строка/массив импортов + +- **Использование**: +Добавление импортов в файл. + +## injectRootOptions + +- **Аргументы** + - `{string} file` — целевой файл для добавления опций + - `{string | [string]} options` — строка/массив опций + +- **Использование**: +Добавление опций в корневой экземпляр Vue (определяемый по `new Vue`). + +## entryFile + +- **Возвращает** + - `{('src/main.ts'|'src/main.js')}` + +- **Использование**: +Получение входного файла, с учётом использования typescript. + +## invoking + +- **Возвращает** + - `{boolean}` + +- **Использование**: +Проверка, вызван ли плагин. diff --git a/docs/ru/dev-guide/plugin-api.md b/docs/ru/dev-guide/plugin-api.md new file mode 100644 index 0000000000..287de8b9cd --- /dev/null +++ b/docs/ru/dev-guide/plugin-api.md @@ -0,0 +1,132 @@ +# API плагина + +## version + +Тип: `string` + +Строка с версией `@vue/cli-service` загружающей плагин. + +## assertVersion + +- **Аргументы** + - `{integer | string} range` — semver диапазон, которому должен соответствовать `@vue/cli-service` + +- **Использование** + + Хотя `api.version` и может быть полезным, иногда приятнее просто объявить требуемую версию. Данный API предоставляет простой способ сделать это. + + Ничего не произойдёт, если предоставленная версия устраивает. В противном случае, будет выдана ошибка. + + Примечание: Рекомендуется использовать [поле `peerDependencies` в файле `package.json`](https://docs.npmjs.com/files/package.json#peerdependencies) в большинстве случаев. + +## getCwd + +- **Использование**: +Возвращает текущий рабочий каталог + +## resolve + +- **Аргументы** + - `{string} path` — относительный путь от корня проекта + +- **Возвращает** + - `{string}` — разрешённый (resolved) абсолютный путь + +- **Использование**: +Разрешение пути для текущего проекта + +## hasPlugin + +- **Аргументы** + - `{string} id` — идентификатор плагина, можно опустить префикс (@vue/|vue-|@scope/vue)-cli-plugin- + +- **Возвращает** + - `{boolean}` + +- **Использование**: +Проверяет есть ли в проекте плагин с указанным идентификатором + +## registerCommand + +- **Аргументы** + - `{string} name` + - `{object} [opts]` + ```js + { + description: string, + usage: string, + options: { [string]: string } + } + ``` + - `{function} fn` + ```js + (args: { [string]: string }, rawArgs: string[]) => ?Promise + ``` + +- **Использование**: +Регистрация команды, доступной как `vue-cli-service [name]`. + +## chainWebpack + +- **Аргументы** + - `{function} fn` + +- **Использование**: +Регистрация функции, которая получит chainable-конфигурацию webpack. Эта функция ленива и не будет вызываться до вызова функции `resolveWebpackConfig`. + + +## configureWebpack + +- **Аргументы** + - `{object | function} fn` + +- **Использование**: +Регистрация объекта конфигурации webpack, который будет объединён с конфигурацией **ИЛИ** функция, которая получит исходную конфигурацию webpack. Функция может либо мутировать конфигурацию напрямую, либо возвращать объект, который будет объединён с конфигурацией webpack. + +## configureDevServer + +- **Аргументы** + - `{object | function} fn` + +- **Использование**: +Регистрация функции для конфигурирования сервера разработки. Она получает `app` экземпляр express сервера разработки. + +## resolveWebpackConfig + +- **Аргументы** + - `{ChainableWebpackConfig} [chainableConfig]` + +- **Возвращает** + - `{object}` — исходная конфигурация webpack + +- **Использование**: +Разрешение финальной конфигурации webpack, которая и будет передана в webpack. + +## resolveChainableWebpackConfig + +- **Возвращает** + - `{ChainableWebpackConfig}` + +- **Использование**: +Разрешение промежуточной chainable-конфигурации webpack, которую можно дополнительно настроить перед генерированием финальной конфигурации webpack. Можно вызывать несколько раз для генерации различных ветвей от базовой конфигурации webpack. + +Подробнее см. [https://github.com/mozilla-neutrino/webpack-chain](https://github.com/mozilla-neutrino/webpack-chain) + +## genCacheConfig + +- **Аргументы** + - `id` + - `partialIdentifier` + - `configFiles` + +- **Возвращает** + - `{object}` + ```js + { + cacheDirectory: string, + cacheIdentifier: string + } + ``` + +- **Использование**: +Генерация идентификатора кэша из нескольких переменных. diff --git a/docs/ru/guide/cli-service.md b/docs/ru/guide/cli-service.md index 47c7a8c7d7..f1963be69e 100644 --- a/docs/ru/guide/cli-service.md +++ b/docs/ru/guide/cli-service.md @@ -44,12 +44,14 @@ npx vue-cli-service serve Опции: - --open открыть браузер при запуске сервера - --copy скопировать url в буфер обмена при запуске сервера - --mode определить режим сборки (по умолчанию: development) - --host определить хост (по умолчанию: 0.0.0.0) - --port определить порт (по умолчанию: 8080) - --https использовать https (по умолчанию: false) + --open открыть браузер при запуске сервера + --copy скопировать url в буфер обмена при запуске сервера + --mode определить режим сборки (по умолчанию: development) + --host определить хост (по умолчанию: 0.0.0.0) + --port определить порт (по умолчанию: 8080) + --https использовать https (по умолчанию: false) + --public указать URL-адрес публичной сети для клиента HMR + --skip-plugins имёна плагинов через запятую, которые следует пропустить при запуске ``` ::: tip --copy @@ -69,17 +71,20 @@ npx vue-cli-service serve Опции: - --mode определить режим сборки (по умолчанию: production) - --dest определить каталог сборки (по умолчанию: dist) - --modern собирать приложение для современных браузеров с авто-фоллбэком для старых - --target app | lib | wc | wc-async (по умолчанию: app) - --formats список выходных форматов для сборок библиотек (по умолчанию: commonjs,umd,umd-min) - --inline-vue включить Vue в содержимое сборки библиотеки или веб-компонента - --name имя библиотеки или режим веб-компонента (по умолчанию: "name" в package.json или имя файла точки входа) - --no-clean не удалять каталог dist перед сборкой проекта - --report сгенерировать report.html для анализа содержимого сборки - --report-json сгенерировать report.json для анализа содержимого сборки - --watch отслеживать изменения + --mode определить режим сборки (по умолчанию: production) + --dest определить каталог сборки (по умолчанию: dist) + --modern собирать приложение для современных браузеров с авто-фоллбэком для старых + --no-unsafe-inline собирать приложение без внедрения инлайн-скриптов + --target app | lib | wc | wc-async (по умолчанию: app) + --formats список выходных форматов для сборок библиотек (по умолчанию: commonjs,umd,umd-min) + --inline-vue включить Vue в содержимое сборки библиотеки или веб-компонента + --name имя библиотеки или режим веб-компонента (по умолчанию: "name" в package.json или имя файла точки входа) + --filename имя выходного файла, только для 'lib' (по умолчанию: значение --name) + --no-clean не удалять каталог dist перед сборкой проекта + --report сгенерировать report.html для анализа содержимого сборки + --report-json сгенерировать report.json для анализа содержимого сборки + --skip-plugins имёна плагинов через запятую, которые следует пропустить при запуске + --watch отслеживать изменения ``` Команда `vue-cli-service build` создаёт готовую для production-сборку в каталоге `dist/` с минификацией для JS / CSS / HTML и автоматическим разделением вендорного кода в отдельный фрагмент для лучшего кэширования. Манифест фрагмента вставляется инлайн в HTML. @@ -118,6 +123,33 @@ npx vue-cli-service help npx vue-cli-service help [command] ``` +## Пропуск плагинов + +Иногда при выполнении команды может понадобиться не использовать определённый плагин CLI. К примеру, для создания сборки приложения без плагина PWA. Такого можно добиться передав имя плагина в опцию `--skip-plugins`. + +```bash +npx vue-cli-service build --skip-plugins pwa +``` + +::: tip СОВЕТ +Опция доступна для _любых_ команд `vue-cli-service`, включая пользовательские команды, добавленные другими плагинами. +::: + +Можно пропустить несколько подключаемых плагинов, передав их имена через запятую: + +```bash +npx vue-cli-service build --skip-plugins pwa,apollo +``` + +Имена плагинов разрешаются также, как и при установке, что подробнее описано [здесь](./plugins-and-presets.md#установка-пnагинов-в-существующий-проект) + +``` bash +# все вызовы равнозначны +npx vue-cli-service build --skip-plugins pwa +npx vue-cli-service build --skip-plugins @vue/pwa +npx vue-cli-service build --skip-plugins @vue/cli-plugin-pwa +``` + ## Кэширование и параллелизация - `cache-loader` используется для компиляции Vue / Babel / TypeScript по умолчанию. Файлы кэшируются внутри `node_modules/.cache` — если при запуске будут возникать проблемы с компиляцией, сначала попробуйте удалить каталог кэша. From 668d709444e5ad89356a325f0cea1335e0bea4e5 Mon Sep 17 00:00:00 2001 From: Alex Sokolov <4497128+Alex-Sokolov@users.noreply.github.com> Date: Thu, 28 Nov 2019 00:19:09 +0300 Subject: [PATCH 13/31] docs: vuex.md added --- docs/ru/core-plugins/vuex.md | 9 +++++++++ 1 file changed, 9 insertions(+) create mode 100644 docs/ru/core-plugins/vuex.md diff --git a/docs/ru/core-plugins/vuex.md b/docs/ru/core-plugins/vuex.md new file mode 100644 index 0000000000..d334e9e25e --- /dev/null +++ b/docs/ru/core-plugins/vuex.md @@ -0,0 +1,9 @@ +# @vue/cli-plugin-vuex + +> Плагин vuex для vue-cli + +## Установка в уже созданный проект + +```sh +vue add vuex +``` From 842fe8f9852e76aae8ab945618c218d570fc3b92 Mon Sep 17 00:00:00 2001 From: Alex Sokolov <4497128+Alex-Sokolov@users.noreply.github.com> Date: Thu, 28 Nov 2019 00:19:20 +0300 Subject: [PATCH 14/31] docs: router.md added --- docs/ru/core-plugins/router.md | 9 +++++++++ 1 file changed, 9 insertions(+) create mode 100644 docs/ru/core-plugins/router.md diff --git a/docs/ru/core-plugins/router.md b/docs/ru/core-plugins/router.md new file mode 100644 index 0000000000..2098948783 --- /dev/null +++ b/docs/ru/core-plugins/router.md @@ -0,0 +1,9 @@ +# @vue/cli-plugin-router + +> Плагин маршрутизации для vue-cli + +## Установка в уже созданный проект + +```sh +vue add router +``` From 0c61e7bc01c679659790bc5d93f51f32c226d7bf Mon Sep 17 00:00:00 2001 From: Alex Sokolov <4497128+Alex-Sokolov@users.noreply.github.com> Date: Thu, 28 Nov 2019 00:19:46 +0300 Subject: [PATCH 15/31] docs: migration from v3 added --- docs/ru/migrating-from-v3/README.md | 308 ++++++++++++++++++++++++++++ 1 file changed, 308 insertions(+) create mode 100644 docs/ru/migrating-from-v3/README.md diff --git a/docs/ru/migrating-from-v3/README.md b/docs/ru/migrating-from-v3/README.md new file mode 100644 index 0000000000..0169a1833f --- /dev/null +++ b/docs/ru/migrating-from-v3/README.md @@ -0,0 +1,308 @@ +--- +sidebar: auto +--- + +# Миграция с версии v3 + +Во-первых, установите последнюю версию Vue CLI глобально: + +```sh +npm install -g @vue/cli +# ИЛИ +yarn global add @vue/cli +``` + +## Обновление всех плагинов сразу + +In your existing projects, run: + +```sh +vue upgrade +``` + +And then see the following section for detailed breaking changes introduced in each package. + +------ + +## One-By-One Manual Migration + +If you want to migrate manually and gradually, here are the tips: + +### The Global `@vue/cli` + +#### [Redesigned](https://github.com/vuejs/vue-cli/pull/4090) `vue upgrade` + +- Before: `vue upgrade [patch | minor | major]`, and it does nothing more than installing the latest versions of Vue CLI plugins. +- After: `vue upgrade [plugin-name]`. Aside from upgrading the plugins, it can run migrators from plugins to help you automate the migration process. For more options for this command, please run `vue upgrade --help`. + +#### `vue --version` Output Format Change + +When running `vue --version`: + +- 3.x: outputs `3.12.0` +- 4.x: outputs `@vue/cli 4.0.0` + +#### Extra Confirmation Step To Avoid Overwriting + +When running `vue invoke` / `vue add` / `vue upgrade`, there's now an [extra confirmation step](https://github.com/vuejs/vue-cli/pull/4275) if you have uncommitted changes in the current repository. + +![image](https://user-images.githubusercontent.com/3277634/65588457-23db5a80-dfba-11e9-9899-9dd72efc111e.png) + +#### Vue Router and Vuex Now Have Corresponding CLI Plugins + +When running `vue add vuex` or `vue add router`: + +- In v3, only `vuex` or `vue-router` will be added to the project; +- In v4, there will also be `@vue/cli-plugin-vuex` or `@vue/cli-plugin-router` installed. + +This currently does not make an actual difference for end-users, but such design allows us to add more features for Vuex and Vue Router users later. + +For preset and plugin authors, there are several noteworthy changes in the two plugins: + +- The default directory structure was changed: + - `src/store.js` moved to `src/store/index.js`; + - `src/router.js` renamed to `src/router/index.js`; +- The `router` & `routerHistoryMode` options in `preset.json` are still supported for compatibility reasons. But it's now recommended to use `plugins: { '@vue/cli-plugin-router': { historyMode: true } }` for better consistency. +- `api.hasPlugin('vue-router')` is no longer supported. It's now `api.hasPlugin('router')`. + +### `@vue/cli-service` + +#### Whitespace handling in the template block + +To get a smaller bundle, we've disabled the `preserveWhitespace` option of `vue-template-compiler` by default in Vue CLI v3. + +This set comes with some caveats, however. + +Luckily, since the Vue 2.6 release, we can now have finer control over the whitespace handling, with the [new `whitespace` option](https://github.com/vuejs/vue/issues/9208#issuecomment-450012518). So we decided to switch over to use this new option by default in Vue CLI v4. + +Take the following template as an example: + +```html +

+ Welcome to Vue.js world. + Have fun! +

+``` + +With `preserveWhitespace: false`, all whitespaces between tags are removed, so it was compiled as: + +```html +

Welcome to Vue.jsworld. Have fun!

+``` + +With `whitespace: 'condense'`, it is now compiled as: + +```html +

Welcome to Vue.js world. Have fun!

+``` + +Note the **inline** whitespace between tags is now preserved. + +#### `vue-cli-service build --mode development` + +In the past, when running the `build` command in the `development` mode, the `dist` folder layout would be different from the `production` mode. Now with the following two changes, the directory structures across all modes would be the same (file names are still different - no hashes in `development` mode): + +- [#4323](https://github.com/vuejs/vue-cli/pull/4323) ensure consistent directory structure for all modes +- [#4302](https://github.com/vuejs/vue-cli/pull/4302) move dev configs into serve command + +#### For SASS/SCSS Users + +Previously in Vue CLI v3, we shipped with `sass-loader@7` by default. + +Recently `sass-loader@8` has been out and has changed its configuration format quite a lot. Here's the release notes: + +`@vue/cli-service` will continue to support `sass-loader@7` in v4, but we strongly recommend you to take a look at the v8 release and upgrade to the latest version. + +#### For Less Users + +`less-loader` v4 is incompatible with `less` >= v3.10, see . +It's strongly recommended to upgrade to `less-loader@5` if your project depends on it. + +#### For CSS Module Users + +- [Deprecate `css.modules` in favor of `css.requireModuleExtension`](https://github.com/vuejs/vue-cli/pull/4387). This is because we've upgraded to `css-loader` v3 and the config format has been changed. For a more detailed explanation please follow the link. + +#### `vue.config.js` options + +The already-deprecated [`baseUrl` option](https://cli.vuejs.org/config/#baseurl) is now [removed](https://github.com/vuejs/vue-cli/pull/4388) + +#### `chainWebpack` / `configureWebpack` + +##### The `minimizer` Method in `chainWebpack` + +If you've customized the internal rules with `chainWebpack`, please notice that `webpack-chain` was updated from v4 to v6, the most noticeable change is the `minimizer` config + +For example, if you want to enable the `drop_console` option in the terser plugin. +In v3, you may do this in `chainWebpack`: + +```js +const TerserPlugin = require('terser-webpack-plugin') +module.exports = { + chainWebpack: (config) => { + config.optimization.minimizer([ + new TerserPlugin({ terserOptions: { compress: { drop_console: true } } }) + ]) + } +} +``` + +In v4, it's changed to: + +```js +module.exports = { + chainWebpack: (config) => { + config.optimization.minimizer('terser').tap((args) => { + args[0].terserOptions.compress.drop_console = true + return args + }) + } +} +``` + +##### Other Changes + +- [The `pug-plain` rule was renamed to `pug-plain-loader`](https://github.com/vuejs/vue-cli/pull/4230) + +#### Underlying Loaders / Plugins + +Not likely to affect users unless you've customized their options via `chainWebpack` / `configureWebpack` + +`css-loader` was upgraded from v1 to v3: + +- [v2 changelog](https://github.com/webpack-contrib/css-loader/releases/tag/v2.0.0) +- [v3 changelog](https://github.com/webpack-contrib/css-loader/releases/tag/v3.0.0) + +Several other underlying webpack loaders and plugins have been upgraded, with mostly trivial changes: + +- `url-loader` [from v1 to v2](https://github.com/webpack-contrib/url-loader/releases/tag/v2.0.0) +- `file-loader` [from v3 to v4](https://github.com/webpack-contrib/file-loader/releases/tag/v4.0.0) +- `copy-webpack-plugin` [from v4 to v5](https://github.com/webpack-contrib/copy-webpack-plugin/blob/master/CHANGELOG.md#500-2019-02-20) +- `terser-webpack-plugin` [from v1 to v2](https://github.com/vuejs/vue-cli/pull/4676) + +### `@vue/cli-plugin-babel`, `@vue/babel-preset-app` + +#### core-js + +The babel plugin requires a peer dependency, for the polyfills used in the transpiled code. + +In Vue CLI v3, the required `core-js` version is 2.x, it is now upgraded to 3.x. + +This migration is automated if you upgrade it through `vue upgrade babel`. But if you have custom polyfills introduced, you may need to manually update the polyfill names (For more details, see [core-js changelog](https://github.com/zloirock/core-js/blob/master/CHANGELOG.md#L279-L297)). + +#### Babel Preset + +This migration is also automated if you upgrade it through `vue upgrade babel`. + +- In v3, the default babel preset used in `babel.config.js` is `@vue/app`. +- In v4, we moved it to the plugin, so now it's named as `@vue/cli-plugin-babel/preset` + +It is because that `@vue/babel-preset-app` is indeed an indirect dependency on the project. +It works because of npm's package hoisting. +But potential problems could still occur if the project has multiple conflicting indirect dependencies of the same package, or if the package manager puts stricter constraints on the dependency resolution (e.g. yarn plug'n'play or pnpm). +So we now moved it to the project's direct dependency (`@vue/cli-plugin-babel`) to make it more standard-compliant and less error-prone. + +------ + +### `@vue/cli-plugin-eslint` + +This plugin now [requires ESLint as a peer dependency](https://github.com/vuejs/vue-cli/pull/3852). + +This won't affect projects scaffolded with Vue CLI 3.1 or later. + +If your project was scaffolded with Vue CLI 3.0.x or earlier, you may need to add `eslint@4` to your project dependencies (This is automated if you upgrade the plugin using `vue upgrade eslint`). + +It's also recommended to upgrade your ESLint to v5, and ESLint config versions to the latest. (ESLint v6 support is still on the way) + +------ + +#### The Prettier Preset + +The old implementation of our prettier preset is flawed. We've updated the default template since Vue CLI v3.10. + +It now requires `eslint`, `eslint-plugin-prettier` and `prettier` as peer dependencies, following the [standard practice in the ESLint ecosystem](https://github.com/eslint/eslint/issues/3458). + +For older projects, if you encountered issues like `Cannot find module: eslint-plugin-prettier`, please run the following command to fix it: + +```sh +npm install --save-dev eslint@5 @vue/eslint-config-prettier@5 eslint-plugin-prettier prettier +``` + +------ + +#### `lintOnSave` options + +(the following only affects development) + +The default value of `lintOnSave` option (when not specified) was [changed from `true` to `'default'`](https://github.com/vuejs/vue-cli/pull/3975). You can read more on the detailed explanation in the [documentation](https://cli.vuejs.org/config/#lintonsave). + +In a nutshell: + +- In v3, by default, lint warnings, along with errors, will be displayed in the error overlay +- In v4, by default, only lint errors will interrupt your development process. Warnings are only logged in the terminal console. + +### `@vue/cli-plugin-pwa` + +The underlying workbox-webpack-plugin has been upgraded from v3 to v4. See [the release notes here](https://github.com/GoogleChrome/workbox/releases/tag/v4.0.0). + +There's also a `pwa.manifestOptions` field available (you can set it in the `vue.config.js`). With this new option, `manifest.json` will be generated from the config object rather than directly copied from the `public` folder. This provides a more consistent interface to manage your PWA configurations. (Note, it is an opt-in feature. Related PRs: [#2981](https://github.com/vuejs/vue-cli/pull/2981), [#4664](https://github.com/vuejs/vue-cli/pull/4664)) + +### `@vue/cli-plugin-e2e-cypress` + +Before Vue CLI v3.0.0-beta.10, the default command for E2E testing was `vue-cli-service e2e`. Later we changed it to `vue-cli-service test:e2e`. The previous command was since deprecated but still supported. +We have now completely [dropped support for this legacy command](https://github.com/vuejs/vue-cli/pull/3774). + +### `@vue/cli-plugin-e2e-nightwatch` + +Nightwatch.js has been upgraded from 0.9 to 1.x. Be sure to read the [Nightwatch migration guides](https://github.com/nightwatchjs/nightwatch/wiki/Migrating-to-Nightwatch-1.0) first. + +The bundled config and generated tests [have been completely overhauled](https://github.com/vuejs/vue-cli/pull/4541). Please follow the link for more details. Most use cases in Vue CLI v3 are still supported. They are just new features. + +As ChromeDriver has changed its version strategy since version 73, we've made it a peer dependency in the project. +A simple browser version check is implemented in the plugin, so if you've upgraded to an incompatible version of Chrome, there will be a warning to prompt you to upgrade the depended ChromeDriver version. + +------ + +As in the cypress plugin, the support for legacy `vue-cli-service e2e` command has also been removed. + +### `@vue/cli-plugin-typescript` + +When using Typescript, the webpack resolve options now [prefer `ts(x)` file extensions over `js(x)` ones](https://github.com/vuejs/vue-cli/pull/3909). + +### `@vue/cli-plugin-unit-jest` + +We've upgraded the bundled Jest from v23 to v24, so please read their [release notes](https://jestjs.io/blog/2019/01/25/jest-24-refreshing-polished-typescript-friendly) first. +Follow [this link](https://github.com/facebook/jest/blob/20ba4be9499d50ed0c9231b86d4a64ec8a6bd303/CHANGELOG.md#user-content-2400) for the full changelog. + +The `unit-jest` plugin now comes with 4 configuration presets: + +- `@vue/cli-plugin-unit-jest` The default preset for the most common type of projects +- `@vue/cli-plugin-unit-jest/presets/no-babel` If you don't have `@vue/cli-plugin-babel` installed and don't want to see babel files in the project +- `@vue/cli-plugin-unit-jest/presets/typescript` The preset with TypeScript support (but no TSX support) +- `@vue/cli-plugin-unit-jest/presets/typescript-and-babel` The preset with TypeScript (and TSX) and babel support. + +If you haven't changed the default Jest configurations (lies in either `jest.config.js` or the `jest` field in `package.json`) ever since project creation, you can now replace the massive configuration object with one single field: + +```js +module.exports = { + // Replace the following preset name with the one you want to use from the above list + preset: '@vue/cli-plugin-unit-jest' +} +``` + +(the `ts-jest`, `babel-jest` dependencies can also be removed after migrating config to use presets) + +::: tip A Reminder +The default test environment in the new presets is jsdom@15, which differs from the default one in Jest 24 (jsdom@11). +This is to be aligned with the upcoming Jest 25 updates. +Most users won't be affected by this change. +For a detailed changelog with regard to jsdom, see +::: + +### `@vue/cli-plugin-unit-mocha` + +- Use mochapack instead of mocha-webpack, see changelog at . This change is not likely to affect actual usage. +- Upgraded to mocha 6, see [Mocha's changelog](https://github.com/mochajs/mocha/blob/master/CHANGELOG.md#600-0--2019-01-01) for more details. + +### `@vue/cli-service-global` + +See breaking changes in the [`@vue/cli-service`](#vue-cli-service) & [`@vue/cli-plugin-eslint`](#vue-cli-plugin-eslint) packages. From cd09d5981eaf752d22c6814857743670aad5608f Mon Sep 17 00:00:00 2001 From: Alex Sokolov <4497128+Alex-Sokolov@users.noreply.github.com> Date: Thu, 28 Nov 2019 00:20:14 +0300 Subject: [PATCH 16/31] docs: config.js updated --- docs/.vuepress/config.js | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index 2033310066..8f701a0198 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -271,7 +271,14 @@ module.exports = { }, { text: 'Плагины', - link: '/ru/core-plugins/' + items: [ + { text: 'Основные плагины', link: '/ru/core-plugins/' }, + { text: 'Просмотр плагинов', link: 'https://awesomejs.dev/for/vue-cli/' } + ] + }, + { + text: 'Миграция с v3', + link: '/ru/migrating-from-v3/' }, { text: 'История изменений', From e52b0f15744c066c07a47ae056746e1cc2781821 Mon Sep 17 00:00:00 2001 From: Alex Sokolov <4497128+Alex-Sokolov@users.noreply.github.com> Date: Thu, 28 Nov 2019 00:22:02 +0300 Subject: [PATCH 17/31] docs: config/readme.md updated --- docs/ru/config/README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/ru/config/README.md b/docs/ru/config/README.md index 57bd73d634..c980c23767 100644 --- a/docs/ru/config/README.md +++ b/docs/ru/config/README.md @@ -275,6 +275,8 @@ module.exports = { Извлечение CSS отключено по умолчанию в режиме `development`, поскольку оно несовместимо с горячей перезагрузкой CSS. Тем не менее, вы всё равно можете принудительно использовать извлечение стилей всегда, установив значение в `true`. + Вместо `true` также можно передать объект с настройками для [mini-css-extract-plugin](https://github.com/webpack-contrib/mini-css-extract-plugin) если необходимо детальнее настроить работу этого плагина. + ### css.sourceMap - Тип: `boolean` From 2a1851c4f2b43e9e401aff51711c2af48d5d1336 Mon Sep 17 00:00:00 2001 From: Alex Sokolov <4497128+Alex-Sokolov@users.noreply.github.com> Date: Thu, 28 Nov 2019 00:22:21 +0300 Subject: [PATCH 18/31] docs: unit-mocha.md updated --- docs/ru/core-plugins/unit-mocha.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/ru/core-plugins/unit-mocha.md b/docs/ru/core-plugins/unit-mocha.md index 0dff4ba3fb..d295f3a6e1 100644 --- a/docs/ru/core-plugins/unit-mocha.md +++ b/docs/ru/core-plugins/unit-mocha.md @@ -6,7 +6,7 @@ - **`vue-cli-service test:unit`** - Запускает тесты с помощью [mocha-webpack](https://github.com/zinserjan/mocha-webpack) + [chai](http://chaijs.com/). + Запускает тесты с помощью [mochapack](https://github.com/sysgears/mochapack) + [chai](http://chaijs.com/). **Обратите внимание, что тесты запускаются в Node.js с симулированным JSDOM окружением браузера.** @@ -27,7 +27,7 @@ По умолчанию под файлы тестов попадают: любые файлы `tests/unit` которые заканчиваются на `.spec.(ts|js)`. - Поддерживаются все [опции командной строки mocha-webpack](http://zinserjan.github.io/mocha-webpack/docs/installation/cli-usage.html). + Поддерживаются все [опции командной строки mochapack](https://sysgears.github.io/mochapack/docs/installation/cli-usage.html). ## Установка в уже созданный проект From 7959255590d37c85cbf1a455a771f9161a7ad5a2 Mon Sep 17 00:00:00 2001 From: Alex Sokolov <4497128+Alex-Sokolov@users.noreply.github.com> Date: Thu, 28 Nov 2019 00:22:56 +0300 Subject: [PATCH 19/31] docs: css.md updated --- docs/ru/guide/css.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/ru/guide/css.md b/docs/ru/guide/css.md index cf03cf216f..1e667dda2b 100644 --- a/docs/ru/guide/css.md +++ b/docs/ru/guide/css.md @@ -114,9 +114,9 @@ module.exports = { // Для пользователей Vue CLI v3, обратитесь к документации css-loader v1 // https://github.com/webpack-contrib/css-loader/tree/v1.0.1 modules: { - localIdentName: '[name]-[hash]', - localsConvention: 'camelCaseOnly' - } + localIdentName: '[name]-[hash]' + }, + localsConvention: 'camelCaseOnly' } } } @@ -135,8 +135,9 @@ module.exports = { // передача настроек в sass-loader // @/ это псевдоним к каталогу src/ поэтому предполагается, // что у вас в проекте есть файл `src/variables.scss` + // Примечание: эта опция называется "data" в sass-loader v7 sass: { - data: `@import "~@/variables.sass"` + prependData: `@import "~@/variables.sass"` }, // по умолчанию опция `sass` будет применяться к обоим синтаксисам // потому что синтаксис `scss` по сути также обрабатывается sass-loader @@ -144,7 +145,7 @@ module.exports = { // в конце оператора, в то время как для `sass` точки с запятой не требуется // в этом случае синтаксис `scss` можно настроить отдельно с помощью опции `scss` scss: { - data: `@import "~@/variables.scss";` + prependData: `@import "~@/variables.scss";` }, // передача настроек Less.js в less-loader less:{ From 230fea77f863c6152376cc7c285842f271c4c358 Mon Sep 17 00:00:00 2001 From: Alex Sokolov <4497128+Alex-Sokolov@users.noreply.github.com> Date: Thu, 28 Nov 2019 00:23:15 +0300 Subject: [PATCH 20/31] docs: cli-service.md updated --- docs/ru/guide/cli-service.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/ru/guide/cli-service.md b/docs/ru/guide/cli-service.md index f1963be69e..20ffeec0ca 100644 --- a/docs/ru/guide/cli-service.md +++ b/docs/ru/guide/cli-service.md @@ -62,7 +62,7 @@ npx vue-cli-service serve Кроме флагов командной строки, также можно настраивать сервер для разработки с помощью поля [devServer](../config/#devserver) в файле `vue.config.js`. -В команде CLI `[entry]` означает *входной файл*, а не *дополнительный входной файл*. Если вы перезапишете запись в CLI, тогда записи из `config.pages` больше не будут учитываться, что может привести к ошибке. +В команде CLI `[entry]` означает *входной файл*, а не *дополнительный входной файл*. Если вы перезапишете запись в CLI, тогда записи из `config.pages` больше не будут учитываться, что может привести к ошибке. По умолчанию [entryFile](../dev-guide/generator-api.html#entryfile). ## vue-cli-service build @@ -143,7 +143,7 @@ npx vue-cli-service build --skip-plugins pwa,apollo Имена плагинов разрешаются также, как и при установке, что подробнее описано [здесь](./plugins-and-presets.md#установка-пnагинов-в-существующий-проект) -``` bash +```bash # все вызовы равнозначны npx vue-cli-service build --skip-plugins pwa npx vue-cli-service build --skip-plugins @vue/pwa @@ -164,6 +164,12 @@ npx vue-cli-service build --skip-plugins @vue/cli-plugin-pwa { "gitHooks": { "pre-commit": "lint-staged" + }, + "lint-staged": { + "*.{js,vue}": [ + "vue-cli-service lint", + "git add" + ] } } ``` From f1eef4655517c064eb6be3b3757f0198169bd7ab Mon Sep 17 00:00:00 2001 From: Alex Sokolov <4497128+Alex-Sokolov@users.noreply.github.com> Date: Thu, 28 Nov 2019 00:25:29 +0300 Subject: [PATCH 21/31] docs: generator-api.md updated --- docs/ru/dev-guide/generator-api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/ru/dev-guide/generator-api.md b/docs/ru/dev-guide/generator-api.md index 3bd4a92b09..48c17269e6 100644 --- a/docs/ru/dev-guide/generator-api.md +++ b/docs/ru/dev-guide/generator-api.md @@ -40,10 +40,10 @@ ## resolve - **Аргументы** - - `{string} _path` — относительный путь от корня проекта + - `{string} ..._paths` — Последовательность относительных путей или сегментов пути - **Возвращает** - - `{string}` — разрешённый (resolved) абсолютный путь + - `{string}` — разрешённый (resolved) абсолютный путь, вычисленный на основе текущего корня проекта - **Использование**: Разрешение пути для текущего проекта From 3b74f8231b838b90ede8673ae277238406fabfc9 Mon Sep 17 00:00:00 2001 From: Alex Sokolov <4497128+Alex-Sokolov@users.noreply.github.com> Date: Thu, 28 Nov 2019 00:39:20 +0300 Subject: [PATCH 22/31] docs: build-target.md update --- docs/ru/guide/build-targets.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/docs/ru/guide/build-targets.md b/docs/ru/guide/build-targets.md index 46bb4dae2b..c279d4f41b 100644 --- a/docs/ru/guide/build-targets.md +++ b/docs/ru/guide/build-targets.md @@ -50,6 +50,10 @@ dist/myLib.css 0.33 kb 0.23 kb - `dist/myLib.css`: извлечённый CSS-файл (можно принудительно вставлять стили инлайн, установив `css: { extract: false }` в `vue.config.js`) +::: warning ВНИМАНИЕ +При разработке библиотеки или использования монорепозитория, имейте ввиду, что CSS-импорты **являются побочными эффектами (side effects)**. Убедитесь, что **удалили** опцию `"sideEffects": false` из файла `package.json`, в противном случае webpack будет удалять CSS-фрагменты при сборке для production. +::: + ### Vue vs. JS / TS файлы точек входа При использовании `.vue` файла в качестве точки входа, библиотека будет экспортировать сам компонент Vue, потому что компонент всегда имеет экспорт по умолчанию (export default). @@ -142,3 +146,21 @@ dist/foo.1.js 5.24 kb 1.64 kb ``` + +## Использование vuex в сборках + +При создании [Веб-компонента](#веб-компонент-web-component) или [Библиотеки](#бибnиотека-library), точкой входа будет не `main.js`, а файл `entry-wc.js`, генерируемый здесь: [https://github.com/vuejs/vue-cli/blob/dev/packages/%40vue/cli-service/lib/commands/build/resolveWcEntry.js](https://github.com/vuejs/vue-cli/blob/dev/packages/%40vue/cli-service/lib/commands/build/resolveWcEntry.js) + +Поэтому для использования vuex при сборке веб-компонента необходимо инициализировать хранилище в `App.vue`: + +```js +import store from './store' + +// ... + +export default { + store, + name: 'App', + // ... +} +``` From 4d9342ba3aa2a5466a16200aca60a5cc37659110 Mon Sep 17 00:00:00 2001 From: Alex Sokolov <4497128+Alex-Sokolov@users.noreply.github.com> Date: Thu, 28 Nov 2019 00:47:56 +0300 Subject: [PATCH 23/31] docs: deployment.md update --- docs/ru/guide/deployment.md | 42 +++++++++++++++++++++---------------- 1 file changed, 24 insertions(+), 18 deletions(-) diff --git a/docs/ru/guide/deployment.md b/docs/ru/guide/deployment.md index 246ea1d69a..177a9a8f26 100644 --- a/docs/ru/guide/deployment.md +++ b/docs/ru/guide/deployment.md @@ -125,6 +125,8 @@ pages: # задание должно быть именованными стра - npm run build - mv public public-vue # GitLab Pages хук для каталога public - mv dist public # переименование каталога dist (результат команды npm run build) + # опционально, можно активировать поддержку gzip с помощью следующей строки: + - find public -type f -regex '.*\.\(htm\|html\|txt\|text\|js\|css\)$' -exec gzip -f -k {} \; artifacts: paths: - public # путь к артефакту должен быть /public для GitLab Pages @@ -132,15 +134,14 @@ pages: # задание должно быть именованными стра - master ``` -Как правило, по адресу `https://yourUserName.gitlab.io/yourProjectName` будет располагаться статический веб-сайт, поэтому вы также захотите создать файл `vue.config.js` для указания [значения `BASE_URL`](../config/#publicpath), соответствующего ему: +Как правило, по адресу `https://yourUserName.gitlab.io/yourProjectName` будет располагаться статический веб-сайт, поэтому потребуется создать файл `vue.config.js` для указания [значения `BASE_URL`](../config/#publicpath), соответствующего имени проекта ([переменная окружения `CI_PROJECT_NAME`](https://docs.gitlab.com/ee/ci/variables/predefined_variables.html) содержит его): ```javascript // файл vue.config.js расположен в корне вашего репозитория -// убедитесь, что обновили `yourProjectName` на имя вашего проекта GitLab module.exports = { publicPath: process.env.NODE_ENV === 'production' - ? '/yourProjectName/' + ? '/' + process.env.CI_PROJECT_NAME + '/' : '/' } ``` @@ -260,14 +261,16 @@ firebase deploy --only hosting ### Now +В данном примере используется последняя версия платформы Now версии 2. + 1. Установите Now CLI: - ```bash - npm install -g now +```bash +npm install -g now - # Или если предпочитаете локальную установку - npm install now - ``` +# Или если предпочитаете локальную установку +npm install now +``` 2. Добавьте файл `now.json` в корневой каталог проекта: @@ -326,9 +329,9 @@ firebase deploy --only hosting "now-build": "npm run build" ``` - Для публикации запустите `now`. + Для публикации запустите `now`. - Если необходим псевдоним публикации, запустите `now --target production`. + Если необходим псевдоним публикации, запустите `now --target production`. ### Stdlib @@ -434,14 +437,17 @@ Deploy your application using nginx inside of a docker container. 2. Создайте файл `Dockerfile` в корневом каталоге проекта - ```Dockerfile - FROM node:10 - COPY ./ /app + ```docker + FROM node:latest as build-stage WORKDIR /app - RUN npm install && npm run build - FROM nginx + COPY package*.json ./ + RUN npm install + COPY ./ . + RUN npm run build + + FROM nginx as production-stage RUN mkdir /app - COPY --from=0 /app/dist /app + COPY --from=build-stage /app/dist /app COPY nginx.conf /etc/nginx/nginx.conf ``` @@ -449,7 +455,7 @@ Deploy your application using nginx inside of a docker container. Настройка файла `.dockerignore` предотвращает копирование `node_modules` и любых промежуточных артефактов сборки в образ, что может вызывать проблемы при сборке. - ```gitignore + ``` **/node_modules **/dist ``` @@ -460,7 +466,7 @@ Deploy your application using nginx inside of a docker container. Ниже приведена простая конфигурация `nginx`, которая обслуживает ваш vue-проект на порту `80`. Корневой `index.html` служит для `page not found` / `404` ошибок, что позволяет использовать маршрутизации, основанной на `pushState()`. - ```text + ```nginx user nginx; worker_processes 1; error_log /var/log/nginx/error.log warn; From 23f88f148b5dd12a5a54c5ff79ad955f157a3509 Mon Sep 17 00:00:00 2001 From: Alex Sokolov <4497128+Alex-Sokolov@users.noreply.github.com> Date: Thu, 28 Nov 2019 11:04:53 +0300 Subject: [PATCH 24/31] docs: e2e-nightwatch.md update --- docs/ru/core-plugins/e2e-nightwatch.md | 128 ++++++++++++++++++++++--- 1 file changed, 116 insertions(+), 12 deletions(-) diff --git a/docs/ru/core-plugins/e2e-nightwatch.md b/docs/ru/core-plugins/e2e-nightwatch.md index 1bcaa266c7..dc6ab441d7 100644 --- a/docs/ru/core-plugins/e2e-nightwatch.md +++ b/docs/ru/core-plugins/e2e-nightwatch.md @@ -6,32 +6,136 @@ - **`vue-cli-service test:e2e`** - Запускает E2E тесты с помощью [NightwatchJS](http://nightwatchjs.org). + Запускает E2E тесты с помощью [Nightwatch.js](https://nightwatchjs.org). Опции: ``` - --url запуск E2E тестов по указанному URL, вместо авто-запуска сервера - --config использовать пользовательский файл конфигурации nightwatch (перезаписывает внутренние настройки) - -e, --env указанные через запятую окружения браузеров, в которых требуется запуск (по умолчанию: chrome) - -t, --test указать запускаемый тест по имени - -f, --filter glob для фильтрации тестов по имени файла + --url запуск E2E тестов по указанному URL, вместо авто-запуска сервера + --config использовать пользовательский файл конфигурации nightwatch (перезаписывает внутренние настройки) + --headless использовать chrome или firefox в безголовом (headless) режиме + --parallel использовать параллельный режим через test workers (доступно только в chromedriver) + --use-selenium использовать сервер Selenium вместо chromedriver или geckodriver + -e, --env указанные через запятую окружения браузеров, в которых требуется запуск (по умолчанию: chrome) + -t, --test указать запускаемый тест по имени + -f, --filter glob для фильтрации тестов по имени файла ``` - > Примечание: этот плагин в настоящее время использует Nightwatch v0.9.x. Мы ждём стабильного релиза Nightwatch 1.0 для обновления. + Также [поддерживаются все опции Nightwatch CLI](https://nightwatchjs.org/guide/running-tests/#command-line-options). Например: `--verbose`, `--retries` и т.д. - Дополнительно, [все опции Nightwatch CLI поддерживаются](https://nightwatchjs.org/guide#command-line-options). +## Структура проекта -## Конфигурация +При установке плагина генерируется следующая структура каталогов. В ней уже будут примеры для большинства концептов тестирования, доступных в Nightwatch. + +``` +tests/e2e/ + ├── custom-assertions/ + | └── elementCount.js + ├── custom-commands/ + | ├── customExecute.js + | ├── openHomepage.js + | └── openHomepageClass.js + ├── page-objects/ + | └── homepage.js + ├── specs/ + | ├── test.js + | └── test-with-pageobjects.js + └── globals.js +``` -Nightwatch предварительно сконфигурирован для запуска в Chrome по умолчанию. Если необходимо запустить E2E тесты в других браузерах — потребуется добавить `nightwatch.config.js` или `nightwatch.json` в корневой каталог проекта и указать там дополнительные браузеры. Конфигурация будет объединена с [внутренней конфигурацией Nightwatch](https://github.com/vuejs/vue-cli/blob/dev/packages/%40vue/cli-plugin-e2e-nightwatch/nightwatch.config.js). +#### `specs` +Основное место расположения тестов. Может содержать вложенные каталоги, которые возможно выбирать при запуске с помощью аргумента `--group`. [Подробнее](https://nightwatchjs.org/guide/running-tests/#test-groups). -Кроме того, можно полностью заменить внутреннюю конфигурацию на пользовательский конфигурационный файл с помощью опции `--config`. +#### `custom-assertions` +Расположенные здесь файлы будут автоматически загружаться Nightwatch и добавляться в API `.assert` и `.verify` для расширения встроенных методов проверок Nightwatch. Подробнее в документации [по созданию пользовательских утверждений (assertions)](https://nightwatchjs.org/guide/extending-nightwatch/#writing-custom-assertions). -Обратитесь к документации Nightwatch для получения информации о [параметрах конфигурации](http://nightwatchjs.org/gettingstarted#settings-file) и о том, как [установить драйверы браузера](http://nightwatchjs.org/gettingstarted#browser-drivers-setup). +#### `custom-commands` +Расположенные здесь файлы будут автоматически загружаться Nightwatch и добавляться в API объекта `browser` для расширения встроенных команд Nightwatch. Подробнее в документации [по созданию пользовательских команд](https://nightwatchjs.org/guide/extending-nightwatch/#writing-custom-commands). + +#### `page objects` +Работа с объектами страниц — популярная методология в end-to-end UI тестировании. Расположенные здесь файлы будут автоматически добавляться в API `.page`, при этом имя файла определит имя объекта страницы. Подробнее в документации [по работе с объектами страниц](https://nightwatchjs.org/guide/working-with-page-objects/). + +#### `globals.js` +Файл с внешними глобальными переменными, который может содержать глобальные свойства или хуки. Подробнее в документации [по глобальным свойствам тестов](https://nightwatchjs.org/gettingstarted/configuration/#test-globals). ## Установка в уже созданный проект ```sh vue add e2e-nightwatch ``` + +## Конфигурация + +Nightwatch предварительно сконфигурирован для запуска в Chrome по умолчанию. Доступен также Firefox через `--env firefox`. При необходимости запускать end-to-end тесты в других браузерах (например, Safari, Microsoft Edge), нужно добавить `nightwatch.conf.js` или `nightwatch.json` в корневой каталог проекта для настройки дополнительных браузеров. Конфигурация будет объединена во [внутреннюю конфигурацию Nightwatch](https://github.com/vuejs/vue-cli/blob/dev/packages/%40vue/cli-plugin-e2e-nightwatch/nightwatch.config.js). + +При необходимости можно полностью заменить внутреннюю конфигурацию собственной с помощью опции `--config`. + +Обратитесь к документации Nightwatch для информации о [параметрах конфигурации](https://nightwatchjs.org/gettingstarted/configuration/) и как [устанавливать драйверы браузеров](http://nightwatchjs.org/gettingstarted#browser-drivers-setup). + +## Запуск тестов + +По умолчанию, все тесты внутри каталога `specs` будут запускаться с использованием Chrome. Если необходимо запустить end-to-end тесты в безголовом (headless) режиме в Chrome (или Firefox), укажите аргумент `--headless`. + +```sh +$ vue-cli-service test:e2e +``` + +**Запуск одного теста** + +Для запуска одного теста укажите путь к файлу. Например: + +```sh +$ vue-cli-service test:e2e tests/e2e/specs/test.js +``` + +**Пропустить автоматический запуск сервера разработки** + +Если сервер разработки уже запущен и необходимо пропустить автоматический запуск, укажите аргумент `--url`: + +```sh +$ vue-cli-service test:e2e --url http://localhost:8080/ +``` + +**Запуск тестов в Firefox** + +По умолчанию также поддерживается запуск тестов в Firefox. Выполните следующую команду (опционально можно добавить `--headless` для запуска Firefox в безголовом режиме): + +```sh +$ vue-cli-service test:e2e --env firefox [--headless] +``` + +**Запуск тестов в Firefox и Chrome одновременно** + +Можно запускать тесты одновременно в обоих браузерах, определяя требуемые тестовые окружения через запятую (",") — не используя пробелы. + +```sh +$ vue-cli-service test:e2e --env firefox,chrome [--headless] +``` + +**Запуск тестов в параллельном режиме** + +Для значительного увеличения скорости тестирования можно включить параллельный запуск тестов если имеются в наличии несколько тестовых наборов. Согласование осуществляется на файловом уровне и автоматически распределяется по доступным ядрам процессора. + +На данный момент возможность доступна только в Chromedriver. Подробнее о [режиме параллельной работы](https://nightwatchjs.org/guide/running-tests/#parallel-running) можно прочитать в документации Nightwatch. + +```sh +$ vue-cli-service test:e2e --parallel +``` + +**Запуск тестов с Selenium** + +Поскольку с версии `v4` автономный сервер Selenium больше не включён в этот плагин, да и в большинстве случаев работа с Selenium не требуется с версии Nightwatch v1.0. + +Но возможность использования сервера Selenium по-прежнему имеется, для этого необходимо выполнить следующие шаги: + +__1.__ Установите NPM-пакет `selenium-server`: + + ```sh + $ npm install selenium-server --save-dev + ``` + +__2.__ Запустите команду с аргументом `--use-selenium`: + + ```sh + $ vue-cli-service test:e2e --use-selenium + ``` From 64716f5da6ab94630f27e947e4b46c35dca559bf Mon Sep 17 00:00:00 2001 From: Alex Sokolov <4497128+Alex-Sokolov@users.noreply.github.com> Date: Thu, 28 Nov 2019 11:05:03 +0300 Subject: [PATCH 25/31] docs: unit-jest.md update --- docs/ru/core-plugins/unit-jest.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/ru/core-plugins/unit-jest.md b/docs/ru/core-plugins/unit-jest.md index 9a86243498..5c94bbfdff 100644 --- a/docs/ru/core-plugins/unit-jest.md +++ b/docs/ru/core-plugins/unit-jest.md @@ -6,14 +6,14 @@ - **`vue-cli-service test:unit`** - Запуск модульных тестов с помощью. По умолчанию значением `testMatch` будет `/(tests/unit/**/*.spec.(js|jsx|ts|tsx)|**/__tests__/*.(js|jsx|ts|tsx))` что совпадает с: + Запуск модульных тестов с помощью Jest. По умолчанию значением `testMatch` будет `/(tests/unit/**/*.spec.(js|jsx|ts|tsx)|**/__tests__/*.(js|jsx|ts|tsx))` что совпадает с: - Любыми файлами в `tests/unit` которые заканчиваются на `.spec.(js|jsx|ts|tsx)`; - Любыми js(x)/ts(x) файлами внутри каталогов `__tests__`. Использование: `vue-cli-service test:unit [options] ` - Также поддерживаются все [опции командной строки Jest](https://facebook.github.io/jest/docs/en/cli.html). + Также поддерживаются все [опции Jest CLI](https://facebook.github.io/jest/docs/en/cli.html). ## Отладка тестов From af7e17630c6a99e932a2c32e8d4ad9e1982cf1f5 Mon Sep 17 00:00:00 2001 From: Alex Sokolov <4497128+Alex-Sokolov@users.noreply.github.com> Date: Sat, 30 Nov 2019 13:28:54 +0300 Subject: [PATCH 26/31] docs: e2e-nightwatch.md update --- docs/ru/core-plugins/e2e-nightwatch.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/ru/core-plugins/e2e-nightwatch.md b/docs/ru/core-plugins/e2e-nightwatch.md index dc6ab441d7..99d594c971 100644 --- a/docs/ru/core-plugins/e2e-nightwatch.md +++ b/docs/ru/core-plugins/e2e-nightwatch.md @@ -11,21 +11,21 @@ Опции: ``` - --url запуск E2E тестов по указанному URL, вместо авто-запуска сервера + --url запуск E2E-тестов по указанному URL, вместо авто-запуска сервера --config использовать пользовательский файл конфигурации nightwatch (перезаписывает внутренние настройки) - --headless использовать chrome или firefox в безголовом (headless) режиме + --headless использовать chrome или firefox в headless-режиме --parallel использовать параллельный режим через test workers (доступно только в chromedriver) --use-selenium использовать сервер Selenium вместо chromedriver или geckodriver - -e, --env указанные через запятую окружения браузеров, в которых требуется запуск (по умолчанию: chrome) - -t, --test указать запускаемый тест по имени + -e, --env окружения браузеров через запятую для тестирования (по умолчанию: chrome) + -t, --test запустить тест по указанному пути к файлу -f, --filter glob для фильтрации тестов по имени файла ``` - Также [поддерживаются все опции Nightwatch CLI](https://nightwatchjs.org/guide/running-tests/#command-line-options). Например: `--verbose`, `--retries` и т.д. + [Поддерживаются все опции Nightwatch CLI](https://nightwatchjs.org/guide/running-tests/#command-line-options). Например: `--verbose`, `--retries` и т.д. ## Структура проекта -При установке плагина генерируется следующая структура каталогов. В ней уже будут примеры для большинства концептов тестирования, доступных в Nightwatch. +При установке плагина генерируется следующая структура каталогов. В ней будут примеры для большинства концептов тестирования доступных в Nightwatch. ``` tests/e2e/ @@ -44,19 +44,19 @@ tests/e2e/ ``` #### `specs` -Основное место расположения тестов. Может содержать вложенные каталоги, которые возможно выбирать при запуске с помощью аргумента `--group`. [Подробнее](https://nightwatchjs.org/guide/running-tests/#test-groups). +Основное место расположения тестов. Может содержать вложенные каталоги, которые можно выбирать при запуске с помощью аргумента `--group`. [Подробнее](https://nightwatchjs.org/guide/running-tests/#test-groups). #### `custom-assertions` -Расположенные здесь файлы будут автоматически загружаться Nightwatch и добавляться в API `.assert` и `.verify` для расширения встроенных методов проверок Nightwatch. Подробнее в документации [по созданию пользовательских утверждений (assertions)](https://nightwatchjs.org/guide/extending-nightwatch/#writing-custom-assertions). +Расположенные здесь файлы будут автоматически загружаться Nightwatch и добавляться в API `.assert` и `.verify` для расширения встроенных методов утверждений Nightwatch. Подробнее в документации [по созданию пользовательских утверждений](https://nightwatchjs.org/guide/extending-nightwatch/#writing-custom-assertions). #### `custom-commands` Расположенные здесь файлы будут автоматически загружаться Nightwatch и добавляться в API объекта `browser` для расширения встроенных команд Nightwatch. Подробнее в документации [по созданию пользовательских команд](https://nightwatchjs.org/guide/extending-nightwatch/#writing-custom-commands). #### `page objects` -Работа с объектами страниц — популярная методология в end-to-end UI тестировании. Расположенные здесь файлы будут автоматически добавляться в API `.page`, при этом имя файла определит имя объекта страницы. Подробнее в документации [по работе с объектами страниц](https://nightwatchjs.org/guide/working-with-page-objects/). +Работа с объектами страниц — популярная методология в E2E-тестировании UI. Расположенные здесь файлы будут автоматически добавляться в API `.page`, при этом имя файла определит имя объекта страницы. Подробнее в документации [по работе с объектами страниц](https://nightwatchjs.org/guide/working-with-page-objects/). #### `globals.js` -Файл с внешними глобальными переменными, который может содержать глобальные свойства или хуки. Подробнее в документации [по глобальным свойствам тестов](https://nightwatchjs.org/gettingstarted/configuration/#test-globals). +Файл внешних глобальных переменных, который может содержать глобальные свойства или хуки. Подробнее в документации [по глобальным свойствам тестов](https://nightwatchjs.org/gettingstarted/configuration/#test-globals). ## Установка в уже созданный проект @@ -74,7 +74,7 @@ Nightwatch предварительно сконфигурирован для з ## Запуск тестов -По умолчанию, все тесты внутри каталога `specs` будут запускаться с использованием Chrome. Если необходимо запустить end-to-end тесты в безголовом (headless) режиме в Chrome (или Firefox), укажите аргумент `--headless`. +По умолчанию, все тесты внутри каталога `specs` будут запускаться с использованием Chrome. Если необходимо запустить end-to-end тесты в headless-режиме в Chrome (или Firefox), укажите аргумент `--headless`. ```sh $ vue-cli-service test:e2e From bc59ab75da4e727f0eddfdfe2077268995e8c733 Mon Sep 17 00:00:00 2001 From: Alex Sokolov <4497128+Alex-Sokolov@users.noreply.github.com> Date: Sat, 30 Nov 2019 13:29:17 +0300 Subject: [PATCH 27/31] docs: migrating-from-v3.md update --- docs/ru/migrating-from-v3/README.md | 223 +++++++++++++--------------- 1 file changed, 107 insertions(+), 116 deletions(-) diff --git a/docs/ru/migrating-from-v3/README.md b/docs/ru/migrating-from-v3/README.md index 0169a1833f..d79818e955 100644 --- a/docs/ru/migrating-from-v3/README.md +++ b/docs/ru/migrating-from-v3/README.md @@ -4,7 +4,7 @@ sidebar: auto # Миграция с версии v3 -Во-первых, установите последнюю версию Vue CLI глобально: +Для начала глобально установите последнюю версию Vue CLI: ```sh npm install -g @vue/cli @@ -14,68 +14,68 @@ yarn global add @vue/cli ## Обновление всех плагинов сразу -In your existing projects, run: +В существующих проектах запустите команду: ```sh vue upgrade ``` -And then see the following section for detailed breaking changes introduced in each package. +После чего ознакомьтесь со следующим разделом с информацией о крупных изменениях (breaking changes) в каждом пакете. ------ -## One-By-One Manual Migration +## Миграция вручную по одному пакету -If you want to migrate manually and gradually, here are the tips: +При желании выполнить миграцию постепенно и вручную несколько советов: -### The Global `@vue/cli` +### Глобальный пакет `@vue/cli` -#### [Redesigned](https://github.com/vuejs/vue-cli/pull/4090) `vue upgrade` +#### [Переработана команда](https://github.com/vuejs/vue-cli/pull/4090) `vue upgrade` -- Before: `vue upgrade [patch | minor | major]`, and it does nothing more than installing the latest versions of Vue CLI plugins. -- After: `vue upgrade [plugin-name]`. Aside from upgrading the plugins, it can run migrators from plugins to help you automate the migration process. For more options for this command, please run `vue upgrade --help`. +- Было: `vue upgrade [patch | minor | major]` — выполняла только установку последних версий плагинов Vue CLI. +- Стало: `vue upgrade [plugin-name]` — кроме обновления плагинов, запускает миграции из них для автоматизации процесса обновления. Для получения информации о дополнительных опциях этой команды выполните `vue upgrade --help`. -#### `vue --version` Output Format Change +#### Изменён формат вывода `vue --version` -When running `vue --version`: +При запуске `vue --version`: -- 3.x: outputs `3.12.0` -- 4.x: outputs `@vue/cli 4.0.0` +- 3.x: выводит `3.12.0` +- 4.x: выводит `@vue/cli 4.0.0` -#### Extra Confirmation Step To Avoid Overwriting +#### Добавлен дополнительный шаг подтверждения во избежание перезаписи -When running `vue invoke` / `vue add` / `vue upgrade`, there's now an [extra confirmation step](https://github.com/vuejs/vue-cli/pull/4275) if you have uncommitted changes in the current repository. +При запуске `vue invoke` / `vue add` / `vue upgrade` теперь появляется [дополнительный шаг подтверждения](https://github.com/vuejs/vue-cli/pull/4275) при наличии незафиксированных изменений в текущем репозитории. ![image](https://user-images.githubusercontent.com/3277634/65588457-23db5a80-dfba-11e9-9899-9dd72efc111e.png) -#### Vue Router and Vuex Now Have Corresponding CLI Plugins +#### Vue Router и Vuex теперь имеют сопутствующие CLI-плагины -When running `vue add vuex` or `vue add router`: +При запуске `vue add vuex` или `vue add router`: -- In v3, only `vuex` or `vue-router` will be added to the project; -- In v4, there will also be `@vue/cli-plugin-vuex` or `@vue/cli-plugin-router` installed. +- В версии 3, только `vuex` или `vue-router` добавляется в проект; +- В версии 4, также устанавливается `@vue/cli-plugin-vuex` или `@vue/cli-plugin-router`. -This currently does not make an actual difference for end-users, but such design allows us to add more features for Vuex and Vue Router users later. +В настоящее время это не привносит ничего особенного для конечных пользователей, но такой подход позволяет добавлять больше возможностей для пользователей Vuex и Vue Router позднее. -For preset and plugin authors, there are several noteworthy changes in the two plugins: +Для разработчиков пресетов и плагинов есть ещё несколько изменений в этих двух плагинах: -- The default directory structure was changed: - - `src/store.js` moved to `src/store/index.js`; - - `src/router.js` renamed to `src/router/index.js`; -- The `router` & `routerHistoryMode` options in `preset.json` are still supported for compatibility reasons. But it's now recommended to use `plugins: { '@vue/cli-plugin-router': { historyMode: true } }` for better consistency. -- `api.hasPlugin('vue-router')` is no longer supported. It's now `api.hasPlugin('router')`. +- Структура каталогов по умолчанию изменена: + - `src/store.js` перемещён в `src/store/index.js`; + - `src/router.js` перемещён в `src/router/index.js`; +- Опции `router` и `routerHistoryMode` в файле `preset.json` по-прежнему поддерживаются для совместимости. Но рекомендуется использовать `plugins: { '@vue/cli-plugin-router': { historyMode: true } }` для консистентности. +- `api.hasPlugin('vue-router')` больше не поддерживается. Теперь `api.hasPlugin('router')`. ### `@vue/cli-service` -#### Whitespace handling in the template block +#### Обработка пробелов в шаблонах -To get a smaller bundle, we've disabled the `preserveWhitespace` option of `vue-template-compiler` by default in Vue CLI v3. +Во Vue CLI v3 для уменьшения размеров итоговой сборки по умолчанию отключена опция `preserveWhitespace` для `vue-template-compiler`. -This set comes with some caveats, however. +Однако это привносило свои тонкости использования. -Luckily, since the Vue 2.6 release, we can now have finer control over the whitespace handling, with the [new `whitespace` option](https://github.com/vuejs/vue/issues/9208#issuecomment-450012518). So we decided to switch over to use this new option by default in Vue CLI v4. +Но после релиза Vue 2.6 теперь можно управлять обработкой пробелов с помощью [новой опции `whitespace`](https://github.com/vuejs/vue/issues/9208#issuecomment-450012518). Поэтому во Vue CLI v4 перешли на использование этой новой опции по умолчанию. -Take the following template as an example: +Возьмём в качестве примера следующий шаблон: ```html

@@ -84,56 +84,56 @@ Take the following template as an example:

``` -With `preserveWhitespace: false`, all whitespaces between tags are removed, so it was compiled as: +С опцией `preserveWhitespace: false` все пробелы между тегами будут удалены, поэтому он скомпилируется в: ```html

Welcome to Vue.jsworld. Have fun!

``` -With `whitespace: 'condense'`, it is now compiled as: +С опцией `whitespace: 'condense'` он скомпилируется в: ```html

Welcome to Vue.js world. Have fun!

``` -Note the **inline** whitespace between tags is now preserved. +Обратите внимание, что теперь сохраняется **инлайновый** пробел между тегами. #### `vue-cli-service build --mode development` -In the past, when running the `build` command in the `development` mode, the `dist` folder layout would be different from the `production` mode. Now with the following two changes, the directory structures across all modes would be the same (file names are still different - no hashes in `development` mode): +Раньше при запуске команды `build` в режиме `development` расположение каталога `dist` отличалось от расположения в режиме `production`. Теперь, с учётом указанных ниже двух пулл-реквестов, структура и расположение каталогов будет во всех режимах одинакова (имена файлов всё ещё различаются — никаких хэшей в режиме `development`): - [#4323](https://github.com/vuejs/vue-cli/pull/4323) ensure consistent directory structure for all modes - [#4302](https://github.com/vuejs/vue-cli/pull/4302) move dev configs into serve command -#### For SASS/SCSS Users +#### Для пользователей SASS/SCSS -Previously in Vue CLI v3, we shipped with `sass-loader@7` by default. +Раньше во Vue CLI v3 использовался `sass-loader@7` по умолчанию. -Recently `sass-loader@8` has been out and has changed its configuration format quite a lot. Here's the release notes: +Недавно вышел `sass-loader@8` в котором довольно сильно изменился формат конфигурации. Примечания к релизу: -`@vue/cli-service` will continue to support `sass-loader@7` in v4, but we strongly recommend you to take a look at the v8 release and upgrade to the latest version. +`@vue/cli-service` продолжает поддерживать `sass-loader@7` в v4, но настоятельно рекомендуем обратить внимание на релиз `sass-loader@8` и обновиться до последней версии. -#### For Less Users +#### Для пользователей Less -`less-loader` v4 is incompatible with `less` >= v3.10, see . -It's strongly recommended to upgrade to `less-loader@5` if your project depends on it. +`less-loader` v4 несовместим с `less` >= v3.10, см. . +Настоятельно рекомендуем обновиться до `less-loader@5`, если в проекте используется Less. -#### For CSS Module Users +#### Для пользователей CSS модулей -- [Deprecate `css.modules` in favor of `css.requireModuleExtension`](https://github.com/vuejs/vue-cli/pull/4387). This is because we've upgraded to `css-loader` v3 and the config format has been changed. For a more detailed explanation please follow the link. +- [Устаревшая опция `css.modules` заменена на `css.requireModuleExtension`](https://github.com/vuejs/vue-cli/pull/4387). Это связано с обновлением `css-loader` до v3 и изменением формата конфигурации. С подробным объяснением можно ознакомиться по ссылке. -#### `vue.config.js` options +#### Настройки `vue.config.js` -The already-deprecated [`baseUrl` option](https://cli.vuejs.org/config/#baseurl) is now [removed](https://github.com/vuejs/vue-cli/pull/4388) +Уже объявленная как устаревшая [опция `baseUrl`](../config/#baseurl) теперь [удалена](https://github.com/vuejs/vue-cli/pull/4388). #### `chainWebpack` / `configureWebpack` -##### The `minimizer` Method in `chainWebpack` +##### Метод `minimizer` в `chainWebpack` -If you've customized the internal rules with `chainWebpack`, please notice that `webpack-chain` was updated from v4 to v6, the most noticeable change is the `minimizer` config +Если настраивали правила через `chainWebpack`, то обратите внимание, что `webpack-chain` обновлён с версии v4 до v6. Наиболее заметным изменением является конфигурация `minimizer`. -For example, if you want to enable the `drop_console` option in the terser plugin. -In v3, you may do this in `chainWebpack`: +Например, если необходимо включить опцию `drop_console` в плагине terser. +В версии v3 это можно сделать через `chainWebpack` так: ```js const TerserPlugin = require('terser-webpack-plugin') @@ -146,7 +146,7 @@ module.exports = { } ``` -In v4, it's changed to: +В версии v4 необходимо изменить таким образом: ```js module.exports = { @@ -159,69 +159,66 @@ module.exports = { } ``` -##### Other Changes +##### Другие изменения -- [The `pug-plain` rule was renamed to `pug-plain-loader`](https://github.com/vuejs/vue-cli/pull/4230) +- [Правило `pug-plain` переименовано в `pug-plain-loader`](https://github.com/vuejs/vue-cli/pull/4230) -#### Underlying Loaders / Plugins +#### Базовые загрузчики / плагины -Not likely to affect users unless you've customized their options via `chainWebpack` / `configureWebpack` +Скорее всего это вряд ли повлияет на пользователей, если не настраивали опции через `chainWebpack` / `configureWebpack` -`css-loader` was upgraded from v1 to v3: +`css-loader` был обновлён с версии v1 до v3: -- [v2 changelog](https://github.com/webpack-contrib/css-loader/releases/tag/v2.0.0) -- [v3 changelog](https://github.com/webpack-contrib/css-loader/releases/tag/v3.0.0) +- [История изменений v2](https://github.com/webpack-contrib/css-loader/releases/tag/v2.0.0) +- [История изменений v3](https://github.com/webpack-contrib/css-loader/releases/tag/v3.0.0) -Several other underlying webpack loaders and plugins have been upgraded, with mostly trivial changes: +Несколько базовых загрузчиков и плагинов webpack обновлены, с незначительными изменениями: -- `url-loader` [from v1 to v2](https://github.com/webpack-contrib/url-loader/releases/tag/v2.0.0) -- `file-loader` [from v3 to v4](https://github.com/webpack-contrib/file-loader/releases/tag/v4.0.0) -- `copy-webpack-plugin` [from v4 to v5](https://github.com/webpack-contrib/copy-webpack-plugin/blob/master/CHANGELOG.md#500-2019-02-20) -- `terser-webpack-plugin` [from v1 to v2](https://github.com/vuejs/vue-cli/pull/4676) +- `url-loader` [с версии v1 до v2](https://github.com/webpack-contrib/url-loader/releases/tag/v2.0.0) +- `file-loader` [с версии v3 до v4](https://github.com/webpack-contrib/file-loader/releases/tag/v4.0.0) +- `copy-webpack-plugin` [с версии v4 до v5](https://github.com/webpack-contrib/copy-webpack-plugin/blob/master/CHANGELOG.md#500-2019-02-20) +- `terser-webpack-plugin` [с версии v1 до v2](https://github.com/vuejs/vue-cli/pull/4676) ### `@vue/cli-plugin-babel`, `@vue/babel-preset-app` #### core-js -The babel plugin requires a peer dependency, for the polyfills used in the transpiled code. +Требуется плагину babel в качестве peer-зависимости для полифилов, используемых в транспилированном коде. -In Vue CLI v3, the required `core-js` version is 2.x, it is now upgraded to 3.x. +Во Vue CLI v3 использовалась `core-js` версии 2.x, теперь она обновлена до 3.x. -This migration is automated if you upgrade it through `vue upgrade babel`. But if you have custom polyfills introduced, you may need to manually update the polyfill names (For more details, see [core-js changelog](https://github.com/zloirock/core-js/blob/master/CHANGELOG.md#L279-L297)). +Эта миграция автоматизирована, достаточно выполнить команду `vue upgrade babel`. Но если добавлялись пользовательские полифилы, может потребоваться обновить имена полифилов (подробную информацию можно найти в [истории изменений core-js](https://github.com/zloirock/core-js/blob/master/CHANGELOG.md#L279-L297)). -#### Babel Preset +#### Пресет Babel -This migration is also automated if you upgrade it through `vue upgrade babel`. +Эта миграция также автоматизирована, при обновлении командой `vue upgrade babel`. -- In v3, the default babel preset used in `babel.config.js` is `@vue/app`. -- In v4, we moved it to the plugin, so now it's named as `@vue/cli-plugin-babel/preset` +- В версии v3, babel пресет по умолчанию в `babel.config.js` был `@vue/app`. +- В версии v4, пресет перемещён в плагин и теперь называется `@vue/cli-plugin-babel/preset` -It is because that `@vue/babel-preset-app` is indeed an indirect dependency on the project. -It works because of npm's package hoisting. -But potential problems could still occur if the project has multiple conflicting indirect dependencies of the same package, or if the package manager puts stricter constraints on the dependency resolution (e.g. yarn plug'n'play or pnpm). -So we now moved it to the project's direct dependency (`@vue/cli-plugin-babel`) to make it more standard-compliant and less error-prone. +Необходимость этого в том, что `@vue/babel-preset-app` в действительности является косвенной зависимостью проекта. Это работает благодаря «поднятию» (hoisting) npm-пакета. Однако может стать причиной потенциальных проблем, если у проекта несколько косвенных зависимостей одного и того же пакета, или если менеджер пакетов накладывает более строгие ограничения при разрешении зависимостей (например, yarn plug'n'play или pnpm). Поэтому он вынесен отдельной зависимостью проекта (`@vue/cli-plugin-babel`) для большей совместимости со стандартами и меньшей подверженности ошибкам. ------ ### `@vue/cli-plugin-eslint` -This plugin now [requires ESLint as a peer dependency](https://github.com/vuejs/vue-cli/pull/3852). +Плагин теперь [требует ESLint в качестве peer-зависимости](https://github.com/vuejs/vue-cli/pull/3852). -This won't affect projects scaffolded with Vue CLI 3.1 or later. +Это не повлияет на проекты, созданные с помощью Vue CLI 3.1 или более поздних версий. -If your project was scaffolded with Vue CLI 3.0.x or earlier, you may need to add `eslint@4` to your project dependencies (This is automated if you upgrade the plugin using `vue upgrade eslint`). +Если проект был создан с помощью Vue CLI 3.0.x или более ранних версий, то потребуется добавить `eslint@4` к зависимостям проекта (это автоматизированно при обновлении плагина с помощью команды `vue upgrade eslint`). -It's also recommended to upgrade your ESLint to v5, and ESLint config versions to the latest. (ESLint v6 support is still on the way) +Также рекомендуется обновить ESLint до версии v5, а конфигурацию ESLint до последней версии (поддержка ESLint v6 будет добавлена в ближайшем будущем). ------ -#### The Prettier Preset +#### Пресет Prettier -The old implementation of our prettier preset is flawed. We've updated the default template since Vue CLI v3.10. +Старая реализация пресета prettier была несовершенной. Шаблон по умолчанию обновлён с версии Vue CLI v3.10. -It now requires `eslint`, `eslint-plugin-prettier` and `prettier` as peer dependencies, following the [standard practice in the ESLint ecosystem](https://github.com/eslint/eslint/issues/3458). +Теперь требуются `eslint`, `eslint-plugin-prettier` и `prettier` в качестве peer-зависимостей, следуя [стандартным практикам экосистемы ESLint](https://github.com/eslint/eslint/issues/3458). -For older projects, if you encountered issues like `Cannot find module: eslint-plugin-prettier`, please run the following command to fix it: +В старых проектах при возникновении проблем как `Cannot find module: eslint-plugin-prettier` необходимо выполнить следующую команду для их исправления: ```sh npm install --save-dev eslint@5 @vue/eslint-config-prettier@5 eslint-plugin-prettier prettier @@ -229,80 +226,74 @@ npm install --save-dev eslint@5 @vue/eslint-config-prettier@5 eslint-plugin-pret ------ -#### `lintOnSave` options +#### Настройки `lintOnSave` -(the following only affects development) +(затрагивает только процесс разработки) -The default value of `lintOnSave` option (when not specified) was [changed from `true` to `'default'`](https://github.com/vuejs/vue-cli/pull/3975). You can read more on the detailed explanation in the [documentation](https://cli.vuejs.org/config/#lintonsave). +Значение по умолчанию для опции `lintOnSave` (если не было указано) [изменено с `true` на `'default'`](https://github.com/vuejs/vue-cli/pull/3975). Ознакомиться с подробным объяснением можно [в документации](../config/#lintonsave). -In a nutshell: +Вкратце: -- In v3, by default, lint warnings, along with errors, will be displayed in the error overlay -- In v4, by default, only lint errors will interrupt your development process. Warnings are only logged in the terminal console. +- В версии v3, по умолчанию, предупреждения линтинга и ошибки отображаются в браузере в слое для ошибок поверх приложения. +- В версии v4, по умолчанию, только ошибки линтинга будут таким образом прерывать процесс разработки. Предупреждения будут отображаться в консоли терминала. ### `@vue/cli-plugin-pwa` -The underlying workbox-webpack-plugin has been upgraded from v3 to v4. See [the release notes here](https://github.com/GoogleChrome/workbox/releases/tag/v4.0.0). +Базовый плагин workbox-webpack-plugin обновлён с версии v3 до v4. См. [примечания к релизу](https://github.com/GoogleChrome/workbox/releases/tag/v4.0.0). -There's also a `pwa.manifestOptions` field available (you can set it in the `vue.config.js`). With this new option, `manifest.json` will be generated from the config object rather than directly copied from the `public` folder. This provides a more consistent interface to manage your PWA configurations. (Note, it is an opt-in feature. Related PRs: [#2981](https://github.com/vuejs/vue-cli/pull/2981), [#4664](https://github.com/vuejs/vue-cli/pull/4664)) +Теперь доступно поле `pwa.manifestOptions` (его можно указать в файле `vue.config.js`). Благодаря этой опции можно сгенерировать `manifest.json` из объекта конфигурации, а не копировать из каталога `public`. Это обеспечивает более консистентный интерфейс управления конфигурацией PWA (Обратите внимание, что это опциональная возможность. Связанные пулл-реквесты: [#2981](https://github.com/vuejs/vue-cli/pull/2981), [#4664](https://github.com/vuejs/vue-cli/pull/4664)). ### `@vue/cli-plugin-e2e-cypress` -Before Vue CLI v3.0.0-beta.10, the default command for E2E testing was `vue-cli-service e2e`. Later we changed it to `vue-cli-service test:e2e`. The previous command was since deprecated but still supported. -We have now completely [dropped support for this legacy command](https://github.com/vuejs/vue-cli/pull/3774). +До Vue CLI v3.0.0-beta.10 команда для E2E-тестирования по умолчанию была `vue-cli-service e2e`. Позднее изменена на `vue-cli-service test:e2e`. Предыдущая команда объявлена устаревшей, но всё ещё поддерживалась. Теперь [поддержка старой команды удалена](https://github.com/vuejs/vue-cli/pull/3774). ### `@vue/cli-plugin-e2e-nightwatch` -Nightwatch.js has been upgraded from 0.9 to 1.x. Be sure to read the [Nightwatch migration guides](https://github.com/nightwatchjs/nightwatch/wiki/Migrating-to-Nightwatch-1.0) first. +Nightwatch.js обновлён с версии 0.9 до 1.x. Рекомендуем сначала изучить [руководство по миграции Nightwatch](https://github.com/nightwatchjs/nightwatch/wiki/Migrating-to-Nightwatch-1.0). -The bundled config and generated tests [have been completely overhauled](https://github.com/vuejs/vue-cli/pull/4541). Please follow the link for more details. Most use cases in Vue CLI v3 are still supported. They are just new features. +Поставляемая в комплекте конфигурация и генерируемые тесты [были полностью переработаны](https://github.com/vuejs/vue-cli/pull/4541). Перейдите по ссылке для получения более подробной информации. Большинство используемых кейсов во Vue CLI v3 по-прежнему поддерживаются. Это просто добавление новых возможностей. -As ChromeDriver has changed its version strategy since version 73, we've made it a peer dependency in the project. -A simple browser version check is implemented in the plugin, so if you've upgraded to an incompatible version of Chrome, there will be a warning to prompt you to upgrade the depended ChromeDriver version. +Поскольку ChromeDriver изменил свою стратегию версионирования с 73-й версии, теперь он сделан peer-зависимостью проекта. В плагине реализована простая проверка версии браузера, поэтому при обновлении до несовместимой версии Chrome появится предупреждение с предложением обновить до соответствующей версии и ChromeDriver. ------ -As in the cypress plugin, the support for legacy `vue-cli-service e2e` command has also been removed. +Аналогично плагину для cypress, поддержка устаревшей команды `vue-cli-service e2e` удалена. ### `@vue/cli-plugin-typescript` -When using Typescript, the webpack resolve options now [prefer `ts(x)` file extensions over `js(x)` ones](https://github.com/vuejs/vue-cli/pull/3909). +При использовании Typescript, webpack в настройках разрешения модулей теперь [отдаёт предпочтение файлам с расширениями `ts(x)`, а не `js(x)`](https://github.com/vuejs/vue-cli/pull/3909). ### `@vue/cli-plugin-unit-jest` -We've upgraded the bundled Jest from v23 to v24, so please read their [release notes](https://jestjs.io/blog/2019/01/25/jest-24-refreshing-polished-typescript-friendly) first. -Follow [this link](https://github.com/facebook/jest/blob/20ba4be9499d50ed0c9231b86d4a64ec8a6bd303/CHANGELOG.md#user-content-2400) for the full changelog. +Обновлён Jest с версии v23 до v24, поэтому рекомендуем сначала изучить [примечания к релизу](https://jestjs.io/blog/2019/01/25/jest-24-refreshing-polished-typescript-friendly). А также, при необходимости, ознакомиться с [полной историей изменений](https://github.com/facebook/jest/blob/20ba4be9499d50ed0c9231b86d4a64ec8a6bd303/CHANGELOG.md#user-content-2400). -The `unit-jest` plugin now comes with 4 configuration presets: +Плагин `unit-jest` теперь поставляется с 4 пресетами конфигурации: -- `@vue/cli-plugin-unit-jest` The default preset for the most common type of projects -- `@vue/cli-plugin-unit-jest/presets/no-babel` If you don't have `@vue/cli-plugin-babel` installed and don't want to see babel files in the project -- `@vue/cli-plugin-unit-jest/presets/typescript` The preset with TypeScript support (but no TSX support) -- `@vue/cli-plugin-unit-jest/presets/typescript-and-babel` The preset with TypeScript (and TSX) and babel support. +- `@vue/cli-plugin-unit-jest` — пресет по умолчанию для наиболее распространённых типов проектов +- `@vue/cli-plugin-unit-jest/presets/no-babel` — если не установлен `@vue/cli-plugin-babel` и требуется не использовать babel в проекте +- `@vue/cli-plugin-unit-jest/presets/typescript` — пресет с поддержкой TypeScript (но без поддержки TSX) +- `@vue/cli-plugin-unit-jest/presets/typescript-and-babel` — пресет с поддержкой TypeScript (в том числе TSX) и babel. -If you haven't changed the default Jest configurations (lies in either `jest.config.js` or the `jest` field in `package.json`) ever since project creation, you can now replace the massive configuration object with one single field: +Если после создания проекта стандартная конфигурация Jest не изменялась (расположена в файле `jest.config.js` или в поле `jest` в `package.json`), то можно просто заменить массивный объект конфигурации одним единственным полем: ```js module.exports = { - // Replace the following preset name with the one you want to use from the above list + // Замените имя пресета на одно из списка выше по необходимости preset: '@vue/cli-plugin-unit-jest' } ``` -(the `ts-jest`, `babel-jest` dependencies can also be removed after migrating config to use presets) +(зависимости `ts-jest`, `babel-jest` можно удалить после миграции конфигурации на использование пресета) -::: tip A Reminder -The default test environment in the new presets is jsdom@15, which differs from the default one in Jest 24 (jsdom@11). -This is to be aligned with the upcoming Jest 25 updates. -Most users won't be affected by this change. -For a detailed changelog with regard to jsdom, see +::: tip Напоминание +По умолчанию тестовое окружение в новых пресетах использует jsdom@15, что отличается от среды по умолчанию в Jest 24 (jsdom@11). Это должно быть согласовано в предстоящем обновлении Jest 25. Большинство пользователей не будут затронуты этим изменением. Подробную информацию, связанную с jsdom, можно найти в истории изменений ::: ### `@vue/cli-plugin-unit-mocha` -- Use mochapack instead of mocha-webpack, see changelog at . This change is not likely to affect actual usage. -- Upgraded to mocha 6, see [Mocha's changelog](https://github.com/mochajs/mocha/blob/master/CHANGELOG.md#600-0--2019-01-01) for more details. +- Теперь используется mochapack вместо mocha-webpack, см. историю изменений . Это изменение вряд ли повлияет на фактическое использование. +- Обновление mocha до версии 6, см. [историю изменений Mocha](https://github.com/mochajs/mocha/blob/master/CHANGELOG.md#600-0--2019-01-01) для подробной информации. ### `@vue/cli-service-global` -See breaking changes in the [`@vue/cli-service`](#vue-cli-service) & [`@vue/cli-plugin-eslint`](#vue-cli-plugin-eslint) packages. +См. подробные изменения в пакетах [`@vue/cli-service`](#vue-cli-service) и [`@vue/cli-plugin-eslint`](#vue-cli-plugin-eslint). From ca9a5d419383ae138cdc7044c8955677c7851da9 Mon Sep 17 00:00:00 2001 From: Alex Sokolov <4497128+Alex-Sokolov@users.noreply.github.com> Date: Sat, 30 Nov 2019 13:30:10 +0300 Subject: [PATCH 28/31] docs: plugin-dev.md update --- docs/ru/dev-guide/plugin-dev.md | 945 +++++++++++++++++++++++++------- 1 file changed, 746 insertions(+), 199 deletions(-) diff --git a/docs/ru/dev-guide/plugin-dev.md b/docs/ru/dev-guide/plugin-dev.md index 0c979b3583..18437cac02 100644 --- a/docs/ru/dev-guide/plugin-dev.md +++ b/docs/ru/dev-guide/plugin-dev.md @@ -2,333 +2,880 @@ sidebarDepth: 3 --- -# Разработка плагинов +# Руководство по разработке плагинов -## Основные концепции +## Введение -Существуют две основные части системы: +A CLI plugin is an npm package that can add additional features to the project using Vue CLI. These features can include: -- `@vue/cli`: установленный глобально, предоставляет команду `vue create `; -- `@vue/cli-service`: установленный локально, предоставляет команду `vue-cli-service`. +- changing project webpack config - for example, you can add a new webpack resolve rule for a certain file extension, if your plugin is supposed to work with this type of files. Say, `@vue/cli-plugin-typescript` adds such rule to resolve `.ts` and `.tsx` extensions; +- adding new vue-cli-service command - for example, `@vue/cli-plugin-unit-jest` adds a new command `test:unit` that allows developer to run unit tests; +- extending `package.json` - a useful option when your plugin adds some dependencies to the project and you need to add them to package dependencies section; +- creating new files in the project and/or modifying old ones. Sometimes it's a good idea to create an example component or modify a main file to add some imports; +- prompting user to select certain options - for example, you can ask user if they want to create the example component mentioned above. -Обе части используют архитектуру, основанную на плагинах. +:::tip +Don't overuse vue-cli plugins! If you want just to include a certain dependency, e.g. [Lodash](https://lodash.com/) - it's easier to do it manually with npm than create a specific plugin only to do so. +::: + +CLI Plugin should always contain a [Service Plugin](#service-plugin) as its main export, and can optionally contain a [Generator](#generator), a [Prompt File](#prompts) and a [Vue UI integration](#ui-integration). -### Creator +As an npm package, CLI plugin must have a `package.json` file. It's also recommended to have a plugin description in `README.md` to help others find your plugin on npm. -[Creator][creator-class] — это класс, создаваемый при вызове `vue create `. Отвечает за запросы пользователю для получения настроек, запускает генераторы и устанавливает зависимости. +So, typical CLI plugin folder structure looks like the following: -### Service +```bash +. +├── README.md +├── generator.js # generator (optional) +├── index.js # service plugin +├── package.json +├── prompts.js # prompts file (optional) +└── ui.js # Vue UI integration (optional) +``` -[Service][service-class] — это класс, создаваемый при вызове `vue-cli-service [...args]`. Отвечает за управление внутренней конфигурацией webpack, и предоставляет команды для запуска и сборки проекта. +## Именование и обнаруживаемость в поиске -### Плагин для CLI (CLI Plugin) +For a CLI plugin to be usable in a Vue CLI project, it must follow the name convention `vue-cli-plugin-` or `@scope/vue-cli-plugin-`. It allows your plugin to be: -Плагин для CLI — это npm-пакет, который может добавлять дополнительные возможности в проект `@vue/cli`. Он должен всегда содержать [плагин для сервиса](#service-plugin) в качестве основного экспорта, и может опционально содержать [Generator](#generator) и [файл подсказок](#prompts-for-3rd-party-plugins). +- Discoverable by `@vue/cli-service`; +- Discoverable by other developers via searching; +- Installable via `vue add ` or `vue invoke `. -Типичная структура каталогов плагина для CLI выглядит следующим образом: +:::warning Warning +Make sure to name the plugin correctly, otherwise it will be impossible to install it via `vue add` command or find it with Vue UI plugins search! +::: +For better discoverability when a user searches for your plugin, put keywords describing your plugin in the `description` field of the plugin `package.json` file. + +Example: + +```json +{ + "name": "vue-cli-plugin-apollo", + "version": "0.7.7", + "description": "vue-cli plugin to add Apollo and GraphQL" +} ``` -. -├── README.md -├── generator.js # генератор (опционально) -├── prompts.js # файл подсказок (опционально) -├── index.js # плагин для сервиса -└── package.json + +You should add the url to the plugin website or repository in the `homepage` or `repository` field so that a 'More info' button will be displayed in your plugin description: + +```json +{ + "repository": { + "type": "git", + "url": "git+https://github.com/Akryum/vue-cli-plugin-apollo.git" + }, + "homepage": "https://github.com/Akryum/vue-cli-plugin-apollo#readme" +} ``` -### Плагин для сервиса (Service Plugin) +![Plugin search item](/plugin-search-item.png) -Сервисные плагины загружаются автоматически при создании экземпляра сервиса — т.е. каждый раз когда команда `vue-cli-service` вызывается внутри проекта. +## Генератор -Обратите внимание, что концепция «плагина для сервиса», которую мы обсуждаем здесь, несколько уже, чем концепция «плагина для CLI», который публикуется как npm-пакет. Первый относится только к модулю, который будет загружен `@vue/cli-service` когда он инициализирован, и обычно является частью последнего. +A Generator part of the CLI plugin is usually needed when you want to extend your package with new dependencies, create new files in your project or edit existing ones. -Кроме того, [встроенные команды][commands] и [конфигурация модулей][config] `@vue/cli-service` также реализованы как плагины для сервиса. +Inside the CLI plugin the generator should be placed in a `generator.js` or `generator/index.js` file. It will be invoked in two possible scenarios: -Плагин для сервиса должен экспортировать функцию, которая принимает два аргумента: +- During a project's initial creation, if the CLI plugin is installed as part of the project creation preset. -- Экземпляр [PluginAPI][plugin-api] +- When the plugin is installed after project's creation and invoked individually via `vue add` or `vue invoke`. -- Объект, содержащий локальные настройки проекта, указанные в `vue.config.js`, или в поле `"vue"` в `package.json`. +A generator should export a function which receives three arguments: -API позволяет плагинам для сервиса расширять / изменять внутреннюю конфигурацию webpack для разных окружений и внедрять дополнительные команды в `vue-cli-service`. Например: +1. A [GeneratorAPI](generator-api.md) instance; -``` js -module.exports = (api, projectOptions) => { - api.chainWebpack(webpackConfig => { - // изменение конфигурации webpack с помощью webpack-chain - }) +2. The generator options for this plugin. These options are resolved during the [prompt](#prompts) phase of project creation, or loaded from a saved preset in `~/.vuerc`. For example, if the saved `~/.vuerc` looks like this: - api.configureWebpack(webpackConfig => { - // изменение конфигурации webpack - // или возвращение объекта, который будет объединён с помощью webpack-merge - }) +```json +{ + "presets" : { + "foo": { + "plugins": { + "@vue/cli-plugin-foo": { "option": "bar" } + } + } + } +} +``` + +And if the user creates a project using the `foo` preset, then the generator of `@vue/cli-plugin-foo` will receive `{ option: 'bar' }` as its second argument. + +For a 3rd party plugin, the options will be resolved from the prompts or command line arguments when the user executes `vue invoke` (see [Prompts](#prompts)). + +3. The entire preset (`presets.foo`) will be passed as the third argument. + +### Создание новых шаблонов + +When you call `api.render('./template')`, the generator will render files in `./template` (resolved relative to the generator file) with [EJS](https://github.com/mde/ejs). + +Let's imagine we're creating [vue-cli-auto-routing](https://github.com/ktsn/vue-cli-plugin-auto-routing) plugin and we want to make the following changes to the project on plugin invoke: + +- create a `layouts` folder with a default layout file; +- create a `pages` folder with `about` and `home` pages; +- add a `router.js` to the `src` folder root + +To render this structure, you need to create it first inside the `generator/template` folder: + +![Generator structure](/generator-template.png) + +After template is created, you should add `api.render` call to the `generator/index.js` file: + +```js +module.exports = api => { + api.render('./template') +} +``` + +### Изменение существующих шаблонов + +In addition, you can inherit and replace parts of an existing template file (even from another package) using YAML front-matter: + +```ejs +--- +extend: '@vue/cli-service/generator/template/src/App.vue' +replace: !!js/regexp / +``` + +It's also possible to do multiple replaces, although you will need to wrap your replace strings within `<%# REPLACE %>` and `<%# END_REPLACE %>` blocks: + +```ejs +--- +extend: '@vue/cli-service/generator/template/src/App.vue' +replace: + - !!js/regexp /Welcome to Your Vue\.js App/ + - !!js/regexp / +<%# END_REPLACE %> +``` + +### Ограничения по именованию файлов + +If you want to render a template file that either begins with a dot (i.e. `.env`) you will have to follow a specific naming convention, since dotfiles are ignored when publishing your plugin to npm: + +```bash +# dotfile templates have to use an underscore instead of the dot: + +/generator/template/_env + +# When calling api.render('./template'), this will be rendered in the project folder as: + +/generator/template/.env +``` + +Consequently, this means that you also have to follow a special naming convention if you want to render file whose name actually begins with an underscore: + +```bash +# such templates have to use two underscores instead of one: + +/generator/template/__variables.scss - api.registerCommand('test', args => { - // регистрация команды `vue-cli-service test` +# When calling api.render('./template'), this will be rendered in the project folder as: + +/generator/template/_variables.scss +``` + + +### Расширение пакета + +If you need to add an additional dependency to the project, create a new npm script or modify `package.json` in any other way, you can use API `extendPackage` method. + +```js +// generator/index.js + +module.exports = api => { + api.extendPackage({ + dependencies: { + 'vue-router-layout': '^0.1.2' + } }) } ``` -#### Установка режимов для команд +In the example above we added one dependency: `vue-router-layout`. During the plugin invocation this npm module will be installed and this dependency will be added to the user `package.json` file. -> Примечание: установка режимов плагинами была изменена в beta.10. +With the same API method we can add new npm tasks to the project. To do so, we need to specify task name and a command that should be run in the `scripts` section of the user `package.json`: -Если зарегистрированная в плагине команда должна запускаться в определённом режиме по умолчанию, -плагин должен предоставлять её через `module.exports.defaultModes` в формате `{ [commandName]: mode }`: +```js +// generator/index.js -``` js module.exports = api => { - api.registerCommand('build', () => { - // ... + api.extendPackage({ + scripts: { + greet: 'vue-cli-service greet' + } }) } +``` -module.exports.defaultModes = { - build: 'production' +In the example above we're adding a new `greet` task to run a custom vue-cli service command created in [Service section](#add-a-new-cli-service-command). + +### Изменение основного файла + +With generator methods you can make changes to the project files. The most usual case is some modifications to `main.js` or `main.ts` file: new imports, new `Vue.use()` calls etc. + +Let's consider the case where we have created a `router.js` file via [templating](#creating-new-templates) and now we want to import this router to the main file. We will use two Generator API methods: `entryFile` will return the main file of the project (`main.js` or `main.ts`) and `injectImports` serves for adding new imports to this file: + +```js +// generator/index.js + +api.injectImports(api.entryFile, `import router from './router'`) +``` + +Now, when we have a router imported, we can inject this router to the Vue instance in the main file. We will use `afterInvoke` hook which is to be called when the files have been written to disk. + +First, we need to read main file content with Node `fs` module (which provides an API for interacting with the file system) and split this content on lines: + +```js +// generator/index.js + +module.exports.hooks = (api) => { + api.afterInvoke(() => { + const fs = require('fs') + const contentMain = fs.readFileSync(api.entryFile, { encoding: 'utf-8' }) + const lines = contentMain.split(/\r?\n/g) + }) } ``` -Это связано с тем, что ожидаемый режим для команды должен быть известен до загрузки переменных окружения, что в свою очередь должно произойти до загрузки пользовательских настроек / применения плагинов. +Then we should to find the string containing `render` word (it's usually a part of Vue instance) and add our `router` as a next string: -#### Получение итоговой конфигурации Webpack в плагинах +```js{9-10} +// generator/index.js -Плагин может получить итоговую конфигурацию webpack вызвав `api.resolveWebpackConfig()`. Каждый вызов генерирует новую конфигурацию webpack, которая может быть дополнительно изменена при необходимости: +module.exports.hooks = (api) => { + api.afterInvoke(() => { + const fs = require('fs') + const contentMain = fs.readFileSync(api.entryFile, { encoding: 'utf-8' }) + const lines = contentMain.split(/\r?\n/g) -``` js -module.exports = api => { - api.registerCommand('my-build', args => { - const configA = api.resolveWebpackConfig() - const configB = api.resolveWebpackConfig() + const renderIndex = lines.findIndex(line => line.match(/render/)) + lines[renderIndex] += `\n router,` + }) +} +``` + +Finally, you need to write the content back to the main file: + +```js{12-13} +// generator/index.js - // изменение configA и configB для разных целей... +module.exports.hooks = (api) => { + api.afterInvoke(() => { + const { EOL } = require('os') + const fs = require('fs') + const contentMain = fs.readFileSync(api.entryFile, { encoding: 'utf-8' }) + const lines = contentMain.split(/\r?\n/g) + + const renderIndex = lines.findIndex(line => line.match(/render/)) + lines[renderIndex] += `${EOL} router,` + + fs.writeFileSync(api.entryFile, lines.join(EOL), { encoding: 'utf-8' }) }) } +``` -// не забудьте указать режим по умолчанию для правильных переменных окружения -module.exports.defaultModes = { - 'my-build': 'production' +## Плагин для сервиса + +Service plugin serves for modifying webpack config, creating new vue-cli service commands or changing existing commands (such as `serve` and `build`). + +Service plugins are loaded automatically when a Service instance is created - i.e. every time the `vue-cli-service` command is invoked inside a project. It's located in the `index.js` file in CLI plugin root folder. + +A service plugin should export a function which receives two arguments: + +- A [PluginAPI](plugin-api.md) instance + +- An object containing project local options specified in `vue.config.js`, or in the `"vue"` field in `package.json`. + +The minimal required code in the service plugin file is the following: + +```js +module.exports = () => {} +``` + +### Изменение конфигурации webpack + +The API allows service plugins to extend/modify the internal webpack config for different environments. For example, here we're modifying webpack config with webpack-chain to include `vue-auto-routing` webpack plugin with given parameters: + +```js +const VueAutoRoutingPlugin = require('vue-auto-routing/lib/webpack-plugin') + +module.exports = (api, options) => { + api.chainWebpack(webpackConfig => { + webpackConfig + .plugin('vue-auto-routing') + .use(VueAutoRoutingPlugin, [ + { + pages: 'src/pages', + nested: true + } + ]) + }) } ``` -В качестве альтернативы, плагин также может получить новую [конфигурацию в формате chainable](https://github.com/mozilla-neutrino/webpack-chain) вызвав `api.resolveChainableWebpackConfig()`: +You can also use `configureWebpack` method to modify the webpack config or return object to be merged with webpack-merge. -``` js -api.registerCommand('my-build', args => { - const configA = api.resolveChainableWebpackConfig() - const configB = api.resolveChainableWebpackConfig() +### Добавление новой команды в cli-service - // изменяем цепочки configA и configB для разных целей... +With service plugin you can register a new cli-service command in addition to standard ones (i.e. `serve` and `build`). You can do it with a `registerCommand` API method. - const finalConfigA = configA.toConfig() - const finalConfigB = configB.toConfig() -}) +Here is an example of creating a simple new command that will print a greeting to developer console: + +```js +api.registerCommand( + 'greet', + { + description: 'Writes a greeting to the console', + usage: 'vue-cli-service greet' + }, + () => { + console.log(`👋 Hello`) + } +) ``` -#### Пользовательские настройки для сторонних плагинов +In this example we provided the command name (`'greet'`), an object of command options with `description` and `usage`, and a function that will be run on `vue-cli-service greet` command. -Экспорт из `vue.config.js` [валидируется по схеме](https://github.com/vuejs/vue-cli/blob/dev/packages/%40vue/cli-service/lib/options.js#L3) чтобы избежать опечаток и неправильных значений конфигурации. Тем не менее, можно настраивать поведение сторонних плагинов через поле `pluginOptions`. Например, для следующего `vue.config.js`: +:::tip +You can add new command to the list of project npm scripts inside the `package.json` file [via Generator](#extending-package). +::: -``` js -module.exports = { - pluginOptions: { - foo: { /* ... */ } +If you try to run a new command in the project with your plugin installed, you will see the following output: + +```bash +$ vue-cli-service greet +👋 Hello! +``` + +You can also specify a list of available options for a new command. Let's add the option `--name` and change the function to print this name if it's provided. + +```js +api.registerCommand( + 'greet', + { + description: 'Writes a greeting to the console', + usage: 'vue-cli-service greet [options]', + options: { '--name': 'specifies a name for greeting' } + }, + args => { + if (args.name) { + console.log(`👋 Hello, ${args.name}!`); + } else { + console.log(`👋 Hello!`); + } } +); +``` + +Now, if you a `greet` command with a specified `--name` option, this name will be added to console message: + +```bash +$ vue-cli-service greet --name 'John Doe' +👋 Hello, John Doe! +``` + +### Изменение существующей команды в cli-service + +If you want to modify an existing cli-service command, you can retrieve it with `api.service.commands` and add some changes. We're going to print a message to the console with a port where application is running: + +```js +const { serve } = api.service.commands + +const serveFn = serve.fn + +serve.fn = (...args) => { + return serveFn(...args).then(res => { + if (res && res.url) { + console.log(`Project is running now at ${res.url}`) + } + }) } ``` -Сторонний плагин может получить доступ к свойству `projectOptions.pluginOptions.foo` для определения собственной конфигурации. +In the example above we retrieve the `serve` command from the list of existing commands; then we modify its `fn` part (`fn` is the third parameter passed when you create a new command; it specifies the function to run when running the command). With the modification done the console message will be printed after `serve` command has run successfully. -### Генератор (Generator) +### Определение режимов работы для команд -Плагин для CLI, опубликованный как пакет, может содержать файл `generator.js` или `generator/index.js`. Генератор внутри плагина вызывается в двух возможных сценариях: +If a plugin-registered command needs to run in a specific default mode, the plugin needs to expose it via `module.exports.defaultModes` in the form of `{ [commandName]: mode }`: -- Во время первоначального создания проекта, если плагин для CLI установлен как часть пресета для создания проекта. +```js +module.exports = api => { + api.registerCommand('build', () => { + // ... + }) +} -- Когда плагин устанавливается после создания проекта и вызывается через `vue invoke`. +module.exports.defaultModes = { + build: 'production' +} +``` + +This is because the command's expected mode needs to be known before loading environment variables, which in turn needs to happen before loading user options / applying the plugins. + +## Подсказки -[GeneratorAPI][generator-api] позволяет генератору внедрять дополнительные зависимости или поля в `package.json` и добавлять файлы в проект. +Prompts are required to handle user choices when creating a new project or adding a new plugin to the existing one. All prompts logic is stored inside the `prompts.js` file. The prompts are presented using [inquirer](https://github.com/SBoudrias/Inquirer.js) under the hood. -Генератор должен экспортировать функцию, которая принимает три аргумента: +When user initialize the plugin by calling `vue invoke`, if the plugin contains a `prompts.js` in its root directory, it will be used during invocation. The file should export an array of [Questions](https://github.com/SBoudrias/Inquirer.js#question) that will be handled by Inquirer.js. -1. Экземпляр `GeneratorAPI`; +You should export directly array of questions, or export function that return those. -2. Настройки генератора для этого плагина. Они будут получены во время интерактивного выбора пользователем на этапе создания проекта, или загружаются из сохранённого пресета в `~/.vuerc`. Например, если сохранённый файл `~/.vuerc` выглядит так: +e.g. directly array of questions: +```js +// prompts.js - ``` json +module.exports = [ + { + type: 'input', + name: 'locale', + message: 'The locale of project localization.', + validate: input => !!input, + default: 'en' + }, + // ... +] +``` + +e.g. function that return array of questions: +```js +// prompts.js + +// pass `package.json` of project to function argument +module.exports = pkg => { + const prompts = [ { - "presets" : { - "foo": { - "plugins": { - "@vue/cli-plugin-foo": { "option": "bar" } - } - } - } + type: 'input', + name: 'locale', + message: 'The locale of project localization.', + validate: input => !!input, + default: 'en' } - ``` + ] + + // add dynamically prompt + if ('@vue/cli-plugin-eslint' in (pkg.devDependencies || {})) { + prompts.push({ + type: 'confirm', + name: 'useESLintPluginVueI18n', + message: 'Use ESLint plugin for Vue I18n ?' + }) + } - И если пользователь создаёт проект с использованием пресета `foo`, тогда генератор `@vue/cli-plugin-foo` получит `{ option: 'bar' }` в качестве второго аргумента. + return prompts +} +``` - Для стороннего плагина эти параметры будут получены из интерактивного выбора пользователем или аргументов командной строки, когда выполняется команда `vue invoke` (см. [Интерактивные подсказки для сторонних плагинов](#интерактивные-подсказки-дnя-сторонних-пnагинов)). +The resolved answers object will be passed to the plugin's generator as options. -3. Весь пресет (`presets.foo`) будет передан в качестве третьего аргумента. +Alternatively, the user can skip the prompts and directly initialize the plugin by passing options via the command line, e.g.: -**Например:** +```bash +vue invoke my-plugin --mode awesome +``` -``` js -module.exports = (api, options, rootOptions) => { - // изменение полей package.json - api.extendPackage({ - scripts: { - test: 'vue-cli-service test' - } - }) +Prompt can have [different types](https://github.com/SBoudrias/Inquirer.js#prompt-types) but the most widely used in CLI are `checkbox` and `confirm`. Let's add a `confirm` prompt and then use it in plugin generator to create a condition for [template rendering](#creating-new-templates). - // копирование и рендеринг всех файлов в ./template с помощью ejs - api.render('./template') +```js +// prompts.js - if (options.foo) { - // генерация файлов по условию +module.exports = [ + { + name: `addExampleRoutes`, + type: 'confirm', + message: 'Add example routes?', + default: false } +] +``` + +On plugin invoke user will be prompted with the question about example routes and the default answer will be `No`. + +![Prompts example](/prompts-example.png) + +If you want to use the result of the user's choice in generator, it will be accessible with the prompt name. We can add a modification to `generator/index.js`: + +```js +if (options.addExampleRoutes) { + api.render('./template', { + ...options + }) } ``` -#### Шаблоны генератора +Now template will be rendered only if user agreed to create example routes. -Когда вы вызываете `api.render('./template')`, генератор будет рендерить файлы в `./template` (разрешённые относительно файла генератора) с помощью [EJS](https://github.com/mde/ejs). +## Локальная установка плагина -Кроме того, вы можете наследовать и заменять части существующего файла шаблона (даже из другого пакета) с помощью YAML front-matter: +While working on your plugin, you need to test it and check how it works locally on a project using Vue CLI. You can use an existing project or create a new one just for testing purposes: -``` ejs ---- -extend: '@vue/cli-service/generator/template/src/App.vue' -replace: !!js/regexp / ``` -Также возможно выполнять несколько замен в файле, хотя вам потребуется обернуть строки для замены в блоки из `<%# REPLACE %>` и `<%# END_REPLACE %>`: +### Отображение задачи в UI -``` ejs ---- -extend: '@vue/cli-service/generator/template/src/App.vue' -replace: - - !!js/regexp /Welcome to Your Vue\.js App/ - - !!js/regexp / -<%# END_REPLACE %> ``` -#### Ограничения имён файлов +Now if you explore your project in the Vue UI, you will find your task added to the `Tasks` section. You can see a name of the task, provided description, a link icon that leads to the provided URL and also an output screen to show the task output: -Если вы хотите отрендерить файл шаблона, имя которого начинается с точки (т.е. `.env`) вам необходимо следовать определённому соглашению по именованию, поскольку файлы именуемые с точки (dotfiles) игнорируются при публикации вашего плагина в npm: +![UI Greet task](/ui-greet-task.png) + +### Отображение экрана конфигурации + +Sometimes your project can have custom configuration files for different features or libraries. With Vue CLI plugin you can display this config in Vue UI, change it and save (saving will change the corresponding config file in your project). By default, Vue CLI project has a main configuration screen representing `vue.config.js` settings. If you included ESLint to your project, you will see also a ESLint configuration screen: + +![UI Configuration Screen](/ui-configuration-default.png) + +Let's build a custom configuration for our plugin. First of all, after you add your plugin to the existing project, there should be a file containing this custom config. This means you need to add this file to `template` folder on the [templating step](#creating-new-templates). + +By default, a configuration UI might read and write to the following file types: `json`, `yaml`, `js`, `package`. Let's name our new file `myConfig.js` and place in it the root of `template` folder: + +``` +. +└── generator + ├── index.js + └── template + ├── myConfig.js + └── src + ├── layouts + ├── pages + └── router.js ``` -# dotfile шаблоны должны использовать символ подчёркивания вместо точки: -/generator/template/_env +Now you need to add some actual config to this file: -# При вызове api.render('./template'), это будет отрендерено в каталоге проекта как: +```js +// myConfig.js -.env +module.exports = { + color: 'black' +} ``` -Следовательно, это значит, что необходимо также следовать специальному соглашению по именованию если вы хотите отрендерить файл, чьё имя начинается с подчёркивания: + +After your plugin is invoked, the `myConfig.js` file will be rendered in the project root directory. Now let's add a new configuration screen with the `api.describeConfig` method in the `ui.js` file: + +First you need to pass some information: + +```js +// ui.js + +api.describeConfig({ + // Unique ID for the config + id: 'org.ktsn.vue-auto-routing.config', + // Displayed name + name: 'Greeting configuration', + // Shown below the name + description: 'This config defines the color of the greeting printed', + // "More info" link + link: 'https://github.com/ktsn/vue-cli-plugin-auto-routing#readme' +}) ``` -# такие шаблоны должны иметь два символа подчёркивания вместо точки: -/generator/template/__variables.scss +:::danger Warning +Make sure to namespace the id correctly, since it must be unique across all plugins. It's recommended to use the [reverse domain name notation](https://en.wikipedia.org/wiki/Reverse_domain_name_notation) +::: + +#### Config logo + +You can also select an icon for your config. It can be either a [Material icon](https://material.io/tools/icons/?style=baseline) code or a custom image (see [Public static files](ui-api.md#public-static-files)). -# При вызове api.render('./template'), это будет отрендерено в каталоге проекта как: +```js +// ui.js -_variables.scss +api.describeConfig({ + /* ... */ + // Config icon + icon: 'color_lens' +}) ``` -### Интерактивные подсказки +If you don't specify an icon, the plugin logo will be displayed if any (see [Logo](#logo)). + +#### Config files -#### Интерактивные подсказки для встроенных плагинов +Now you need to provide your configuration file to UI: this way you could read its content and save changes to it. You need to choose a name for your config file, select its format and provide a path to the file: -Только встроенные плагины имеют возможность настраивать исходные подсказки при создании нового проекта, а модули подсказок расположены [внутри пакета `@vue/cli`][prompt-modules]. +```js +api.describeConfig({ + // other config properties + files: { + myConfig: { + js: ['myConfig.js'] + } + } +}) +``` -Модуль подсказок должен экспортировать функцию, которая получает экземпляр [PromptModuleAPI][prompt-api]. Подсказки представлены с помощью [inquirer](https://github.com/SBoudrias/Inquirer.js) под капотом: +There can be more than one file provided. Say, if we have `myConfig.json`, we can provide it with `json: ['myConfig.json']` property. The order is important: the first filename in the list will be used to create the config file if it doesn't exist. -``` js -module.exports = api => { - // объект возможности должен быть корректным объектом выбора inquirer - api.injectFeature({ - name: 'Какая-то суперская возможность', - value: 'my-feature' - }) +#### Display config prompts - // injectPrompt ожидает корректный объект подсказки inquirer - api.injectPrompt({ - name: 'someFlag', - // убедитесь, что подсказка отображается только если выбрана ваша функция - when: answers => answers.features.include('my-feature'), - message: 'Вы хотите включить флаг foo?', - type: 'confirm' - }) +We want to display an input field for color property on the configuration screen. To do so, we need a `onRead` hook that will return a list of prompts to be displayed: - // когда все подсказки завершены, внедряйте ваш плагин в настройки, - // которые будут передаваться генераторам - api.onPromptComplete((answers, options) => { - if (answers.features.includes('my-feature')) { - options.plugins['vue-cli-plugin-my-feature'] = { - someFlag: answers.someFlag +```js +api.describeConfig({ + // other config properties + onRead: ({ data }) => ({ + prompts: [ + { + name: `color`, + type: 'input', + message: 'Define the color for greeting message', + value: 'white' } - } + ] }) -} +}) ``` -#### Интерактивные подсказки для сторонних плагинов +In the example above we specified the input prompt with the value of 'white'. This is how our configuration screen will look with all the settings provided above: -Плагины сторонних разработчиков обычно устанавливаются вручную после того, как проект уже создан, и пользователь будет инициализировать плагин вызовом команды `vue invoke`. Если плагин содержит `prompts.js` в своём корневом каталоге, он будет использован во время вызова. Файл должен экспортировать массив [вопросов](https://github.com/SBoudrias/Inquirer.js#question), которые будут обрабатываться Inquirer.js. Объект с ответами будет передаваться генератору плагина в качестве настроек. +![UI Config Start](/ui-config-start.png) -В качестве альтернативы, пользователь может пропустить подсказки и напрямую инициализировать плагин, передав параметры через командную строку, например: +Now let's replace hardcoded `white` value with the property from the config file. In the `onRead` hook `data` object contains the JSON result of each config file content. In our case, the content of `myConfig.js` was -``` bash -vue invoke my-plugin --mode awesome +```js +// myConfig.js + +module.exports = { + color: 'black' +} ``` -## Распространение плагина +So, the `data` object will be + +```js +{ + // File + myConfig: { + // File data + color: 'black' + } +} +``` -Чтобы CLI-плагин мог использоваться другими разработчиками, он должен быть опубликован на npm придерживаясь соглашения по именованию `vue-cli-plugin-`. Следуя соглашению по именованию позволит вашему плагину быть: +It's easy to see that we need `data.myConfig.color` property. Let's change `onRead` hook: -- Легко находимым с помощью `@vue/cli-service`; -- Легко находимым другими разработчиками через поиск; -- Устанавливаться через `vue add ` или `vue invoke `. +```js +// ui.js -## Примечание о разработке Core-плагинов +onRead: ({ data }) => ({ + prompts: [ + { + name: `color`, + type: 'input', + message: 'Define the color for greeting message', + value: data.myConfig && data.myConfig.color + } + ] +}), +``` -::: tip Примечание -Этот раздел применим только в случае, если вы работаете над встроенным плагином непосредственно внутри `vuejs/vue-cli` репозитория. +::: tip +Note that `myConfig` may be undefined if the config file doesn't exist when the screen is loaded. ::: -Плагин с генератором, который внедряет дополнительные зависимости, отличные от пакетов в репозитории (например, `chai` внедряется `@vue/cli-plugin-unit-mocha/generator/index.js`) должен перечислять эти зависимости в собственном поле `devDependencies`. Это гарантирует: +You can see that on the configuration screen `white` is replaced with `black`. + +We can also provide a default value if the config file is not present: + +```js +// ui.js + +onRead: ({ data }) => ({ + prompts: [ + { + name: `color`, + type: 'input', + message: 'Define the color for greeting message', + value: data.myConfig && data.myConfig.color, + default: 'black', + } + ] +}), +``` + +#### Save config changes -1. что пакет всегда существует в корневом `node_modules` репозитория, поэтому нам не нужно их переустанавливать при каждом тестировании. +We just read the content of `myConfig.js` and used it on the configuration screen. Now let's try to save any changes done in the color input field to the file. We can do it with the `onWrite` hook: -2. что `yarn.lock` остаётся постоянным, поэтому CI сможет лучше применять его кэширование. +```js +// ui.js + +api.describeConfig({ + /* ... */ + onWrite: ({ prompts, api }) => { + // ... + } +}) +``` + +`onWrite` hook can take a lot of [arguments](ui-api.html#save-config-changes) but we will need only two of them: `prompts` and `api`. First one is current prompts runtime objects - we will get a prompt id from it and retrieve an answer with this id. To retrieve the answer we'll use `async getAnswer()` method from the `api`: + +```js +// ui.js + +async onWrite({ api, prompts }) { + const result = {} + for (const prompt of prompts) { + result[`${prompt.id}`] = await api.getAnswer(prompt.id) + } + api.setData('myConfig', result) +} +``` + +Now if you try to change the value in the color input field from `black` to `red` on the config screen and press `Save the changes`, you will observe that `myConfig.js` file in your project has been changed as well: + +```js +// myConfig.js + +module.exports = { + color: 'red' +} +``` + +### Отображение подсказок + +If you want, you can display [prompts](#prompts) in the Vue UI as well. When installing your plugin through the UI, prompts will be shown on the plugin invocation step. + +You can extend the [inquirer object](#prompts-for-3rd-party-plugins) with additional properties. They are optional and only used by the UI: + +```js +// prompts.js + +module.exports = [ + { + // basic prompt properties + name: `addExampleRoutes`, + type: 'confirm', + message: 'Add example routes?', + default: false, + // UI-related prompt properties + group: 'Strongly recommended', + description: 'Adds example pages, layouts and correct router config', + link: + 'https://github.com/ktsn/vue-cli-plugin-auto-routing/#vue-cli-plugin-auto-routing' + } +] +``` + +As a result, you will have this screen on plugin invocation: + +![UI Prompts](/ui-prompts.png) + +### Логотип + +You can put a `logo.png` file in the root directory of the folder that will be published on npm. It will be displayed in several places: + - When searching for a plugin to install + - In the installed plugin list + - In the configurations list (by default) + - In the tasks list for augmented tasks (by default) + +![Plugins](/plugins.png) + +The logo should be a square non-transparent image (ideally 84x84). + +## Публикация плагина в npm + +To publish your plugin, you need to be registered an [npmjs.com](npmjs.com) and you should have `npm` installed globally. If it's your first npm module, please run + +```bash +npm login +``` + +Enter your username and password. This will store the credentials so you don’t have to enter it for every publish. + +:::tip +Before publishing a plugin, make sure you choose a right name for it! Name convention is `vue-cli-plugin-`. Check [Discoverability](#discoverability) section for more information +::: + +To publish a plugin, go to the plugin root folder and run this command in the terminal: + +```bash +npm publish +``` -[creator-class]: https://github.com/vuejs/vue-cli/tree/dev/packages/@vue/cli/lib/Creator.js -[service-class]: https://github.com/vuejs/vue-cli/tree/dev/packages/@vue/cli-service/lib/Service.js -[generator-api]: https://github.com/vuejs/vue-cli/tree/dev/packages/@vue/cli/lib/GeneratorAPI.js -[commands]: https://github.com/vuejs/vue-cli/tree/dev/packages/@vue/cli-service/lib/commands -[config]: https://github.com/vuejs/vue-cli/tree/dev/packages/@vue/cli-service/lib/config -[plugin-api]: https://github.com/vuejs/vue-cli/tree/dev/packages/@vue/cli-service/lib/PluginAPI.js -[prompt-modules]: https://github.com/vuejs/vue-cli/tree/dev/packages/@vue/cli/lib/promptModules -[prompt-api]: https://github.com/vuejs/vue-cli/tree/dev/packages/@vue/cli/lib/PromptModuleAPI.js +After successful publish, you should be able to add your plugin to the project created with Vue CLI with `vue add ` command. From 9a645c0ea857a0ff50727d90d992556a449d3751 Mon Sep 17 00:00:00 2001 From: Alex Sokolov <4497128+Alex-Sokolov@users.noreply.github.com> Date: Mon, 2 Dec 2019 17:10:22 +0300 Subject: [PATCH 29/31] docs: plugin-dev.md update --- docs/ru/dev-guide/plugin-dev.md | 431 ++++++++++++++++---------------- 1 file changed, 215 insertions(+), 216 deletions(-) diff --git a/docs/ru/dev-guide/plugin-dev.md b/docs/ru/dev-guide/plugin-dev.md index 18437cac02..df79163bda 100644 --- a/docs/ru/dev-guide/plugin-dev.md +++ b/docs/ru/dev-guide/plugin-dev.md @@ -6,49 +6,49 @@ sidebarDepth: 3 ## Введение -A CLI plugin is an npm package that can add additional features to the project using Vue CLI. These features can include: +Плагин CLI — это npm-пакет, который может добавлять дополнительные возможности в проект с помощью Vue CLI. Эти функции могут включать в себя: -- changing project webpack config - for example, you can add a new webpack resolve rule for a certain file extension, if your plugin is supposed to work with this type of files. Say, `@vue/cli-plugin-typescript` adds such rule to resolve `.ts` and `.tsx` extensions; -- adding new vue-cli-service command - for example, `@vue/cli-plugin-unit-jest` adds a new command `test:unit` that allows developer to run unit tests; -- extending `package.json` - a useful option when your plugin adds some dependencies to the project and you need to add them to package dependencies section; -- creating new files in the project and/or modifying old ones. Sometimes it's a good idea to create an example component or modify a main file to add some imports; -- prompting user to select certain options - for example, you can ask user if they want to create the example component mentioned above. +- изменение конфигурации webpack проекта — например, можно добавить новое правило для разрешения определённых расширений файлов, если плагин должен работать с этим типом файлов. Например, `@vue/cli-plugin-typescript` добавляет такое правило для разрешения файлов с расширениями `.ts` и `.tsx`; +- добавление новых команд vue-cli-service — например, `@vue/cli-plugin-unit-jest` добавляет новую команду `test:unit`, которая позволяет разработчику запускать модульные тесты; +- расширение `package.json` — полезная опция, когда плагину для работы требуются новые зависимости и необходимо добавить их в раздел зависимостей проекта; +- создание новых и/или изменение старых файлов в проекте. Иногда полезно создать файл с примером компонента или изменить основной файл для добавления необходимых импортов; +- предоставление возможности выбора пользователем требуемых опций — например, можно уточнить необходимость создания примера компонента, упомянутого выше. -:::tip -Don't overuse vue-cli plugins! If you want just to include a certain dependency, e.g. [Lodash](https://lodash.com/) - it's easier to do it manually with npm than create a specific plugin only to do so. +:::tip Совет +Не злоупотребляйте плагинами vue-cli! Если необходимо просто добавить какую-то новую зависимость в проект, например [Lodash](https://lodash.com/) — проще сделать это вручную через npm, чем создавать специальный плагин только для этого. ::: -CLI Plugin should always contain a [Service Plugin](#service-plugin) as its main export, and can optionally contain a [Generator](#generator), a [Prompt File](#prompts) and a [Vue UI integration](#ui-integration). +Плагин CLI всегда должен содержать [плагин для сервиса](#пnагин-дnя-сервиса) в качестве своего основного экспорта, и может опционально содержать [генератор](#генератор), [файл интерактивных подсказок](#интерактивные-подсказки) и [интеграцию с Vue UI](#интеграция-с-ui). -As an npm package, CLI plugin must have a `package.json` file. It's also recommended to have a plugin description in `README.md` to help others find your plugin on npm. +Как npm-пакет, плагин CLI должен иметь файл `package.json`. Также рекомендуется, чтобы у плагина было описание в файле `README.md`, чтобы помочь другим найти ваш плагин в npm. -So, typical CLI plugin folder structure looks like the following: +Типичная структура плагина CLI выглядит следующим образом: ```bash . ├── README.md -├── generator.js # generator (optional) -├── index.js # service plugin +├── generator.js # генератор (опционально) +├── index.js # плагин для сервиса ├── package.json -├── prompts.js # prompts file (optional) -└── ui.js # Vue UI integration (optional) +├── prompts.js # файл интерактивных подсказок (опционально) +└── ui.js # интеграция с Vue UI (опционально) ``` ## Именование и обнаруживаемость в поиске -For a CLI plugin to be usable in a Vue CLI project, it must follow the name convention `vue-cli-plugin-` or `@scope/vue-cli-plugin-`. It allows your plugin to be: +Чтобы плагин CLI мог использоваться в проекте Vue CLI, он должен соответствовать соглашению по именованию `vue-cli-plugin-` или `@scope/vue-cli-plugin-`. Это позволит вашему плагину быть: -- Discoverable by `@vue/cli-service`; -- Discoverable by other developers via searching; -- Installable via `vue add ` or `vue invoke `. +- Обнаруживаемым `@vue/cli-service`; +- Обнаруживаемым другими разработчиками при поиске; +- Устанавливаемым через `vue add ` или `vue invoke `. -:::warning Warning -Make sure to name the plugin correctly, otherwise it will be impossible to install it via `vue add` command or find it with Vue UI plugins search! +:::warning Предупреждение +Убедитесь, что плагин назван правильно, иначе его невозможно будет установить через команду `vue add` или найти с помощью поиска плагинов Vue UI! ::: -For better discoverability when a user searches for your plugin, put keywords describing your plugin in the `description` field of the plugin `package.json` file. +Для лучшей обнаруживаемости при поиске плагина пользователем, укажите ключевые слова, описывающие плагин, в поле `description` в его файле `package.json`. -Example: +Например: ```json { @@ -58,7 +58,7 @@ Example: } ``` -You should add the url to the plugin website or repository in the `homepage` or `repository` field so that a 'More info' button will be displayed in your plugin description: +Для отображения в описании плагина кнопки «More info» нужно указать URL-адрес веб-сайта плагина или его репозитория в полях `homepage` или `repository`: ```json { @@ -74,53 +74,53 @@ You should add the url to the plugin website or repository in the `homepage` or ## Генератор -A Generator part of the CLI plugin is usually needed when you want to extend your package with new dependencies, create new files in your project or edit existing ones. +Генератор — это часть плагина CLI, которая обычно необходима когда требуется расширить пакет новыми зависимостями, создать новые файлы в проекте или изменить существующие. -Inside the CLI plugin the generator should be placed in a `generator.js` or `generator/index.js` file. It will be invoked in two possible scenarios: +Внутри плагина CLI генератор должен быть расположен в файле `generator.js` или `generator/index.js`. Он будет вызываться в двух возможных сценариях: -- During a project's initial creation, if the CLI plugin is installed as part of the project creation preset. +- При первоначальном создании проекта, если подключаемый плагин CLI необходим в рамках выбранного пресета настроек создания проекта. -- When the plugin is installed after project's creation and invoked individually via `vue add` or `vue invoke`. +- При установке плагина после создания проекта через команду `vue add` или `vue invoke`. -A generator should export a function which receives three arguments: +Генератор должен экспортировать функцию, которая принимает три аргумента: -1. A [GeneratorAPI](generator-api.md) instance; +1. Экземпляр [GeneratorAPI](generator-api.md); -2. The generator options for this plugin. These options are resolved during the [prompt](#prompts) phase of project creation, or loaded from a saved preset in `~/.vuerc`. For example, if the saved `~/.vuerc` looks like this: +2. Настройки генератора для плагина. Эти настройки разрешаются с помощью [интерактивных подсказок](#интерактивные-подсказки) во время фазы создания проекта или загружаются из сохранённого пресета в `~/.vuerc`. Например, если сохранённый файл `~/.vuerc` выглядит так: -```json -{ - "presets" : { - "foo": { - "plugins": { - "@vue/cli-plugin-foo": { "option": "bar" } + ```json + { + "presets" : { + "foo": { + "plugins": { + "@vue/cli-plugin-foo": { "option": "bar" } + } + } } } - } -} -``` + ``` -And if the user creates a project using the `foo` preset, then the generator of `@vue/cli-plugin-foo` will receive `{ option: 'bar' }` as its second argument. + Если пользователь создаёт проект, используя пресет `foo`, то генератор `@vue/cli-plugin-foo` получит `{ option: 'bar' }` в качестве второго аргумента. -For a 3rd party plugin, the options will be resolved from the prompts or command line arguments when the user executes `vue invoke` (see [Prompts](#prompts)). + Для сторонних плагинов настройки будут разрешаются из интерактивных подсказок или аргументов командной строки, когда пользователь вызывает `vue invoke` (см. [интерактивные подсказки](#интерактивные-подсказки)). -3. The entire preset (`presets.foo`) will be passed as the third argument. +3. Всё содержимое пресета (`presets.foo`) будет передано в качестве третьего аргумента. ### Создание новых шаблонов -When you call `api.render('./template')`, the generator will render files in `./template` (resolved relative to the generator file) with [EJS](https://github.com/mde/ejs). +При вызове команды `api.render('./template')` генератор будет компилировать файлы из каталога `./template` (путь разрешается относительно файла генератора) с помощью [EJS](https://github.com/mde/ejs). -Let's imagine we're creating [vue-cli-auto-routing](https://github.com/ktsn/vue-cli-plugin-auto-routing) plugin and we want to make the following changes to the project on plugin invoke: +Представим, что разрабатываем плагин [vue-cli-auto-routing](https://github.com/ktsn/vue-cli-plugin-auto-routing) и хотим внести следующие изменения в проект при его вызове: -- create a `layouts` folder with a default layout file; -- create a `pages` folder with `about` and `home` pages; -- add a `router.js` to the `src` folder root +- создать каталог `layouts` с файлом шаблона по умолчанию; +- создать каталог `pages` со страницами `about` и `home`; +- добавить файл `router.js` в каталоге `src` -To render this structure, you need to create it first inside the `generator/template` folder: +Для создания такой структуры нужно сначала создать её внутри каталога `generator/template`: -![Generator structure](/generator-template.png) +![Структура файлов генератора](/generator-template.png) -After template is created, you should add `api.render` call to the `generator/index.js` file: +После создания шаблона необходимо добавить вызов `api.render` в файле `generator/index.js`: ```js module.exports = api => { @@ -130,7 +130,7 @@ module.exports = api => { ### Изменение существующих шаблонов -In addition, you can inherit and replace parts of an existing template file (even from another package) using YAML front-matter: +Кроме того, можно унаследовать или заменить части существующего файла шаблона (даже из другого пакета) используя YAML front-matter: ```ejs --- @@ -140,12 +140,12 @@ replace: !!js/regexp / ``` -It's also possible to do multiple replaces, although you will need to wrap your replace strings within `<%# REPLACE %>` and `<%# END_REPLACE %>` blocks: +Также есть возможность заменять сразу несколько мест, для этого потребуется обернуть заменяющие строки в блоки `<%# REPLACE %>` и `<%# END_REPLACE %>`: ```ejs --- @@ -156,13 +156,13 @@ replace: --- <%# REPLACE %> -Replace Welcome Message +Заменяем сообщение с приветствием <%# END_REPLACE %> <%# REPLACE %> <%# END_REPLACE %> @@ -170,26 +170,26 @@ export default { ### Ограничения по именованию файлов -If you want to render a template file that either begins with a dot (i.e. `.env`) you will have to follow a specific naming convention, since dotfiles are ignored when publishing your plugin to npm: +При необходимости создания шаблона файла, имя которого начинается с точки (например, `.env`), необходимо следовать определённому соглашению об именовании, поскольку при публикации плагина в npm такие файлы игнорируются: ```bash -# dotfile templates have to use an underscore instead of the dot: +# Шаблон файла должен использовать символ подчёркивания вместо точки: /generator/template/_env -# When calling api.render('./template'), this will be rendered in the project folder as: +# При вызове api.render('./template') в каталоге проекта он будет сгенерирован как: /generator/template/.env ``` -Consequently, this means that you also have to follow a special naming convention if you want to render file whose name actually begins with an underscore: +Следовательно, также потребуется придерживаться определённого соглашения об именовании, если требуется сгенерировать файл, имя которого начинается с подчёркивания: ```bash -# such templates have to use two underscores instead of one: +# Шаблоны таких файлов должны использовать 2 символа подчёркивания вместо одного: /generator/template/__variables.scss -# When calling api.render('./template'), this will be rendered in the project folder as: +# При вызове api.render('./template') в каталоге проекта он будет сгенерирован как: /generator/template/_variables.scss ``` @@ -197,7 +197,7 @@ Consequently, this means that you also have to follow a special naming conventio ### Расширение пакета -If you need to add an additional dependency to the project, create a new npm script or modify `package.json` in any other way, you can use API `extendPackage` method. +Если нужно добавить новую зависимость к проекту, создать npm script или изменить `package.json` любым другим способом, можно использовать метод API `extendPackage`. ```js // generator/index.js @@ -211,9 +211,9 @@ module.exports = api => { } ``` -In the example above we added one dependency: `vue-router-layout`. During the plugin invocation this npm module will be installed and this dependency will be added to the user `package.json` file. +В примере выше добавляется одна зависимость: `vue-router-layout`. При вызове плагина этот npm-пакет будет установлен и зависимость добавлена в пользовательский файл `package.json`. -With the same API method we can add new npm tasks to the project. To do so, we need to specify task name and a command that should be run in the `scripts` section of the user `package.json`: +Этим же методом API можно добавлять npm-задачи в проект. Для этого нужно указать имя задачи и команду, которая будет выполняться, для добавления в секцию `scripts` файла `package.json`: ```js // generator/index.js @@ -227,13 +227,13 @@ module.exports = api => { } ``` -In the example above we're adding a new `greet` task to run a custom vue-cli service command created in [Service section](#add-a-new-cli-service-command). +В примере выше добавляется новая задача `greet`, которая будет запускать специальную команду сервиса vue-cli, создание которой подробнее описано в разделе [плагина для сервиса](#добавnение-новой-команды-в-cli-service). ### Изменение основного файла -With generator methods you can make changes to the project files. The most usual case is some modifications to `main.js` or `main.ts` file: new imports, new `Vue.use()` calls etc. +С помощью методов генератора можно вносить изменения и в файлы проекта. Наиболее распространённым случаем является изменение основного файла `main.js` или `main.ts`: добавление новых импортов, вызовы новых `Vue.use()` и т.д. -Let's consider the case where we have created a `router.js` file via [templating](#creating-new-templates) and now we want to import this router to the main file. We will use two Generator API methods: `entryFile` will return the main file of the project (`main.js` or `main.ts`) and `injectImports` serves for adding new imports to this file: +Рассмотрим случай, когда файл `router.js` создан с помощью [генерации новых шаблонов](#создание-новых-шабnонов) и теперь требуется импортировать этот маршрутизатор в основной файл. Для этого используем два метода API генератора: `entryFile` вернёт основной файл проекта (`main.js` или `main.ts`), а `injectImports` предоставит возможность добавить новые импорты в этот файл: ```js // generator/index.js @@ -241,9 +241,9 @@ Let's consider the case where we have created a `router.js` file via [templating api.injectImports(api.entryFile, `import router from './router'`) ``` -Now, when we have a router imported, we can inject this router to the Vue instance in the main file. We will use `afterInvoke` hook which is to be called when the files have been written to disk. +Теперь, когда маршрутизатор импортирован, можно внедрить его в экземпляр Vue в основном файле. Для этого используем хук `afterInvoke`, который вызывается после записи файлов на диск. -First, we need to read main file content with Node `fs` module (which provides an API for interacting with the file system) and split this content on lines: +Сначала нужно прочитать содержимое основного файла с помощью модуля Node `fs` (который предоставляет API для взаимодействия с файловой системой) и разделить содержимое на строки: ```js // generator/index.js @@ -257,7 +257,7 @@ module.exports.hooks = (api) => { } ``` -Then we should to find the string containing `render` word (it's usually a part of Vue instance) and add our `router` as a next string: +Затем находим строку, содержащую слово `render` (это обычно будет часть экземпляра Vue), и добавляем `router` в качестве следующей строки: ```js{9-10} // generator/index.js @@ -274,7 +274,7 @@ module.exports.hooks = (api) => { } ``` -Finally, you need to write the content back to the main file: +Наконец, нужно сохранить содержимое обратно в основной файл: ```js{12-13} // generator/index.js @@ -296,17 +296,17 @@ module.exports.hooks = (api) => { ## Плагин для сервиса -Service plugin serves for modifying webpack config, creating new vue-cli service commands or changing existing commands (such as `serve` and `build`). +Плагин для сервиса позволяет вносить изменения в конфигурацию webpack, создавать новые vue-cli команды или изменять существующие (такие как `serve` и `build`). -Service plugins are loaded automatically when a Service instance is created - i.e. every time the `vue-cli-service` command is invoked inside a project. It's located in the `index.js` file in CLI plugin root folder. +Плагин для сервиса автоматически загружается при создании экземпляра сервиса — т.е. при каждом вызове команды `vue-cli-service` внутри проекта. Он располагается в файле `index.js` в корневом каталоге плагина CLI. -A service plugin should export a function which receives two arguments: +Плагин для сервиса должен экспортировать функцию, которая принимает два аргумента: -- A [PluginAPI](plugin-api.md) instance +- Экземпляр [PluginAPI](plugin-api.md) -- An object containing project local options specified in `vue.config.js`, or in the `"vue"` field in `package.json`. +- Объект, содержащий локальные настройки проекта, указанные в файле `vue.config.js` или в поле `"vue"` файла `package.json`. -The minimal required code in the service plugin file is the following: +Минимально необходимый код файла плагина сервиса приведён ниже: ```js module.exports = () => {} @@ -314,7 +314,7 @@ module.exports = () => {} ### Изменение конфигурации webpack -The API allows service plugins to extend/modify the internal webpack config for different environments. For example, here we're modifying webpack config with webpack-chain to include `vue-auto-routing` webpack plugin with given parameters: +API позволяет плагину для сервиса расширять/изменять внутреннюю конфигурацию webpack для различных окружений. Например, модифицируем конфигурацию webpack с помощью webpack-chain для добавления плагина `vue-auto-routing` с заданными параметрами: ```js const VueAutoRoutingPlugin = require('vue-auto-routing/lib/webpack-plugin') @@ -333,70 +333,70 @@ module.exports = (api, options) => { } ``` -You can also use `configureWebpack` method to modify the webpack config or return object to be merged with webpack-merge. +Также можно использовать метод `configureWebpack` для изменении конфигурации webpack или возврата объекта, который будет объединён с помощью webpack-merge. ### Добавление новой команды в cli-service -With service plugin you can register a new cli-service command in addition to standard ones (i.e. `serve` and `build`). You can do it with a `registerCommand` API method. +С помощью плагина для сервиса можно зарегистрировать новую команду в cli-service в дополнение к стандартным (т.е. `serve` и `build`). Для этого можно использовать метод API `registerCommand`. -Here is an example of creating a simple new command that will print a greeting to developer console: +Пример создания простой новой команды, которая выводит приветствие в консоли разработчика: ```js api.registerCommand( 'greet', { - description: 'Writes a greeting to the console', + description: 'Выводит приветствие в консоли', usage: 'vue-cli-service greet' }, () => { - console.log(`👋 Hello`) + console.log(`👋 Привет`) } ) ``` -In this example we provided the command name (`'greet'`), an object of command options with `description` and `usage`, and a function that will be run on `vue-cli-service greet` command. +В этом примере мы задаём имя команды (`'greet'`), объект настроек с опциями `description` и `usage`, а также функцию которая выполняется при запуске команды `vue-cli-service greet`. -:::tip -You can add new command to the list of project npm scripts inside the `package.json` file [via Generator](#extending-package). +:::tip Совет +Также можно добавить новую команду в список npm-скриптов проекта внутри файла `package.json` [с помощью генератора](#расширение-пакета). ::: -If you try to run a new command in the project with your plugin installed, you will see the following output: +При запуске новой команды в проекте с установленным плагином появится сообщение в консоли: ```bash $ vue-cli-service greet -👋 Hello! +👋 Привет! ``` -You can also specify a list of available options for a new command. Let's add the option `--name` and change the function to print this name if it's provided. +Также можно указать список доступных опций для новой команды. Добавим опцию `--name` и изменим функцию для вывода этого имени, если оно было указано. ```js api.registerCommand( 'greet', { - description: 'Writes a greeting to the console', + description: 'Выводит приветствие в консоль', usage: 'vue-cli-service greet [options]', - options: { '--name': 'specifies a name for greeting' } + options: { '--name': 'определяет имя для приветствия' } }, args => { if (args.name) { - console.log(`👋 Hello, ${args.name}!`); + console.log(`👋 Привет, ${args.name}!`); } else { - console.log(`👋 Hello!`); + console.log(`👋 Привет!`); } } ); ``` -Now, if you a `greet` command with a specified `--name` option, this name will be added to console message: +Теперь, если запустить команду `greet` с указанной опцией `--name`, это имя будет выведено в сообщение в консоли: ```bash -$ vue-cli-service greet --name 'John Doe' -👋 Hello, John Doe! +$ vue-cli-service greet --name 'Джон' +👋 Привет, Джон! ``` ### Изменение существующей команды в cli-service -If you want to modify an existing cli-service command, you can retrieve it with `api.service.commands` and add some changes. We're going to print a message to the console with a port where application is running: +Если необходимо изменить существующую команду cli-service, можно получить её с помощью `api.service.commands` и внести некоторые изменения. Мы выведем сообщение в консоль с номером порта, на котором запущено приложение: ```js const { serve } = api.service.commands @@ -406,17 +406,17 @@ const serveFn = serve.fn serve.fn = (...args) => { return serveFn(...args).then(res => { if (res && res.url) { - console.log(`Project is running now at ${res.url}`) + console.log(`Проект запущен по адресу ${res.url}`) } }) } ``` -In the example above we retrieve the `serve` command from the list of existing commands; then we modify its `fn` part (`fn` is the third parameter passed when you create a new command; it specifies the function to run when running the command). With the modification done the console message will be printed after `serve` command has run successfully. +В примере выше сначала получаем команду `serve` из списка существующих команд; затем изменяем её `fn`-часть (`fn` — это третий параметр, передаваемый при создании новой команды; он определяет функцию, запускаемую при выполнении команды). После внесения модификаций сообщение в консоли будет выводиться после успешного выполнения команды `serve`. -### Определение режимов работы для команд +### Определение режима работы команды -If a plugin-registered command needs to run in a specific default mode, the plugin needs to expose it via `module.exports.defaultModes` in the form of `{ [commandName]: mode }`: +Если команда, зарегистрированная плагином, должна запускаться в определённом режиме, плагин должен определять его через `module.exports.defaultModes` в виде `{ [commandName]: mode }`: ```js module.exports = api => { @@ -430,17 +430,17 @@ module.exports.defaultModes = { } ``` -This is because the command's expected mode needs to be known before loading environment variables, which in turn needs to happen before loading user options / applying the plugins. +Это связано с тем, что ожидаемый режим для работы команды должен быть известен до загрузки переменных окружения, что произойдёт перед загрузкой пользовательских настроек / применением плагинов. -## Подсказки +## Интерактивные подсказки -Prompts are required to handle user choices when creating a new project or adding a new plugin to the existing one. All prompts logic is stored inside the `prompts.js` file. The prompts are presented using [inquirer](https://github.com/SBoudrias/Inquirer.js) under the hood. +Интерактивные подсказки предназначены для обработки пользовательского выбора при создании нового проекта или добавлении нового плагина в существующий проект. Вся логика интерактивных подсказок расположена в файле `prompts.js`. Эти подсказки реализованы с помощью пакета [inquirer](https://github.com/SBoudrias/Inquirer.js) под капотом. -When user initialize the plugin by calling `vue invoke`, if the plugin contains a `prompts.js` in its root directory, it will be used during invocation. The file should export an array of [Questions](https://github.com/SBoudrias/Inquirer.js#question) that will be handled by Inquirer.js. +Когда пользователь инициализирует плагин вызовом `vue invoke`, если плагин содержит `prompts.js` в своем корневом каталоге, он будет использован во время вызова. Файл должен экспортировать массив [вопросов](https://github.com/SBoudrias/Inquirer.js#question), которые затем будут обработаны Inquirer.js. -You should export directly array of questions, or export function that return those. +Необходимо экспортировать массив вопросов или функцию, которая возвращает его. -e.g. directly array of questions: +Например, экспорт непосредственно массива вопросов: ```js // prompts.js @@ -448,7 +448,7 @@ module.exports = [ { type: 'input', name: 'locale', - message: 'The locale of project localization.', + message: 'Используемый язык для локализации проекта.', validate: input => !!input, default: 'en' }, @@ -456,28 +456,28 @@ module.exports = [ ] ``` -e.g. function that return array of questions: +Или функция, которая возвращает массив вопросов: ```js // prompts.js -// pass `package.json` of project to function argument +// в качестве аргумента функции передаётся `package.json` проекта module.exports = pkg => { const prompts = [ { type: 'input', name: 'locale', - message: 'The locale of project localization.', + message: 'Используемый язык для локализации проекта.', validate: input => !!input, default: 'en' } ] - // add dynamically prompt + // динамическое добавление интерактивной подсказки if ('@vue/cli-plugin-eslint' in (pkg.devDependencies || {})) { prompts.push({ type: 'confirm', name: 'useESLintPluginVueI18n', - message: 'Use ESLint plugin for Vue I18n ?' + message: 'Использовать ESLint-плагин для Vue I18n?' }) } @@ -485,15 +485,15 @@ module.exports = pkg => { } ``` -The resolved answers object will be passed to the plugin's generator as options. +Итоговый объект с ответами будет передан в генератор плагина в качестве настроек. -Alternatively, the user can skip the prompts and directly initialize the plugin by passing options via the command line, e.g.: +Кроме того, пользователь может пропускать интерактивные подсказки и напрямую инициализировать плагин, передав опции через командную строку, например: ```bash vue invoke my-plugin --mode awesome ``` -Prompt can have [different types](https://github.com/SBoudrias/Inquirer.js#prompt-types) but the most widely used in CLI are `checkbox` and `confirm`. Let's add a `confirm` prompt and then use it in plugin generator to create a condition for [template rendering](#creating-new-templates). +Интерактивные подсказки могут быть [различных типов](https://github.com/SBoudrias/Inquirer.js#prompt-types), но наиболее широко в CLI используются `checkbox` и `confirm`. Добавим интерактивную подсказку `confirm` и используем её в генераторе плагина чтобы создавать по условию [новый шаблон файла](#создание-новых-шабnонов). ```js // prompts.js @@ -502,17 +502,17 @@ module.exports = [ { name: `addExampleRoutes`, type: 'confirm', - message: 'Add example routes?', + message: 'Добавить примеры маршрутов?', default: false } ] ``` -On plugin invoke user will be prompted with the question about example routes and the default answer will be `No`. +При вызове плагина пользователю будет предложено ответить на вопрос о добавлении примеров маршрутов и ответом по умолчанию будет выбран «Нет». -![Prompts example](/prompts-example.png) +![Пример интерактивных подсказок](/prompts-example.png) -If you want to use the result of the user's choice in generator, it will be accessible with the prompt name. We can add a modification to `generator/index.js`: +Если необходимо использовать результат выбора пользователя в генераторе, ответ будет доступен по имени интерактивной подсказки. Теперь можно модифицировать `generator/index.js`: ```js if (options.addExampleRoutes) { @@ -522,96 +522,96 @@ if (options.addExampleRoutes) { } ``` -Now template will be rendered only if user agreed to create example routes. +Шаблон будет генерироваться только если пользователь согласился создать примеры маршрутов. ## Локальная установка плагина -While working on your plugin, you need to test it and check how it works locally on a project using Vue CLI. You can use an existing project or create a new one just for testing purposes: +При разработке плагина может потребоваться протестировать его и проверить как он работает локально на проекте с помощью Vue CLI. Можно использовать существующий проект или создать новый в целях тестирования: ```bash vue create test-app ``` -To add the plugin, run the following command in the root folder of the project: +Для добавления плагина выполните следующую команду в корневом каталоге проекта: ```bash npm install --save-dev file:/full/path/to/your/plugin vue invoke ``` -You need to repeat these steps every time you make changes to your plugin. +Это необходимо повторять каждый раз, когда вносите изменения в плагин. -Another way to add a plugin is to leverage the power of Vue UI. You can run it with: +Другой способ добавления плагина — воспользоваться возможностями Vue UI. Выполните команду: ```bash vue ui ``` -You will have a UI open in browser window on `localhost:8000`. Go to the `Vue Project Manager` tab: +Пользовательский интерфейс откроется в браузере по адресу `localhost:8000`. Перейдите на вкладку `Vue Project Manager`: -![Vue Project Manager](/ui-project-manager.png) +![Менеджер проекта Vue](/ui-project-manager.png) -And look for your test project name there: +И найдите в списке название тестового проекта: -![UI Plugins List](/ui-select-plugin.png) +![Список плагинов в UI](/ui-select-plugin.png) -Click on your application name, go to the Plugins tab (it has a puzzle icon) and then click the `Add new plugin` button on the top right. In the new view you will see a list of Vue CLI plugins accessible via npm. There is also a `Browse local plugin` button on the bottom of the page: +Нажмите на названии приложения, перейдите на вкладку плагинов (значок пазла) и затем нажмите кнопку `Add new plugin` (Добавить новый плагин) в правом верхнем углу. На новой странице будет отображён список плагинов Vue CLI, доступных через npm. В нижней части страницы будет кнопка `Browse local plugin` (Выбор локального плагина): -![Browse local plugins](/ui-browse-local-plugin.png) +![Выбор локальный плагин](/ui-browse-local-plugin.png) -After you click it, you can easily search for you plugin and add it to the project. After this you will be able to see it in plugins list and apply all changes done to the plugin via simply clicking on `Refresh` icon: +В окне выбора легко найти тестируемый плагин и добавить в проект. После этого его можно будет увидеть в списке плагинов и применять изменения к плагину просто нажав на иконку обновления: ![Refresh plugin](/ui-plugin-refresh.png) ## Интеграция с UI -Vue CLI has a great UI tool which allows user to scaffold and manage a project with a nice graphical interface. The Vue CLI plugin can be integrated to this interface. UI provides an additional functionality to CLI plugins: +Vue CLI имеет отличный UI с помощью которого пользователь сможет разворачивать и управлять проектом в удобном графическом интерфейсе. Плагин Vue CLI может интегрироваться в этот интерфейс. UI предоставляет дополнительные возможности для плагинов CLI: -- you can run npm tasks, including plugin-specific ones, directly from the UI; -- you can display custom configurations for your plugin. For example, [vue-cli-plugin-apollo](https://github.com/Akryum/vue-cli-plugin-apollo) provides the following configuration screen for Apollo server: +- можно запускать npm-задачи, в том числе и специфичные для плагинов, напрямую из UI; +- можно отображать экран с настройками конфигурации плагина. Например, [vue-cli-plugin-apollo](https://github.com/Akryum/vue-cli-plugin-apollo) предоставляет отдельный экран для конфигурации сервера Apollo: -![UI Configuration Screen](/ui-configuration.png) -- when creating the project, you can display [prompts](#prompts) visually -- you can add localizations for your plugin if you want to support multiple languages -- you can make your plugin discoverable in the Vue UI search +![Экран конфигурации в UI](/ui-configuration.png) +- можно отображать [интерактивные подсказки](#интерактивные-подсказки) при создании проекта +- можно добавлять локализации плагина при необходимости поддержки нескольких языков +- можно сделать плагин обнаруживаемым при поиске в Vue UI -All the logic connected to Vue UI should be placed to `ui.js` file in the root folder or in the `ui/index.js`. The file should export a function which gets the api object as argument: +Вся логика, связанная с Vue UI, должна располагаться в файле `ui.js` в корневом каталоге или в `ui/index.js`. Файл должен экспортировать функцию, которая принимает аргументом объект api: ```js module.exports = api => { - // Use the API here... + // Используем API здесь... } ``` ### Отображение задачи в UI -Vue CLI plugin allows you not only add new npm tasks to the project [via Generator](#extending-package) but also create a view for them in Vue UI. It's useful when you want to run the the task right from the UI and see its output there. +Плагин Vue CLI позволяет не только добавлять новые npm-задачи в проект [через Generator](#расширение-пакета), но и создавать новые экраны для использования в Vue UI. Это полезно, если хочется запускать задачу прямо из пользовательского интерфейса и видеть результаты её выполнения. -Let's add a `greet` task created with [Generator](#extending-package) to the UI. Tasks are generated from the `scripts` field in the project `package.json` file. You can 'augment' the tasks with additional info and hooks thanks to the `api.describeTask` method. Let's provide some additional information about our task: +Добавим в пользовательский интерфейс задачу `greet`, которую создавали с помощью [генератора](#расширение-пакета). Список задач генерируются из поля `scripts` файла проекта `package.json`. Можно «дополнить» задачу дополнительной информацией и хуками с помощью метода `api.describeTask`: ```js module.exports = api => { api.describeTask({ match: /greet/, - description: 'Prints a greeting in the console', - link: 'https://cli.vuejs.org/dev-guide/plugin-dev.html#core-concepts' + description: 'Выводит приветствие в консоль', + link: 'https://cli.vuejs.org/ru/dev-guide/plugin-dev.html' }) } ``` -Now if you explore your project in the Vue UI, you will find your task added to the `Tasks` section. You can see a name of the task, provided description, a link icon that leads to the provided URL and also an output screen to show the task output: +Теперь в обзоре проекта через Vue UI можно увидеть, что задача добавлена в секцию `Tasks`. Можно увидеть её название, предоставленное описание, иконку ссылки, которая ведёт на указанный URL, а также экран для отображения результатов выполнения задачи: -![UI Greet task](/ui-greet-task.png) +![Задача Greet в UI](/ui-greet-task.png) ### Отображение экрана конфигурации -Sometimes your project can have custom configuration files for different features or libraries. With Vue CLI plugin you can display this config in Vue UI, change it and save (saving will change the corresponding config file in your project). By default, Vue CLI project has a main configuration screen representing `vue.config.js` settings. If you included ESLint to your project, you will see also a ESLint configuration screen: +Иногда проект может иметь пользовательские файлы конфигураций для различных функций или библиотек. С помощью плагина Vue CLI можно отображать эту конфигурацию в Vue UI, изменять её и сохранять (сохранение изменит соответствующий конфигурационный файл в вашем проекте). По умолчанию, проект Vue CLI имеет главный экран конфигурации, отображающий настройки из `vue.config.js`. Если добавить ESLint в проект, то будет виден также экран конфигурации ESLint: ![UI Configuration Screen](/ui-configuration-default.png) -Let's build a custom configuration for our plugin. First of all, after you add your plugin to the existing project, there should be a file containing this custom config. This means you need to add this file to `template` folder on the [templating step](#creating-new-templates). +Давайте создадим пользовательский экран конфигурации для плагина. Прежде всего, после добавления плагина в существующий проект, должен быть файл, содержащий эту пользовательскую конфигурацию. Это означает, что требуется добавить этот файл в каталог `template` для [шага создания новых шаблонов](#создание-новых-шабnонов). -By default, a configuration UI might read and write to the following file types: `json`, `yaml`, `js`, `package`. Let's name our new file `myConfig.js` and place in it the root of `template` folder: +По умолчанию пользовательский интерфейс конфигурации может читать и записывать файлы следующих форматов: `json`, `yaml`, `js`, `package`. Назовём новый файл `myConfig.js` и поместим его в корне каталога `template`: ``` . @@ -625,7 +625,7 @@ By default, a configuration UI might read and write to the following file types: └── router.js ``` -Now you need to add some actual config to this file: +Теперь необходимо добавить в этот файл какую-то актуальную конфигурацию: ```js // myConfig.js @@ -635,52 +635,52 @@ module.exports = { } ``` -After your plugin is invoked, the `myConfig.js` file will be rendered in the project root directory. Now let's add a new configuration screen with the `api.describeConfig` method in the `ui.js` file: +После вызова плагина файл `myConfig.js` будет сгенерирован в корневом каталоге проекта. Теперь добавим новый экран конфигурации с помощью метода `api.describeConfig` в файле `ui.js`: -First you need to pass some information: +Сначала нужно передать некоторую информацию: ```js // ui.js api.describeConfig({ - // Unique ID for the config + // Уникальный ID для конфигурации id: 'org.ktsn.vue-auto-routing.config', - // Displayed name - name: 'Greeting configuration', - // Shown below the name - description: 'This config defines the color of the greeting printed', - // "More info" link + // Отображаемое имя + name: 'Настройка приветствия', + // Описание, отображаемое под именем + description: 'Можно настроить цвет текста приветствия', + // Ссылка «More info» link: 'https://github.com/ktsn/vue-cli-plugin-auto-routing#readme' }) ``` -:::danger Warning -Make sure to namespace the id correctly, since it must be unique across all plugins. It's recommended to use the [reverse domain name notation](https://en.wikipedia.org/wiki/Reverse_domain_name_notation) +:::danger Предупреждение +Убедитесь в точности пространства имён для id, так как он должен быть уникальным для всех плагинов. Рекомендуется использовать [обратную нотацию записи доменного имени](https://en.wikipedia.org/wiki/Reverse_domain_name_notation) ::: -#### Config logo +#### Логотип конфигурации -You can also select an icon for your config. It can be either a [Material icon](https://material.io/tools/icons/?style=baseline) code or a custom image (see [Public static files](ui-api.md#public-static-files)). +Можно выбрать значок для конфигурации. Это может быть код [значка Material](https://material.io/tools/icons/?style=baseline) или пользовательское изображение (см. [публичные статические файлы](ui-api.md#пубnичные-статические-файnы)). ```js // ui.js api.describeConfig({ /* ... */ - // Config icon + // Значок конфигурации icon: 'color_lens' }) ``` -If you don't specify an icon, the plugin logo will be displayed if any (see [Logo](#logo)). +Если значок не указан, будет использоваться логотип плагина если такой есть (см. [Логотип](#логотип)). -#### Config files +#### Файлы конфигурации -Now you need to provide your configuration file to UI: this way you could read its content and save changes to it. You need to choose a name for your config file, select its format and provide a path to the file: +Теперь, если необходимо предоставить файл конфигурации для UI: таким образом можно будет читать его содержимое и сохранять изменения в нём. Для этого необходимо указать имя конфигурационного файла, выбрать его формат и указать путь к нему: ```js api.describeConfig({ - // other config properties + // другие свойства конфигурации files: { myConfig: { js: ['myConfig.js'] @@ -689,21 +689,21 @@ api.describeConfig({ }) ``` -There can be more than one file provided. Say, if we have `myConfig.json`, we can provide it with `json: ['myConfig.json']` property. The order is important: the first filename in the list will be used to create the config file if it doesn't exist. +Можно указывать больше одного файла. Например, если есть `myConfig.json`, можно указать его в свойстве `json: ['myConfig.json']`. Порядок важен: первое имя файла в списке будет использовано для создания файла конфигурации, если его не существует. -#### Display config prompts +#### Отображение интерактивных подсказок конфигурации -We want to display an input field for color property on the configuration screen. To do so, we need a `onRead` hook that will return a list of prompts to be displayed: +Отобразим поля ввода для свойства цвета на экране конфигурации. Для этого используем хук `onRead`, который вернёт список интерактивных подсказок для отображения: ```js api.describeConfig({ - // other config properties + // другие свойства конфигурации onRead: ({ data }) => ({ prompts: [ { name: `color`, type: 'input', - message: 'Define the color for greeting message', + message: 'Цвет сообщения с приветствием', value: 'white' } ] @@ -711,11 +711,11 @@ api.describeConfig({ }) ``` -In the example above we specified the input prompt with the value of 'white'. This is how our configuration screen will look with all the settings provided above: +В примере выше мы добавили интерактивную подсказку в виде поля со значением `white`. Вот как будет выглядеть экран конфигурации со всеми приведёнными выше настройками: -![UI Config Start](/ui-config-start.png) +![Начало конфигурации UI](/ui-config-start.png) -Now let's replace hardcoded `white` value with the property from the config file. In the `onRead` hook `data` object contains the JSON result of each config file content. In our case, the content of `myConfig.js` was +Теперь заменим явно указанное значение `white` на свойство из конфигурационного файла. В хуке `onRead` объект `data` содержит JSON с результатом каждого файла конфигурации. В нашем случае, содержание `myConfig.js` было таким: ```js // myConfig.js @@ -725,19 +725,19 @@ module.exports = { } ``` -So, the `data` object will be +Поэтому объект `data` будет таким: ```js { - // File + // Файл myConfig: { - // File data + // Данные файла color: 'black' } } ``` -It's easy to see that we need `data.myConfig.color` property. Let's change `onRead` hook: +Легко увидеть, что нам необходимо свойство `data.myConfig.color`. Изменим хук `onRead`: ```js // ui.js @@ -747,20 +747,20 @@ onRead: ({ data }) => ({ { name: `color`, type: 'input', - message: 'Define the color for greeting message', + message: 'Цвет сообщения с приветствием', value: data.myConfig && data.myConfig.color } ] }), ``` -::: tip -Note that `myConfig` may be undefined if the config file doesn't exist when the screen is loaded. +::: tip Совет +Обратите внимание, что `myConfig` может быть неопределён, если конфигурационного файла не существует при загрузке экрана. ::: -You can see that on the configuration screen `white` is replaced with `black`. +Как можно увидеть на экране конфигурации значение `white` заменилось на `black`. -We can also provide a default value if the config file is not present: +Также можно предоставить значение по умолчанию, если конфигурационный файл отсутствует: ```js // ui.js @@ -770,7 +770,7 @@ onRead: ({ data }) => ({ { name: `color`, type: 'input', - message: 'Define the color for greeting message', + message: 'Цвет сообщения с приветствием', value: data.myConfig && data.myConfig.color, default: 'black', } @@ -778,9 +778,9 @@ onRead: ({ data }) => ({ }), ``` -#### Save config changes +#### Сохранение конфигурации после изменений -We just read the content of `myConfig.js` and used it on the configuration screen. Now let's try to save any changes done in the color input field to the file. We can do it with the `onWrite` hook: +Пока мы лишь считали содержимое `myConfig.js` и использовали его на экране конфигурации. Теперь попробуем сохранить все изменения в файл. Это можно сделать с помощью хука `onWrite`: ```js // ui.js @@ -793,7 +793,7 @@ api.describeConfig({ }) ``` -`onWrite` hook can take a lot of [arguments](ui-api.html#save-config-changes) but we will need only two of them: `prompts` and `api`. First one is current prompts runtime objects - we will get a prompt id from it and retrieve an answer with this id. To retrieve the answer we'll use `async getAnswer()` method from the `api`: +Хук `onWrite` принимает множество [аргументов](ui-api.html#сохранение-изменений-конфигурации), но нам необходимо только два из них: `prompts` и `api`. В первом текущие объекты интерактивных подсказок — мы молучим id интерактивной подсказки и ответ для этого id. Для получения ответа воспользуемся методом `async getAnswer()` из `api`: ```js // ui.js @@ -807,7 +807,7 @@ async onWrite({ api, prompts }) { } ``` -Now if you try to change the value in the color input field from `black` to `red` on the config screen and press `Save the changes`, you will observe that `myConfig.js` file in your project has been changed as well: +Теперь, если изменить значение цвета в поле ввода с `black` на `red` на экране конфигурации и нажать кнопку `Save the changes`, то содержимое файла `myConfig.js` в проекте также изменится: ```js // myConfig.js @@ -817,65 +817,64 @@ module.exports = { } ``` -### Отображение подсказок +### Отображение интерактивных подсказок -If you want, you can display [prompts](#prompts) in the Vue UI as well. When installing your plugin through the UI, prompts will be shown on the plugin invocation step. +При желании можно также отображать [интерактивные подсказки](#интерактивные-подсказки) в Vue UI. При установке плагина через UI, интерактивные подсказки будут отображены на шаге вызова плагина. -You can extend the [inquirer object](#prompts-for-3rd-party-plugins) with additional properties. They are optional and only used by the UI: +[Объект inquirer](#prompts-for-3rd-party-plugins) можно расширить дополнительными свойствами. Они опциональны и используются только в UI: ```js // prompts.js module.exports = [ { - // basic prompt properties + // основные свойства интерактивных подсказок name: `addExampleRoutes`, type: 'confirm', - message: 'Add example routes?', + message: 'Добавить примеры маршрутов?', default: false, - // UI-related prompt properties - group: 'Strongly recommended', - description: 'Adds example pages, layouts and correct router config', - link: - 'https://github.com/ktsn/vue-cli-plugin-auto-routing/#vue-cli-plugin-auto-routing' + // свойства интерактивных подсказок для UI + group: 'Настоятельно рекомендуется', + description: 'Добавить примеры страниц, шаблонов и конфигурацию маршрутизатора', + link: 'https://github.com/ktsn/vue-cli-plugin-auto-routing/#vue-cli-plugin-auto-routing' } ] ``` -As a result, you will have this screen on plugin invocation: +В результате при вызове плагина появится такой экран: -![UI Prompts](/ui-prompts.png) +![Интерактивные подсказки в UI](/ui-prompts.png) ### Логотип -You can put a `logo.png` file in the root directory of the folder that will be published on npm. It will be displayed in several places: - - When searching for a plugin to install - - In the installed plugin list - - In the configurations list (by default) - - In the tasks list for augmented tasks (by default) +Можно поместить файл `logo.png` в корне каталога, который будет публиковаться в npm. Тогда его можно будет увидеть в нескольких местах: + - При поиска плагина для установки + - В списке установленных плагинов + - В списке конфигураций (по умолчанию) + - В списке дополненных задач (по умолчанию) -![Plugins](/plugins.png) +![Плагины](/plugins.png) -The logo should be a square non-transparent image (ideally 84x84). +Логотип должен быть квадратным изображением без прозрачности (в идеале 84x84). ## Публикация плагина в npm -To publish your plugin, you need to be registered an [npmjs.com](npmjs.com) and you should have `npm` installed globally. If it's your first npm module, please run +Для публикации плагина необходимо быть зарегистрированным на [npmjs.com](npmjs.com) и `npm` должна быть установлена глобально. Если это ваш первый npm-модуль, запустите команду: ```bash npm login ``` -Enter your username and password. This will store the credentials so you don’t have to enter it for every publish. +Введите имя пользователя и пароль. Это позволит сохранить учётные данные, чтобы не пришлось вводить их при каждой публикации. -:::tip -Before publishing a plugin, make sure you choose a right name for it! Name convention is `vue-cli-plugin-`. Check [Discoverability](#discoverability) section for more information +:::tip Совет +Перед публикацией плагина убедитесь, что выбрали правильно имя для него! Соглашение по именованию `vue-cli-plugin-`. Дополнительную информации см. в разделе [Именование и обнаруживаемость в поиске](#именование-и-обнаруживаемость-в-поиске). ::: -To publish a plugin, go to the plugin root folder and run this command in the terminal: +Для публикации плагина перейдите в корневой каталог и выполните команду в терминале: ```bash npm publish ``` -After successful publish, you should be able to add your plugin to the project created with Vue CLI with `vue add ` command. +После успешной публикации можно будет добавить ваш плагин в проект, созданный с помощью Vue CLI командой `vue add `. From 3b88ca523a81fd4945d0228979c42caee93d05fa Mon Sep 17 00:00:00 2001 From: Alex Sokolov <4497128+Alex-Sokolov@users.noreply.github.com> Date: Mon, 2 Dec 2019 17:14:55 +0300 Subject: [PATCH 30/31] docs: plugin-dev.md update --- docs/ru/dev-guide/plugin-dev.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/ru/dev-guide/plugin-dev.md b/docs/ru/dev-guide/plugin-dev.md index df79163bda..19c66ed234 100644 --- a/docs/ru/dev-guide/plugin-dev.md +++ b/docs/ru/dev-guide/plugin-dev.md @@ -793,7 +793,7 @@ api.describeConfig({ }) ``` -Хук `onWrite` принимает множество [аргументов](ui-api.html#сохранение-изменений-конфигурации), но нам необходимо только два из них: `prompts` и `api`. В первом текущие объекты интерактивных подсказок — мы молучим id интерактивной подсказки и ответ для этого id. Для получения ответа воспользуемся методом `async getAnswer()` из `api`: +Хук `onWrite` принимает множество [аргументов](ui-api.html#сохранение-изменений-конфигурации), но нам необходимо только два из них: `prompts` и `api`. В первом текущие объекты интерактивных подсказок — мы получим id интерактивной подсказки и ответ для этого id. Для получения ответа воспользуемся методом `async getAnswer()` из `api`: ```js // ui.js @@ -821,7 +821,7 @@ module.exports = { При желании можно также отображать [интерактивные подсказки](#интерактивные-подсказки) в Vue UI. При установке плагина через UI, интерактивные подсказки будут отображены на шаге вызова плагина. -[Объект inquirer](#prompts-for-3rd-party-plugins) можно расширить дополнительными свойствами. Они опциональны и используются только в UI: +Объект подсказки можно расширить дополнительными свойствами. Они опциональны и используются только в UI: ```js // prompts.js From f6783284710046bf0665bbffbed1add56921ea16 Mon Sep 17 00:00:00 2001 From: Alex Sokolov <4497128+Alex-Sokolov@users.noreply.github.com> Date: Mon, 2 Dec 2019 18:31:01 +0300 Subject: [PATCH 31/31] docs: plugin-dev.md update --- docs/ru/dev-guide/plugin-dev.md | 158 ++++++++++++++++---------------- 1 file changed, 79 insertions(+), 79 deletions(-) diff --git a/docs/ru/dev-guide/plugin-dev.md b/docs/ru/dev-guide/plugin-dev.md index 19c66ed234..191e7ddb27 100644 --- a/docs/ru/dev-guide/plugin-dev.md +++ b/docs/ru/dev-guide/plugin-dev.md @@ -8,14 +8,14 @@ sidebarDepth: 3 Плагин CLI — это npm-пакет, который может добавлять дополнительные возможности в проект с помощью Vue CLI. Эти функции могут включать в себя: -- изменение конфигурации webpack проекта — например, можно добавить новое правило для разрешения определённых расширений файлов, если плагин должен работать с этим типом файлов. Например, `@vue/cli-plugin-typescript` добавляет такое правило для разрешения файлов с расширениями `.ts` и `.tsx`; +- изменение конфигурации webpack проекта — например, можно добавить новое правило для поддержки файлов определённых расширений, если плагин должен работать с ними. Например, `@vue/cli-plugin-typescript` добавляет такое правило для работы с файлами `.ts` и `.tsx`; - добавление новых команд vue-cli-service — например, `@vue/cli-plugin-unit-jest` добавляет новую команду `test:unit`, которая позволяет разработчику запускать модульные тесты; -- расширение `package.json` — полезная опция, когда плагину для работы требуются новые зависимости и необходимо добавить их в раздел зависимостей проекта; -- создание новых и/или изменение старых файлов в проекте. Иногда полезно создать файл с примером компонента или изменить основной файл для добавления необходимых импортов; -- предоставление возможности выбора пользователем требуемых опций — например, можно уточнить необходимость создания примера компонента, упомянутого выше. +- расширение файла `package.json` — полезная опция, когда плагину для работы требуются новые зависимости и необходимо добавить их в раздел зависимостей проекта; +- создание новых и/или изменение существующих файлов в проекте. Иногда полезно создать файл с примером компонента или изменить основной файл для добавления новых импортов; +- предоставление пользователю возможности выбора требуемых опций — например, можно уточнить необходимость создания примера компонента, упомянутого выше. :::tip Совет -Не злоупотребляйте плагинами vue-cli! Если необходимо просто добавить какую-то новую зависимость в проект, например [Lodash](https://lodash.com/) — проще сделать это вручную через npm, чем создавать специальный плагин только для этого. +Не злоупотребляйте плагинами vue-cli! При необходимости просто добавить какую-то новую зависимость в проект, например [Lodash](https://lodash.com/) — лучше сделать это вручную, через npm, чем создавать специальный плагин для этого. ::: Плагин CLI всегда должен содержать [плагин для сервиса](#пnагин-дnя-сервиса) в качестве своего основного экспорта, и может опционально содержать [генератор](#генератор), [файл интерактивных подсказок](#интерактивные-подсказки) и [интеграцию с Vue UI](#интеграция-с-ui). @@ -36,14 +36,14 @@ sidebarDepth: 3 ## Именование и обнаруживаемость в поиске -Чтобы плагин CLI мог использоваться в проекте Vue CLI, он должен соответствовать соглашению по именованию `vue-cli-plugin-` или `@scope/vue-cli-plugin-`. Это позволит вашему плагину быть: +Чтобы плагин CLI мог использоваться в проекте Vue CLI, он должен соответствовать определённому соглашению по именованию `vue-cli-plugin-` или `@scope/vue-cli-plugin-`. Такой подход позволяет вашему плагину быть: - Обнаруживаемым `@vue/cli-service`; - Обнаруживаемым другими разработчиками при поиске; -- Устанавливаемым через `vue add ` или `vue invoke `. +- Устанавливаемым с помощью команд `vue add ` или `vue invoke `. :::warning Предупреждение -Убедитесь, что плагин назван правильно, иначе его невозможно будет установить через команду `vue add` или найти с помощью поиска плагинов Vue UI! +Убедитесь в правильности указанного имени плагина, иначе его невозможно будет установить через команду `vue add` или найти с помощью поиска плагинов в Vue UI! ::: Для лучшей обнаруживаемости при поиске плагина пользователем, укажите ключевые слова, описывающие плагин, в поле `description` в его файле `package.json`. @@ -58,7 +58,7 @@ sidebarDepth: 3 } ``` -Для отображения в описании плагина кнопки «More info» нужно указать URL-адрес веб-сайта плагина или его репозитория в полях `homepage` или `repository`: +Для отображения кнопки «More info» возле описания плагина нужно указать URL-адрес веб-сайта плагина или его репозитория в полях `homepage` или `repository`: ```json { @@ -74,13 +74,13 @@ sidebarDepth: 3 ## Генератор -Генератор — это часть плагина CLI, которая обычно необходима когда требуется расширить пакет новыми зависимостями, создать новые файлы в проекте или изменить существующие. +Генератор — это часть плагина CLI, которая обычно используется если требуется расширить пакет новыми зависимостями, создать новые файлы в проекте или изменить существующие. -Внутри плагина CLI генератор должен быть расположен в файле `generator.js` или `generator/index.js`. Он будет вызываться в двух возможных сценариях: +В структуре плагина CLI генератор должен располагаться в файле `generator.js` или `generator/index.js`. Он будет вызываться в двух случаях: - При первоначальном создании проекта, если подключаемый плагин CLI необходим в рамках выбранного пресета настроек создания проекта. -- При установке плагина после создания проекта через команду `vue add` или `vue invoke`. +- При установке плагина в созданном проекте командой `vue add` или `vue invoke`. Генератор должен экспортировать функцию, которая принимает три аргумента: @@ -100,27 +100,27 @@ sidebarDepth: 3 } ``` - Если пользователь создаёт проект, используя пресет `foo`, то генератор `@vue/cli-plugin-foo` получит `{ option: 'bar' }` в качестве второго аргумента. + То когда пользователь создаёт проект, используя пресет `foo`, генератор `@vue/cli-plugin-foo` получит `{ option: 'bar' }` вторым аргументом. - Для сторонних плагинов настройки будут разрешаются из интерактивных подсказок или аргументов командной строки, когда пользователь вызывает `vue invoke` (см. [интерактивные подсказки](#интерактивные-подсказки)). + Для сторонних плагинов настройки разрешаются из интерактивных подсказок или аргументов командной строки, когда пользователь вызывает `vue invoke` (см. [интерактивные подсказки](#интерактивные-подсказки)). -3. Всё содержимое пресета (`presets.foo`) будет передано в качестве третьего аргумента. +3. Всё содержимое пресета (`presets.foo`) передаётся третьим аргументом. ### Создание новых шаблонов -При вызове команды `api.render('./template')` генератор будет компилировать файлы из каталога `./template` (путь разрешается относительно файла генератора) с помощью [EJS](https://github.com/mde/ejs). +Генератор при вызове команды `api.render('./template')` будет создавать файлы из шаблонов в каталоге `./template` (путь разрешается относительно файла генератора) с помощью [EJS](https://github.com/mde/ejs). -Представим, что разрабатываем плагин [vue-cli-auto-routing](https://github.com/ktsn/vue-cli-plugin-auto-routing) и хотим внести следующие изменения в проект при его вызове: +Представим, что разрабатываем плагин [vue-cli-auto-routing](https://github.com/ktsn/vue-cli-plugin-auto-routing) и хотим внести следующие изменения в проект при вызове генератора: -- создать каталог `layouts` с файлом шаблона по умолчанию; +- создать каталог `layouts` с файлом шаблона страниц по умолчанию; - создать каталог `pages` со страницами `about` и `home`; - добавить файл `router.js` в каталоге `src` -Для создания такой структуры нужно сначала создать её внутри каталога `generator/template`: +Для создания такой структуры нужно сначала повторить её внутри каталога `generator/template`: ![Структура файлов генератора](/generator-template.png) -После создания шаблона необходимо добавить вызов `api.render` в файле `generator/index.js`: +После создания необходимо добавить вызов `api.render` в файле `generator/index.js`: ```js module.exports = api => { @@ -130,7 +130,7 @@ module.exports = api => { ### Изменение существующих шаблонов -Кроме того, можно унаследовать или заменить части существующего файла шаблона (даже из другого пакета) используя YAML front-matter: +Кроме того, можно унаследовать или заменить части существующего шаблона файла (даже из другого пакета) с помощью YAML front-matter: ```ejs --- @@ -140,29 +140,29 @@ replace: !!js/regexp / ``` -Также есть возможность заменять сразу несколько мест, для этого потребуется обернуть заменяющие строки в блоки `<%# REPLACE %>` и `<%# END_REPLACE %>`: +Также есть возможность заменять сразу несколько мест в файле одновременно, для этого потребуется обернуть заменяющие строки в блоки `<%# REPLACE %>` и `<%# END_REPLACE %>`: ```ejs --- extend: '@vue/cli-service/generator/template/src/App.vue' replace: - - !!js/regexp /Welcome to Your Vue\.js App/ + - !!js/regexp /Добро пожаловать в приложение Vue\.js/ - !!js/regexp / <%# END_REPLACE %> @@ -170,7 +170,7 @@ export default { ### Ограничения по именованию файлов -При необходимости создания шаблона файла, имя которого начинается с точки (например, `.env`), необходимо следовать определённому соглашению об именовании, поскольку при публикации плагина в npm такие файлы игнорируются: +При необходимости создания шаблона файла, имя которого начинается с точки (например, `.env`), нужно следовать определённому соглашению об именовании, поскольку при публикации плагина в npm такие файлы игнорируются: ```bash # Шаблон файла должен использовать символ подчёркивания вместо точки: @@ -182,7 +182,7 @@ export default { /generator/template/.env ``` -Следовательно, также потребуется придерживаться определённого соглашения об именовании, если требуется сгенерировать файл, имя которого начинается с подчёркивания: +Следовательно, также потребуется придерживаться определённого соглашения об именовании, если потребуется сгенерировать файл, имя которого начинается с подчёркивания: ```bash # Шаблоны таких файлов должны использовать 2 символа подчёркивания вместо одного: @@ -197,7 +197,7 @@ export default { ### Расширение пакета -Если нужно добавить новую зависимость к проекту, создать npm script или изменить `package.json` любым другим способом, можно использовать метод API `extendPackage`. +Если нужно добавить новую зависимость в проект, создать npm-задачу или изменить `package.json` любым другим способом, можно использовать метод API `extendPackage`. ```js // generator/index.js @@ -241,7 +241,7 @@ module.exports = api => { api.injectImports(api.entryFile, `import router from './router'`) ``` -Теперь, когда маршрутизатор импортирован, можно внедрить его в экземпляр Vue в основном файле. Для этого используем хук `afterInvoke`, который вызывается после записи файлов на диск. +Теперь, когда маршрутизатор импортирован, можно внедрить его в экземпляр Vue в основном файле. Используем для этого хук `afterInvoke`, который вызывается после записи файлов на диск. Сначала нужно прочитать содержимое основного файла с помощью модуля Node `fs` (который предоставляет API для взаимодействия с файловой системой) и разделить содержимое на строки: @@ -274,7 +274,7 @@ module.exports.hooks = (api) => { } ``` -Наконец, нужно сохранить содержимое обратно в основной файл: +Наконец, сохраняем содержимое обратно в основной файл: ```js{12-13} // generator/index.js @@ -296,7 +296,7 @@ module.exports.hooks = (api) => { ## Плагин для сервиса -Плагин для сервиса позволяет вносить изменения в конфигурацию webpack, создавать новые vue-cli команды или изменять существующие (такие как `serve` и `build`). +Плагин для сервиса позволяет вносить изменения в конфигурацию webpack, создавать новые команды vue-cli или изменять существующие (такие как `serve` и `build`). Плагин для сервиса автоматически загружается при создании экземпляра сервиса — т.е. при каждом вызове команды `vue-cli-service` внутри проекта. Он располагается в файле `index.js` в корневом каталоге плагина CLI. @@ -306,7 +306,7 @@ module.exports.hooks = (api) => { - Объект, содержащий локальные настройки проекта, указанные в файле `vue.config.js` или в поле `"vue"` файла `package.json`. -Минимально необходимый код файла плагина сервиса приведён ниже: +Минимально необходимый код файла плагина для сервиса приведён ниже: ```js module.exports = () => {} @@ -333,7 +333,7 @@ module.exports = (api, options) => { } ``` -Также можно использовать метод `configureWebpack` для изменении конфигурации webpack или возврата объекта, который будет объединён с помощью webpack-merge. +Также можно использовать метод `configureWebpack` для изменении конфигурации webpack или возврата объекта, который будет объединяться с конфигурацией с помощью webpack-merge. ### Добавление новой команды в cli-service @@ -354,10 +354,10 @@ api.registerCommand( ) ``` -В этом примере мы задаём имя команды (`'greet'`), объект настроек с опциями `description` и `usage`, а также функцию которая выполняется при запуске команды `vue-cli-service greet`. +В этом примере мы задаём имя команды (`'greet'`), объект настроек с опциями `description` и `usage`, а также функцию, которая выполняется при запуске команды `vue-cli-service greet`. :::tip Совет -Также можно добавить новую команду в список npm-скриптов проекта внутри файла `package.json` [с помощью генератора](#расширение-пакета). +Можно также добавить новую команду в список npm-задач проекта в файле `package.json` [с помощью генератора](#расширение-пакета). ::: При запуске новой команды в проекте с установленным плагином появится сообщение в консоли: @@ -367,7 +367,7 @@ $ vue-cli-service greet 👋 Привет! ``` -Также можно указать список доступных опций для новой команды. Добавим опцию `--name` и изменим функцию для вывода этого имени, если оно было указано. +Можно указать список доступных опций для новой команды. Добавим опцию `--name` и изменим функцию для вывода этого имени, если оно было указано. ```js api.registerCommand( @@ -387,7 +387,7 @@ api.registerCommand( ); ``` -Теперь, если запустить команду `greet` с указанной опцией `--name`, это имя будет выведено в сообщение в консоли: +Теперь при запуске команды `greet` с указанной опцией `--name`, это имя будет выводиться вместе с сообщением в консоли: ```bash $ vue-cli-service greet --name 'Джон' @@ -396,7 +396,7 @@ $ vue-cli-service greet --name 'Джон' ### Изменение существующей команды в cli-service -Если необходимо изменить существующую команду cli-service, можно получить её с помощью `api.service.commands` и внести некоторые изменения. Мы выведем сообщение в консоль с номером порта, на котором запущено приложение: +Если необходимо изменить существующую команду cli-service, сначала нужно получить её через `api.service.commands` и затем внести некоторые изменения. К примеру, выведем сообщение в консоли с номером порта, на котором запущено приложение: ```js const { serve } = api.service.commands @@ -434,11 +434,11 @@ module.exports.defaultModes = { ## Интерактивные подсказки -Интерактивные подсказки предназначены для обработки пользовательского выбора при создании нового проекта или добавлении нового плагина в существующий проект. Вся логика интерактивных подсказок расположена в файле `prompts.js`. Эти подсказки реализованы с помощью пакета [inquirer](https://github.com/SBoudrias/Inquirer.js) под капотом. +Интерактивные подсказки предназначены для обработки пользовательского выбора при создании нового проекта или добавлении нового плагина в существующий проект. Вся логика интерактивных подсказок расположена в файле `prompts.js`. Сами подсказки реализованы с помощью пакета [inquirer](https://github.com/SBoudrias/Inquirer.js) под капотом. -Когда пользователь инициализирует плагин вызовом `vue invoke`, если плагин содержит `prompts.js` в своем корневом каталоге, он будет использован во время вызова. Файл должен экспортировать массив [вопросов](https://github.com/SBoudrias/Inquirer.js#question), которые затем будут обработаны Inquirer.js. +При инициализации плагина пользователем командой `vue invoke`, если плагин содержит `prompts.js` в своем корневом каталоге, он будет использован во время вызова. Файл должен экспортировать массив [вопросов](https://github.com/SBoudrias/Inquirer.js#question), которые затем будут обработаны Inquirer.js. -Необходимо экспортировать массив вопросов или функцию, которая возвращает его. +Необходимо экспортировать сам массив вопросов или функцию, которая возвращает его. Например, экспорт непосредственно массива вопросов: ```js @@ -456,7 +456,7 @@ module.exports = [ ] ``` -Или функция, которая возвращает массив вопросов: +Или экспорт функции, которая возвращает массив вопросов: ```js // prompts.js @@ -485,15 +485,15 @@ module.exports = pkg => { } ``` -Итоговый объект с ответами будет передан в генератор плагина в качестве настроек. +Итоговый объект с ответами будет передаваться в генератор плагина в качестве настроек. -Кроме того, пользователь может пропускать интерактивные подсказки и напрямую инициализировать плагин, передав опции через командную строку, например: +Кроме того, пользователь может пропустить этап в интерактивными подсказками и напрямую инициализировать плагин, передав опции через командную строку, например: ```bash vue invoke my-plugin --mode awesome ``` -Интерактивные подсказки могут быть [различных типов](https://github.com/SBoudrias/Inquirer.js#prompt-types), но наиболее широко в CLI используются `checkbox` и `confirm`. Добавим интерактивную подсказку `confirm` и используем её в генераторе плагина чтобы создавать по условию [новый шаблон файла](#создание-новых-шабnонов). +Интерактивные подсказки могут быть [различных типов](https://github.com/SBoudrias/Inquirer.js#prompt-types), но наиболее широко в CLI применяются `checkbox` и `confirm`. Добавим интерактивную подсказку `confirm` и используем её в генераторе плагина чтобы создавать по условию [новый файл из шаблона](#создание-новых-шабnонов). ```js // prompts.js @@ -508,11 +508,11 @@ module.exports = [ ] ``` -При вызове плагина пользователю будет предложено ответить на вопрос о добавлении примеров маршрутов и ответом по умолчанию будет выбран «Нет». +При вызове плагина пользователю будет предложено ответить на вопрос о добавлении примеров маршрутов с ответом по умолчанию «Нет». ![Пример интерактивных подсказок](/prompts-example.png) -Если необходимо использовать результат выбора пользователя в генераторе, ответ будет доступен по имени интерактивной подсказки. Теперь можно модифицировать `generator/index.js`: +Если необходимо использовать результат выбора пользователя в генераторе, ответ будет доступен по имени интерактивной подсказки. Теперь можно модифицировать `generator/index.js` так: ```js if (options.addExampleRoutes) { @@ -526,20 +526,20 @@ if (options.addExampleRoutes) { ## Локальная установка плагина -При разработке плагина может потребоваться протестировать его и проверить как он работает локально на проекте с помощью Vue CLI. Можно использовать существующий проект или создать новый в целях тестирования: +При разработке плагина может потребоваться протестировать его и проверить локально как он работает на проекте с помощью Vue CLI. Можно использовать существующий проект или создать новый в целях тестирования: ```bash vue create test-app ``` -Для добавления плагина выполните следующую команду в корневом каталоге проекта: +Для добавления плагина выполняем следующую команду в корневом каталоге проекта: ```bash npm install --save-dev file:/full/path/to/your/plugin vue invoke ``` -Это необходимо повторять каждый раз, когда вносите изменения в плагин. +Вызов этих команд необходимо повторять каждый раз при внесении изменений в плагин. Другой способ добавления плагина — воспользоваться возможностями Vue UI. Выполните команду: @@ -555,19 +555,19 @@ vue ui ![Список плагинов в UI](/ui-select-plugin.png) -Нажмите на названии приложения, перейдите на вкладку плагинов (значок пазла) и затем нажмите кнопку `Add new plugin` (Добавить новый плагин) в правом верхнем углу. На новой странице будет отображён список плагинов Vue CLI, доступных через npm. В нижней части страницы будет кнопка `Browse local plugin` (Выбор локального плагина): +Нажмите на название приложения, перейдите на вкладку плагинов (значок пазла) и затем нажмите кнопку `Add new plugin` (Добавить новый плагин) в правом верхнем углу. На новой странице будет отображён список плагинов Vue CLI, доступных через npm. В нижней части страницы будет кнопка `Browse local plugin` (Выбор локального плагина): ![Выбор локальный плагин](/ui-browse-local-plugin.png) -В окне выбора легко найти тестируемый плагин и добавить в проект. После этого его можно будет увидеть в списке плагинов и применять изменения к плагину просто нажав на иконку обновления: +В окне выбора находим тестируемый плагин и добавляем в проект. После этого он станет виден в списке плагинов, а применить изменения к плагину можно просто нажав на иконку обновления: ![Refresh plugin](/ui-plugin-refresh.png) ## Интеграция с UI -Vue CLI имеет отличный UI с помощью которого пользователь сможет разворачивать и управлять проектом в удобном графическом интерфейсе. Плагин Vue CLI может интегрироваться в этот интерфейс. UI предоставляет дополнительные возможности для плагинов CLI: +Vue CLI имеет отличный UI с помощью которого пользователь может разворачивать и управлять проектом в удобном графическом интерфейсе. Плагины Vue CLI могут интегрироваться в этот интерфейс. Также UI предоставляет дополнительные возможности для плагинов CLI: -- можно запускать npm-задачи, в том числе и специфичные для плагинов, напрямую из UI; +- можно напрямую из UI запускать npm-задачи, в том числе и специфичные для плагинов; - можно отображать экран с настройками конфигурации плагина. Например, [vue-cli-plugin-apollo](https://github.com/Akryum/vue-cli-plugin-apollo) предоставляет отдельный экран для конфигурации сервера Apollo: ![Экран конфигурации в UI](/ui-configuration.png) @@ -585,9 +585,9 @@ module.exports = api => { ### Отображение задачи в UI -Плагин Vue CLI позволяет не только добавлять новые npm-задачи в проект [через Generator](#расширение-пакета), но и создавать новые экраны для использования в Vue UI. Это полезно, если хочется запускать задачу прямо из пользовательского интерфейса и видеть результаты её выполнения. +Плагин Vue CLI позволяет не только добавлять новые npm-задачи в проект с помощью [генератора](#расширение-пакета), но и создавать новые экраны для использования в Vue UI. Это полезно, если хочется запускать задачу сразу из пользовательского интерфейса и видеть результаты её выполнения. -Добавим в пользовательский интерфейс задачу `greet`, которую создавали с помощью [генератора](#расширение-пакета). Список задач генерируются из поля `scripts` файла проекта `package.json`. Можно «дополнить» задачу дополнительной информацией и хуками с помощью метода `api.describeTask`: +Добавим отображение задачи `greet`, которую создавали с помощью [генератора](#расширение-пакета). Список задач определяется из поля `scripts` файла проекта `package.json`. Можно «дополнить» задачу дополнительной информацией и хуками с помощью метода `api.describeTask`: ```js module.exports = api => { @@ -599,17 +599,17 @@ module.exports = api => { } ``` -Теперь в обзоре проекта через Vue UI можно увидеть, что задача добавлена в секцию `Tasks`. Можно увидеть её название, предоставленное описание, иконку ссылки, которая ведёт на указанный URL, а также экран для отображения результатов выполнения задачи: +Теперь в обзоре проекта Vue UI можно увидеть, что задача появилась на странице `Tasks`. Можно увидеть её название, предоставленное описание, иконку ссылки, которая ведёт на указанный URL, а также экран для отображения результатов выполнения задачи: ![Задача Greet в UI](/ui-greet-task.png) ### Отображение экрана конфигурации -Иногда проект может иметь пользовательские файлы конфигураций для различных функций или библиотек. С помощью плагина Vue CLI можно отображать эту конфигурацию в Vue UI, изменять её и сохранять (сохранение изменит соответствующий конфигурационный файл в вашем проекте). По умолчанию, проект Vue CLI имеет главный экран конфигурации, отображающий настройки из `vue.config.js`. Если добавить ESLint в проект, то будет виден также экран конфигурации ESLint: +Иногда в проекте могут быть пользовательские файлы конфигураций для различных функций или библиотек. С помощью плагина Vue CLI можно отображать конфигурацию в Vue UI, изменять её и сохранять (сохранение изменит соответствующий конфигурационный файл в проекте). По умолчанию в проекте Vue CLI имеется только главный экран конфигурации с настройками из `vue.config.js`. Если добавить ESLint в проект, то появится также экран конфигурации ESLint: -![UI Configuration Screen](/ui-configuration-default.png) +![Экран конфигурации в UI](/ui-configuration-default.png) -Давайте создадим пользовательский экран конфигурации для плагина. Прежде всего, после добавления плагина в существующий проект, должен быть файл, содержащий эту пользовательскую конфигурацию. Это означает, что требуется добавить этот файл в каталог `template` для [шага создания новых шаблонов](#создание-новых-шабnонов). +Давайте создадим экран конфигурации для плагина. Прежде всего, после добавления плагина в существующий проект, должен быть файл с пользовательской конфигурацией. Это означает, что требуется добавить этот файл в каталог `template` для шага [создания новых шаблонов](#создание-новых-шабnонов). По умолчанию пользовательский интерфейс конфигурации может читать и записывать файлы следующих форматов: `json`, `yaml`, `js`, `package`. Назовём новый файл `myConfig.js` и поместим его в корне каталога `template`: @@ -655,7 +655,7 @@ api.describeConfig({ ``` :::danger Предупреждение -Убедитесь в точности пространства имён для id, так как он должен быть уникальным для всех плагинов. Рекомендуется использовать [обратную нотацию записи доменного имени](https://en.wikipedia.org/wiki/Reverse_domain_name_notation) +Убедитесь в точности пространства имён для id, так как он должен быть уникальным для всех плагинов. Рекомендуем использовать [обратную нотацию записи доменного имени](https://en.wikipedia.org/wiki/Reverse_domain_name_notation) ::: #### Логотип конфигурации @@ -672,11 +672,11 @@ api.describeConfig({ }) ``` -Если значок не указан, будет использоваться логотип плагина если такой есть (см. [Логотип](#логотип)). +Если значок не указан, то будет использоваться логотип плагина, если таковой есть (см. [Логотип](#логотип)). #### Файлы конфигурации -Теперь, если необходимо предоставить файл конфигурации для UI: таким образом можно будет читать его содержимое и сохранять изменения в нём. Для этого необходимо указать имя конфигурационного файла, выбрать его формат и указать путь к нему: +Теперь нужно предоставить файл конфигурации для UI: таким образом можно будет читать его содержимое и сохранять изменения обратно. Для этого указываем имя конфигурационного файла, его формат и указываем путь к нему: ```js api.describeConfig({ @@ -689,11 +689,11 @@ api.describeConfig({ }) ``` -Можно указывать больше одного файла. Например, если есть `myConfig.json`, можно указать его в свойстве `json: ['myConfig.json']`. Порядок важен: первое имя файла в списке будет использовано для создания файла конфигурации, если его не существует. +Можно указать больше одного файла. Например, если есть `myConfig.json`, можно определить его в свойстве `json: ['myConfig.json']`. Порядок здесь важен: первое имя файла в списке будет использоваться при создании файла конфигурации, если его не существует. #### Отображение интерактивных подсказок конфигурации -Отобразим поля ввода для свойства цвета на экране конфигурации. Для этого используем хук `onRead`, который вернёт список интерактивных подсказок для отображения: +Отобразим поле ввода для отображения свойства с цветом на экране конфигурации. Для этого используем хук `onRead`, который вернёт список интерактивных подсказок для отображения: ```js api.describeConfig({ @@ -711,11 +711,11 @@ api.describeConfig({ }) ``` -В примере выше мы добавили интерактивную подсказку в виде поля со значением `white`. Вот как будет выглядеть экран конфигурации со всеми приведёнными выше настройками: +Этот пример добавляет интерактивную подсказку в виде поля с указанным значением `white`. Вот как будет выглядеть экран конфигурации со всеми приведёнными выше настройками: ![Начало конфигурации UI](/ui-config-start.png) -Теперь заменим явно указанное значение `white` на свойство из конфигурационного файла. В хуке `onRead` объект `data` содержит JSON с результатом каждого файла конфигурации. В нашем случае, содержание `myConfig.js` было таким: +Заменим теперь статическое значение `white` на свойство из конфигурационного файла. В хуке `onRead` объект `data` содержит JSON с результатом каждого файла конфигурации. В нашем случае содержание `myConfig.js` такое: ```js // myConfig.js @@ -737,7 +737,7 @@ module.exports = { } ``` -Легко увидеть, что нам необходимо свойство `data.myConfig.color`. Изменим хук `onRead`: +Легко увидеть, что необходимое нам свойство `data.myConfig.color`. Обновим хук `onRead`: ```js // ui.js @@ -755,10 +755,10 @@ onRead: ({ data }) => ({ ``` ::: tip Совет -Обратите внимание, что `myConfig` может быть неопределён, если конфигурационного файла не существует при загрузке экрана. +Обратите внимание, что `myConfig` может быть неопределён, если конфигурационного файла не существует на момент загрузки экрана конфигурации. ::: -Как можно увидеть на экране конфигурации значение `white` заменилось на `black`. +Как можно увидеть на экране конфигурации значение `white` заменится на `black`. Также можно предоставить значение по умолчанию, если конфигурационный файл отсутствует: @@ -793,7 +793,7 @@ api.describeConfig({ }) ``` -Хук `onWrite` принимает множество [аргументов](ui-api.html#сохранение-изменений-конфигурации), но нам необходимо только два из них: `prompts` и `api`. В первом текущие объекты интерактивных подсказок — мы получим id интерактивной подсказки и ответ для этого id. Для получения ответа воспользуемся методом `async getAnswer()` из `api`: +Хук `onWrite` принимает множество [аргументов](ui-api.html#сохранение-изменений-конфигурации), но нам нужны только два из них: `prompts` и `api`. В первом текущие объекты интерактивных подсказок — получим id интерактивной подсказки и ответ для этого id. Для получения ответа воспользуемся методом `async getAnswer()` из `api`: ```js // ui.js @@ -807,7 +807,7 @@ async onWrite({ api, prompts }) { } ``` -Теперь, если изменить значение цвета в поле ввода с `black` на `red` на экране конфигурации и нажать кнопку `Save the changes`, то содержимое файла `myConfig.js` в проекте также изменится: +Теперь, если на экране конфигурации изменить значение цвета в поле ввода с `black` на `red` и нажать кнопку `Save the changes`, то содержимое файла `myConfig.js` также обновится: ```js // myConfig.js @@ -819,9 +819,9 @@ module.exports = { ### Отображение интерактивных подсказок -При желании можно также отображать [интерактивные подсказки](#интерактивные-подсказки) в Vue UI. При установке плагина через UI, интерактивные подсказки будут отображены на шаге вызова плагина. +При желании также можно отображать [интерактивные подсказки](#интерактивные-подсказки) в Vue UI. При установке плагина через UI интерактивные подсказки будут отображаться на шаге вызова плагина. -Объект подсказки можно расширить дополнительными свойствами. Они опциональны и используются только в UI: +Объект подсказки можно расширять дополнительными свойствами. Они опциональны и используются только в UI: ```js // prompts.js @@ -848,7 +848,7 @@ module.exports = [ ### Логотип Можно поместить файл `logo.png` в корне каталога, который будет публиковаться в npm. Тогда его можно будет увидеть в нескольких местах: - - При поиска плагина для установки + - При поиске плагина для установки - В списке установленных плагинов - В списке конфигураций (по умолчанию) - В списке дополненных задач (по умолчанию) @@ -859,16 +859,16 @@ module.exports = [ ## Публикация плагина в npm -Для публикации плагина необходимо быть зарегистрированным на [npmjs.com](npmjs.com) и `npm` должна быть установлена глобально. Если это ваш первый npm-модуль, запустите команду: +Для публикации плагина необходимо быть зарегистрированным на [npmjs.com](npmjs.com) и глобально установить `npm`. Если публикуете ваш первый npm-модуль, то сначала запустите команду: ```bash npm login ``` -Введите имя пользователя и пароль. Это позволит сохранить учётные данные, чтобы не пришлось вводить их при каждой публикации. +Введите имя пользователя и пароль. Это позволит сохранить учётные данные, чтобы не приходилось вводить их при каждой публикации. :::tip Совет -Перед публикацией плагина убедитесь, что выбрали правильно имя для него! Соглашение по именованию `vue-cli-plugin-`. Дополнительную информации см. в разделе [Именование и обнаруживаемость в поиске](#именование-и-обнаруживаемость-в-поиске). +Перед публикацией плагина убедитесь, что выбрали правильное имя для него! Соглашение по именованию `vue-cli-plugin-`. Дополнительную информации см. в разделе [Именование и обнаруживаемость в поиске](#именование-и-обнаруживаемость-в-поиске). ::: Для публикации плагина перейдите в корневой каталог и выполните команду в терминале: