Vue CLI 3 向けに vue-cli-plugin-p11n という Vue CLI プラグインを npm に初期パブリックバージョンをリリースしました。

このプラグインは、Vue CLI 3 で作成された Vue アプリケーション開発環境を Vue I18n や Vuetify のような Vue プラグイン、Vue コンポーネント、そして Vue.js をベースにした UI フレームワークなど、そういったライブラリ開発者に最適な開発環境にセットアップしてくれます。

そもそもプラグイン名にある p11n とは？

p11n === pluginization

pluginization の数略語(ヌメロニウム: numeronym)で作った単語です。pluginization だと長いので。

pluginization は、アプリケーション開発環境を、 プラグイン向け開発環境に化けさせるということで、プラグインの英語「plugin」と「〜化」の英語表現である「〜 zation」を組み合わせて作った単語です。

なぜ作ったの？

vue-cli-plugin-p11n を作った背景というか、モチベーションとしては、以下の 3 点から来ています。

1. webpack 以外でバンドリングできない

Vue CLI 3 でセットアップされた開発環境は、デフォルトのバンドラとして webpack のみです。

JavaScript 界隈で存在するバンドラの中で、バンドリングサイズとして優秀な rollup を選択することができません。

Vue プラグイン、Vue コンポーネントライブラリのような開発者側としては、配布する JavaScript コードサイズは小さくしたいので、rollup が使えるかは重要です。

2. vue init による開発環境構築は今後できなくなる

Vue CLI 3でセットアップされた Vue アプリケーション開発環境は、Vue.js ライブラリ開発環境のユースケースと一致しないため、ほとんどの Vue.js ライブラリ開発者は開発環境を設定するための何らかの方法を持っています。

vue init はそのうちの1つです。

Vue CLI 3 以前のバージョンでは、Vue.js 公式に公開されたいくつかのテンプレート（いわゆるボイラープレート）を使用して開発環境をセットアップできます。

vue init は公式でサポートするテンプレートの他に、独自に用意したテンプレートで、開発環境をセットアップすることができます。

Vue プラグイン、Vue コンポーネントライブラリのような開発者の中には、それぞれ独自に用意したテンプレートで開発環境を構築している人もいます。

自分や Vue コアチームメンバの posva 氏はこんな感じのテンプレートを用意しています。

Vue CLI 3 は vue init をサポートしていますが、レガシーです。

次のメジャーバージョンアップでサポートされなくなる予定なので、vue init で開発環境構築に依存していた人は、難民になってしまいます。

3. Feature request が来た！

これまでの説明した感じなところに、Vue CLI の GitHub Issues に以下の issue が登録されました。

この issue は、Vue I18n も Vue 3 サポートするために、TypeScript の開発環境を整備するのも兼ねて、Vue CLI 3 向けにプラグインを作ろうか思っていたところの矢先でした。

この issue の投下がきっかけで、そろそろ作るか！という気分になり、決意しました。

the standard build toolchain for Vue applications.

ただ、Evan 氏が言っているように、この issue に対しては、Vue CLI 自体でサポートされるべきではないと思っています。

こうした背景から、Feature Request の PoC も想定して、Vue CLI プラグイン作成を始めたという次第です。

どうやって開発環境をセットアップするんですか？

とても簡単です！vue-cli-plugin-p11n をインストールするだけです。

実際に手を動かして、体感してみましょう！
(あ、Vue CLI 3 をインストールしていない方は、 npm i -g @vue/cli でインストールもお忘れなく！)

以下の手順のように、Vue CLI のコマンドを実行するだけで、これだけでVue プラグイン開発環境の構築は完了します。

# Vue プラグインプロジェクトを作成
$ vue create vue-your-plugin

# 対象プロジェクトへ移動
$ cd vue-your-plugin

# `vue add` で vue-cli-plugin-p11n をインストール
$ vue add p11n

もし、ターミナルが苦手なら、vue ui を一時実行して、GUI ベースでも Vue プラグインの開発環境をセットアップすることができます。

どんな開発環境が整備、用意されるの？

vue-cli-plugin-p11n をインストールすると、以下の開発環境が整備、用意されます。

1. プログラミング言語対応した Vue プラグイン開発コードのセットアップ

