VOYAGE GROUP VR室ブログ

VOYAGE GROUP VR室のブログです。コンテンツの紹介や制作方法、イベントレポートなどについて書きます。原則毎週水曜日更新。

自作A-Frameコンポーネントをnpmモジュールとして公開するための神ってるツール A-Frame component boilerplate

年の瀬ですね。jujunjun110です!

VR元年と呼ばれた今年、みなさんはどのような年を過ごされたでしょうか。

今回は、一年を振り返る意味も込めて今年の流行語を駆使しながら開発したA-Frameのコンポーネントをライブラリとして公開する方法について書いていきたいと思います。

目次

A-Frameにコンポーネントを公開しよう!

A-Frameにおけるコンポーネント

A-Frameは Entity-Component-System というパターンに基づいて作られており、球や立方体など基本的なエンティティに、コンポーネントと呼ばれる「見た目や機能などの振る舞い」を実装した再利用可能なモジュールを付与することでアプリケーションを実装していきます。

もちろん、自作コンポーネントはディベロッパーがライブラリとして公開することができます。

中でも神ってるコンポーネントは、A-Frameの公式ブログのA Week of A-Frameというコーナーや、awesome aframeというページに公開されていきます。 眺めているだけでも楽しいしアイデアが湧いてくるのでおすすめです。

https://media.giphy.com/media/l0HlQ3daLB34XbJtK/giphy.gif

先日A-FrameイベントにLT登壇した際、A-Frame開発者のKevinにコンポーネントをぜひ公開してねと言ってもらったので、npmに公開してみました。↓こちらです!

www.npmjs.com

というわけで、今回はそんな自作コンポーネントの公開方法について書いていきます。

コンポーネントの公開方法

コンポーネントは、基本的にjavascriptのパッケージ管理ツール npm に公開されていきます。

npmはnpm install {package_name} などと打つとパッケージを落としてきてくれるツール。A-Frame開発においては手放すことのできないアモーレですね。詳しい使い方はこちらの記事などをご覧ください。*1

環境を整える

まず、開発をはじめる前に環境を整えていきましょう。建築で言ったら盛り土にあたる部分です。

公開用Githubリポジトリの作成とクローン

まず最初はGithubで公開用のpublicリポジトリを作成して、自分の作業環境にcloneしてきましょう。

git clone {remote_path}

publicリポジトリであれば無料ユーザーでいくらでも作成できるので、マイナス金利になるほど経済が冷え込む昨今でも安心です。

aframe-component-boilerplate のダウンロード

素晴らしいことに、A-Frameのエコシステムでは、コンポーネントを公開するためのとてもよくできた雛形(boilerplate)が用意されています。その名もズバリaframe-component-boilerplate

github.com

このリポジトリ全体をzipでDLし解凍して、中身をさきほど作った自分のgitリポジトリに配置しましょう。*2(このとき、MacのFinderでやろうとすると.gitignore などドットファイルをコピーしそびれやすいので注意!)

f:id:jujunjun110:20161211175501p:plain

npm の初期設定

ファイルが配置できたら、公式のREADMEに沿って、プロジェクトに対するnpmの初期設定をしていきます。

npm init

ここでライブラリのライセンスが入力できるので慎重かつ大胆に決めましょう。今回はMITライセンスにしてみました。

npm install

package.jsondevDependenciesに記述されているモジュールが全てインストールされます。

npm run unboil

対話形式でコンポーネントの重要な情報を入力します。こんな感じで必要情報を入力すると...

f:id:jujunjun110:20161211181214p:plain

こんな感じで、各ファイルの必要情報をいい感じに書き換えてくれます!ポケモンGOでポッポを捕まえるくらい簡単ですね!

f:id:jujunjun110:20161209180319p:plain

ここまで完了したところで、プロジェクトの初期状態はこんな感じになっているはずです。

f:id:jujunjun110:20161212184016p:plain