vue-cli-plugin-p11n は、Vue CLI 3 で選択したプログラミング言語に応じて Vue プラグインの開発するために必要な初期コードを scaffolding します。

JavaScript (Babel) なら JavaScript、 TypeScript なら TypeScript 、それぞれの初期コードを scaffolding します。

以下は TypeScript 環境において scaffolding されたプロジェクト構造です。

上記は、VSCode の explorer のものですが、色によるハイライトからどうscaffolding されたか分かります。実際、どのように scaffolding されてプロジェクトに対してコードが追加、また変更されたかどうかは、git diff で確認することができます。

Vue CLI 3 で単体テスト環境もセットアップされている場合は、Vue プラグインの単体テストの初期コードも以下のように scaffolding されます。

2. rollup によるプロダクションコードのビルド

Vue CLI 3 で構築された開発プロジェクトには、アプリケーションをプロダクション環境向けにビルドするために、CLI Service のコマンドとして build コマンドがセットアップされています。

vue-cli-plugin-p11n は、この CLI Service のコマンドを上書きして rollup でプロダクション向けにビルドするようにしています。

以下は、上書きした CLI Service の build コマンドを実行したときの出力の様子です。

$ yarn build
yarn run v1.13.0
$ vue-cli-service build
⚠️  license is undefined in package.json
⚠️  author is undefined in package.json
Building for production mode as plugin ...
📦  dist/vue-your-plugin.common.js 0.55kb
📦  dist/vue-your-plugin.esm.js 0.53kb
📦  dist/vue-your-plugin.umd.min.js 0.44kb (gzipped: 0.28kb)
📦  dist/vue-your-plugin.umd.js 0.85kb
✅  Build complete. The dist directory is ready to be deployed.
✨  Done in 5.66s.

出力結果から、警告メッセージも出力されていますが、これは package.json に Vue プラグインを公開する際に必要な情報がないものを出力するようにしています。

また、dist ディレクトリに配布対象となるファイルが生成されるほか、バンドルサイズも確認できるようになっています。

ビルドされたファイルは、以下のモジュールをサポートしたものが生成されます。

・ES Modules:
ES Modules に対応したモジュール。rollup または webpack v2 以降のようなバンドラで利用可能

・UMD:
Universal Module Definition に対応したモジュール。<script>タグで利用可能。開発利用向け。

・UMD minify:
読込高速化のため、UMD に対応したモジュールを圧縮したもの。上記に同じく、<script>タグで利用可能。プロダクション利用向け。

・CommonJS:
CommonJS スタイルのモジュール。browserify または webpack v1 のようなレガシーなバンドラで利用可能

3. Vue プラグインを配信するための調整

作成する Vue プラグインは、Vue.js コミュニティのユーザーに使ってもらうために、npm や CDN で配信する必要があります。

このため vue-cli-plugin-p11n は、package.json や .gitignore といったファイルに必要なものを追加・変更します。

以下は、調整された package.json を git diff したものです。

$ git diff ./package.json
diff --git a/package.json b/package.json
index 50f2e23..286910e 100644
--- a/package.json
+++ b/package.json
@@ -1,18 +1,17 @@
 {
   "name": "vue-your-plugin",
   "version": "0.1.0",
-  "private": true,
   "scripts": {
     "serve": "vue-cli-service serve",
     "build": "vue-cli-service build",
     "lint": "vue-cli-service lint",
+    "demo": "vue-cli-service demo",
+    "docs": "npm run docs:serve",
+    "docs:build": "vue-cli-service docs --mode build",
+    "docs:serve": "vue-cli-service docs --mode serve",
     "test:unit": "vue-cli-service test:unit"
   },
-  "dependencies": {
-    "vue": "^2.5.22",
-    "vue-class-component": "^6.0.0",
-    "vue-property-decorator": "^7.0.0"
-  },
+  "dependencies": {},
   "devDependencies": {
     "@types/jest": "^23.1.4",
     "@vue/cli-plugin-babel": "^3.4.0",
@@ -29,6 +28,24 @@
     "eslint-plugin-vue": "^5.0.0",
     "ts-jest": "^23.0.0",
     "typescript": "~3.2.2",
-    "vue-template-compiler": "^2.5.21"
-  }
-}
+    "vue-cli-plugin-p11n": "^0.1.2",
+    "vue-template-compiler": "^2.5.21",
+    "vue": "^2.5.22",
+    "vue-class-component": "^6.0.0",
+    "vue-property-decorator": "^7.0.0"
+  },
+  "files": [
+    "dist/vue-your-plugin.common.js",
+    "dist/vue-your-plugin.umd.min.js",
+    "dist/vue-your-plugin.umd.js",
+    "dist/vue-your-plugin.esm.js",
+    "src",
+    "types/index.d.ts"
+  ],
+  "jsdelivr": "dist/vue-your-plugin.umd.min.js",
+  "main": "dist/vue-your-plugin.common.js",
+  "module": "dist/vue-your-plugin.esm.js",
+  "sideeffects": false,
+  "types": "types/index.d.ts",
+  "unpkg": "dist/vue-your-plugin.umd.min.js"
+}
\ No newline at end of file