以下で詳細に説明していきますが、これらのファイル・ディレクトリは、おおよそ以下の役割を持ちます。

  • dist/ 以下
    ライブラリ公開後実際に利用される、ブラウザで実行可能なjsファイルが配置されます。

  • example/ 以下
    ライブラリ公開後、git clonenpm run build などで、ライブラリのデモを自分の環境で試してみる際のデモページの一式が配置されます。

  • index.js
    ファイルに配布するモジュールの実装そのものを記述するファイルです。このファイル内では、node.js の記法(require()など)が使えます。

  • node_modules/ 以下
    外部nodeモジュールが配置されます。

  • package.json
    npmの設定を記述するファイルです。

ざっくり言うと、自分でコードを書くのはindex.jsだけでOKなようになっており、用意されている便利コマンドを使うことで、配布用やデモ用のファイル群を自動でビルドすることができます。

コンポーネントの実装とデモページの作成

さて、ここまで準備ができたら、コンポーネント自体を実装していきましょう。

index.js の実装

index.js の初期状態は以下のようになっています。

A-Frameのコンポーネントが持つ、各プロパティとイベントのひな形が書かれています。

f:id:jujunjun110:20161209180335p:plain

各イベントに対しての実装は、必ずしもされていなくても問題ないので、必要なイベント部分だけ実装していきましょう。

デモ用のjsをビルドする

実装がうまくできたら、以下を実行します。

npm run build

するとexample/ ディレクトリ下に build.js というファイルが新たにできます。

なぜこうなるのか軽く説明していきます。まず、package.json の中に、以下のような記載があります。

"scripts":{
"build": "browserify examples/main.js -o examples/build.js",
(略)
}

これによって、このプロジェクト内では、npm run buildbrowserify examples/main.js -o examples/build.js のエイリアスになっています。

browserify はnode記法で書かれたjsを、ブラウザで実行できるjsに変換するnodeモジュール。main.jsはデフォルトでは以下のようになっているので、

require('aframe');
require('../index.js');

aframeコンポーネントと、index.js の内容を順番に解釈した上で、両方の内容を1ファイルで完結するコードをbuild.js として書き出してくれたというわけですね。

ここまでを図にまとめると以下のようになります。

f:id:jujunjun110:20161212184038p:plain

ここから分かるように、examplesに含めたいデモに他のnpmモジュールも利用したい場合は、

npm install --save-dev {package_name}

などでpackage.jsondevDependencies 項目にそのモジュールを登録した上で、main.js内でそのモジュールをrequire すればいいというわけです!

実装した内容の確認

ビルドができたら、以下のコマンドを打ってみましょう。

npm run dev

ブラウザが立ち上がり、examples/index.html が表示されるはずです。

f:id:jujunjun110:20161211192238p:plain

そこからBasicをクリックして、自分のモジュールが正しく動いているか確認しましょう。

examples/basic/index.htmlは自動的にexamples/build.jsを読みこむようになっているので、そのコンポーネントの機能がわかりやすいようなデモを実装しましょう。リソースファイルの置き方などは、すでに公開されているコンポーネント群を聖地巡礼して参考にすると良いと思います。

f:id:jujunjun110:20161102103229p:plain

ちなみに、このコマンドはpackage.jsonbudo examples/main.js:build.js --dir examples --port 8000 --live --open" にエイリアスが張られています。

budo は、nodeで簡単にウェブサーバーが立てられるnpmモジュール。今回は8000番ポートでexamples/ を表示しています。--liveオプションがついているので、budoのLiveReload機能により、javascriptファイルが更新されるとブラウザ側でも自動的に更新が行われます。これは本当に便利。

README.md の記述

ここまでで、自分のライブラリが正しく動いていることが確認できたら、README.mdを記述していきましょう。

f:id:jujunjun110:20161211203151p:plain

こちらも、aframe-component-boilerplateREADME.md に雛形が用意されているので参考にしながら以下の項目を記述しましょう。

  • Summary
    • コンポーネントの概要
    • gifアニメーションを用意して、初めて見た人がすぐ理解できるようにするのがおすすめです
  • API
    • コンポーネントに入力することができる変数
  • Usage
    • コンポーネントの使い方
  • Installation
    • ブラウザ経由の場合
    • npm経由の場合

npmモジュールとしての公開

ここまで来たらあとは公開するのみ!

公開用モジュールのビルド

公開用にnpm run distを実行しましょう。すると、以下のように、dist以下に、ブラウザで直接実行可能なjsファイルがビルドされます。

f:id:jujunjun110:20161212184051p:plain

裏ではpackage.jsonで定義された"webpack index.js dist/aframe-crawling-cursor.js && webpack -p index.js dist/aframe-crawling-cursor.min.js"が実行されています。*3

npmへのサインアップ

npmにモジュールをアップロードするために、まずnpm公式サイトからユーザーを作成します。

f:id:jujunjun110:20161211194101p:plain

登録完了したら

npm adduser {username}

で現在のプロジェクトに自分のnpmユーザーアカウントを紐付けます。

公開ッ!!

ここまで完了したら、重大なバグがないことを強く念じながら、以下のコマンドを打ちます。

npm publish

f:id:jujunjun110:20161211195244p:plain

やったーーーーーーー!!!\(^o^)/

Github Pageの公開

URLひとつで他の人にコンテンツをシェアできるのがWebVRの魅力。なんとaframe-component-boilerplateには、サンプルページを1コマンドでgithub.io に公開出来る機能も備わっています。

以下のコマンドを打ってみましょう。

npm run ghpages

すると、自動的にリポジトリに gh-pagesブランチが作成され、

f:id:jujunjun110:20161212170705p:plain

https://{github_username}.github.io/{repository_name}

という形式のURLでページにアクセスできるようになります!これまた便利すぎる。

公開後の確認

さて、npmに公開が完了したら、正しく動くか確認しましょう。試す必要があるのは、以下の2パターンです。

1.npm install でdist/ 以下のパッケージだけを利用するパターン

2.リポジトリ全体をビルドしてサンプルを実行してみるパターン

npm install でdist/以下のパッケージだけを利用するパターン

通常利用されるのはこっちのパターンですね。

適当に空のディレクトリでnpm initしたのち、おもむろに以下のコマンドで自分のモジュールがインストールできるか試します。

npm install {package_name}

わーいインストール成功!普段使ってるnpmコマンドで自作のライブラリを落としてこれるのは結構感動ものです。

f:id:jujunjun110:20161211200659p:plain

aframe本体などと一緒に読み込んで、ブラウザで問題なく動くか確認しましょう。

ちなみに、npm install時に、package.jsondependencies に書かれているモジュールは読み込まれ、devDependenciesに書かれているモジュールは読み込まれません。実行に不要なモジュールをdependencies書かないように注意しましょう。

リポジトリ全体をビルドしてサンプルを使ってみるパターン

A-Frameでコンポーネントを探す際には、実際にサンプルシーンを手元でビルドしてみて、パフォーマンスや挙動を確かめることが多々あります。

このパターンは、以下の流れで試すことができます。

npm install {package_name}
cd ./node_modules/{package_name}
npm run install
npm run build
npm run dev

A-Frame 開発コミュニティへの連絡

f:id:jujunjun110:20161215120212p:plain

TwitterもしくはA-FrameのSlack で開発者に直接知らせましょう!良いモジュールであれば取り上げてもらえるかもしれません!


以上、npmとaframe-component-boilerplateについて一通り説明してみました。

あまりに至れり尽くせりで、他のツールにゲス不倫する気も起きないくらい素晴らしいですね。ぜひみなさんも自作コンポーネントを公開し、A-Frameコミュニティをトランプ現象以上に盛り上げていきましょう!

自作コンポーネントを登録すれば、あなたも完璧にA-Frameコンポーネント開発者の一員、すなわちPPAPPerfectly Part of A-Frame-component Publisher)です!


ん?PPAP????


♪PPAP〜

f:id:jujunjun110:20161214204330j:plain


♪PPAP〜

f:id:jujunjun110:20161214204330j:plain


♪ペンパイナッポーアッポーペン!!!

f:id:jujunjun110:20161214205216g:plain



来年もよろしくお願いします!!!!

*1:なお筆者はjavascriptの開発環境の複雑さについては全く明るくないので、用語の使い方など不適切なところがあればTwitterなどでご指摘ください。

*2:afarme-component-boilerplateの方をcloneしてきてから向き先のgitリポジトリを変更する方法でも問題ないと思います

*3:webpackもBrowserifyと同様、node記法で書かれたjsをブラウザで実行可能にするnodeモジュールです。