package.json に調整された内容のすべての詳細については、このブログでは割愛しますが、CLI Service の build コマンドによって dist ディレクトリに生成されたファイルが、以下のように、 npm 、CDN などといった配布対象環境に応じた設定しています。

・main:
CommonJS をサポートする Node.js や、browserify や webpack v1 のようなバンドラ向けのモジュールを指定

・module:
ES Modules をサポートする rollup や webpack v2 以降のようなバンドラ向けのモジュールを指定

・jsdelivr:
CDN jsdelivr での配信する圧縮された UMD モジュールを指定

・unpkg:
CDN unpkg での配信する圧縮された UMD モジュールを指定

4. serve コマンドによる Vue プラグイン開発環境の提供

Vue CLI 3 で構築された開発プロジェクトには、 src/App.vue に Vue アプリケーションのエントリポイントとなるコンポーネントが作成されます。

その src/App.vue は実際のエントリポイントとなる src/main.(js|ts) で、new Vue(…) で render 関数で描画されることによって、実際にアプリケーションが動作します。

このとき、アプリケーションの開発においては、 CLI Service の serve コマンドを実行することで、webpack の hot-reload によってアプリケーションを動かしつつ、開発をすることができます。

Vue プラグインの開発においても、特にコンポーネントを提供するような Vue プラグインの場合、serve コマンドで開発することが効率的なことがあります。

このため、vue-cli-plugin-p11n は既にセットアップされた CLI Service の serve コマンドによる開発をサポートしています。

以下のように、CLI でコマンドを実行することで、webpack-dev-server が立ち上がり、Vue プラグインが動作するのをブラウザで確認できるはずです。

# CLI Service の serve コマンドで実行
$ npx vue-cli-service serve

#
# package.json の scripts に serve として登録しているので以下でも実行できる
#

# npm 
$ npm run serve

# yarn
$ yarn serve

5. Vue プラグインのデモ環境を提供

ときどき、Vue ライブラリ開発者は、開発した Vue プラグインでデモをしたいことがあります。

vue-cli-plugin-p11n は、デモの実行をサポートするための環境を提供します。

提供する内容としては、以下になります。

・SFC によるデモ実行環境 demo ディレクトリ
・CLI Service の拡張コマンド、 demo コマンドの提供

vue-cli-plugin-p11n をインストールすると、プロジェクト直下に、以下のように、demo ディレクトリが作成されます。

この demo ディレクトリにデモしたい内容を、SFC で実装してファイルを格納します。そうすることで、CLI Servie の demo コマンドで実装したデモとして実行することができます。

以下のように、コマンドを実行してみましょう！

# vue-cli-plugin-p11n のインストールで生成されたサンプルデモの実行
npx vue-cli-service demo Demo.vue

#
# package.json の scripts に demo として登録しているので以下でも実行できる
#

# npm
npm run demo Demo.vue

# yarn
yarn demo Demo.vue

デモを実行すると、以下のような画面がブラウザに表示されるはずです。

なお、CLI Service の demo コマンドで指定する SFC のデモファイルは、 demo ディレクトリを基点に指定する必要があります。

6. VuePress によるドキュメンテーション環境をセットアップ

Vue ライブラリ開発者は、Vue.js コミュニティのユーザーに提供する Vue プラグインを正しく使ってもらうために、ドキュメンテーションも提供する必要があります。

vue-cli-plugin-p11n は、ドキュメンテーション環境もセットアップします。
提供されるドキュメンテーション環境のセットアップとしては、以下になります。

・VuePress によるドキュメンテーション環境
・CLI Service の拡張コマンド、 docs コマンドの提供

vue-cli-plugin-p11n をインストールすると、プロジェクト直下に、以下のように、docs ディレクトリが作成されます。

この docs ディレクトリに VuePress の流儀に従って markdown でドキュメントを格納していきます。

また、VuePress の設定である docs/.vuepress/config.js を設定することで、必要に応じて柔軟にカスタマイズできます。

ドキュメントの表示確認、そして markdown をビルドして Web サーバにホスティングしたい場合は、VuePress の CLI をラップした、CLI Servie の docs コマンドで対応できます。

ドキュメントの表示確認してみましょう！以下のように、docs コマンドの serve モード実行します。

# CLI Service の docs コマンドで実行 (serve モード)
npx vue-cli-service docs --mode serve

#
# package.json の scripts に docs:serve として登録しているので以下でも実行できる
#

# npm
npm run docs:serve

# yarn
yarn docs:serve

#
# scripts には docs:serve のエイリアスである docs でも実行できる
#

# npm
npm run docs

# yarn
yarn docs

コマンド実行すると、VuePress dev server が起動します。ブラウザでターミナルに表示された VuePress dev server のリスニング先の URL にアクセスしてみましょう！

この時点では、ドキュメントは初期状態ですので、以下のような、初期のサンプルドキュメンテーション画面をブラウザで確認できるはずです。

docs コマンド serve モードは表示内容を確認しながら、ドキュメントを編集することができるので大変便利です。

次に、docs コマンドの build モードを実行して、markdown のドキュメントをビルドしてみましょう！

# CLI Service の docs コマンドで実行 (build モード)
npx vue-cli-service docs --mode build

#
# package.json の scripts に docs:build として登録しているので以下でも実行できる
#

# npm
npm run docs:build

# yarn
yarn docs:build

自分の環境では、以下のようにターミナルに出力されました。

$ yarn docs:build
yarn run v1.13.0
$ vue-cli-service docs --mode build
wait Extracting site metadata...
wait Extracting site metadata...
tip Apply theme @vuepress/theme-default
tip Apply plugin @vuepress/register-components (i.e. "@vuepress/plugin-register-components") ...
tip Apply plugin @vuepress/active-header-links (i.e. "@vuepress/plugin-active-header-links") ...
tip Apply plugin @vuepress/search (i.e. "@vuepress/plugin-search") ...
tip Apply plugin @vuepress/nprogress (i.e. "@vuepress/plugin-nprogress") ...
tip Apply plugin vuepress-plugin- ...
[19:22:17] Compiling Client
[19:22:17] Compiling Server
[19:22:23] Compiled Server in 7s
[19:22:27] Compiled Client in 10s
wait Rendering static HTML...
success Generated static files in docs/.vuepress/dist.
✨  Done in 15.99s.

上記の出力結果から、ドキュメントをビルドすると、デフォルトではdocs/.vuepress/dist ディレクトリに Web サーバでホスティング可能な静的ファイル郡が生成されるようになっています。

このディレクトリまるごと、ホスティングすることでブラウザ上で Vue プラグインのドキュメントを確認できるようになります。

まとめ

このブログ記事では、Vue CLI プラグインのvue-cli-plugin-p11n について紹介しました。

このプラグインをインストールすることで、Vue CLI 3 で構築した開発環境を Vue プラグイン向けの開発環境を整備することができます。

Vue CLI の GitHub Issues に投下されたこの issue を受けて、作成した Vue CLI プラグインなため、PoC でかつ MVP な必要最小限の機能を提供する Vue CLI プラグインです。

ぜひ、使ってみてこちらの GitHub issues にフィードバックくれると、大変うれしいです！💬

Next Step

今回作成した Vue CLI プラグインは、自分も使うため今後も拡張していく予定です。💪

次のステップは、こちらの GitHub projects にプロジェクトの TODO としてタスク化しています。✅

今後、これらのタスクを対応していく予定です。