年の瀬ですね。jujunjun110です!
VR元年と呼ばれた今年、みなさんはどのような年を過ごされたでしょうか。
今回は、一年を振り返る意味も込めて今年の流行語を駆使しながら、開発したA-Frameのコンポーネントをライブラリとして公開する方法について書いていきたいと思います。
目次
- 目次
- A-Frameにコンポーネントを公開しよう!
- 環境を整える
- コンポーネントの実装とデモページの作成
- README.md の記述
- npmモジュールとしての公開
- 公開後の確認
- A-Frame 開発コミュニティへの連絡
A-Frameにコンポーネントを公開しよう!
A-Frameにおけるコンポーネント
A-Frameは Entity-Component-System というパターンに基づいて作られており、球や立方体など基本的なエンティティに、コンポーネントと呼ばれる「見た目や機能などの振る舞い」を実装した再利用可能なモジュールを付与することでアプリケーションを実装していきます。
もちろん、自作コンポーネントはディベロッパーがライブラリとして公開することができます。
中でも神ってるコンポーネントは、A-Frameの公式ブログのA Week of A-Frameというコーナーや、awesome aframeというページに公開されていきます。 眺めているだけでも楽しいしアイデアが湧いてくるのでおすすめです。
先日A-FrameイベントにLT登壇した際、A-Frame開発者のKevinにコンポーネントをぜひ公開してねと言ってもらったので、npmに公開してみました。↓こちらです!
というわけで、今回はそんな自作コンポーネントの公開方法について書いていきます。
コンポーネントの公開方法
コンポーネントは、基本的に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。
このリポジトリ全体をzipでDLし解凍して、中身をさきほど作った自分のgitリポジトリに配置しましょう。*2(このとき、MacのFinderでやろうとすると.gitignore などドットファイルをコピーしそびれやすいので注意!)
npm の初期設定
ファイルが配置できたら、公式のREADMEに沿って、プロジェクトに対するnpmの初期設定をしていきます。
npm init
ここでライブラリのライセンスが入力できるので慎重かつ大胆に決めましょう。今回はMITライセンスにしてみました。
npm install
package.json
のdevDependencies
に記述されているモジュールが全てインストールされます。
npm run unboil
対話形式でコンポーネントの重要な情報を入力します。こんな感じで必要情報を入力すると...
こんな感じで、各ファイルの必要情報をいい感じに書き換えてくれます!ポケモンGOでポッポを捕まえるくらい簡単ですね!
ここまで完了したところで、プロジェクトの初期状態はこんな感じになっているはずです。
以下で詳細に説明していきますが、これらのファイル・ディレクトリは、おおよそ以下の役割を持ちます。
dist/ 以下
ライブラリ公開後実際に利用される、ブラウザで実行可能なjsファイルが配置されます。example/ 以下
ライブラリ公開後、git clone
→npm run build
などで、ライブラリのデモを自分の環境で試してみる際のデモページの一式が配置されます。index.js
ファイルに配布するモジュールの実装そのものを記述するファイルです。このファイル内では、node.js の記法(require()
など)が使えます。node_modules/ 以下
外部nodeモジュールが配置されます。package.json
npmの設定を記述するファイルです。
ざっくり言うと、自分でコードを書くのはindex.jsだけでOKなようになっており、用意されている便利コマンドを使うことで、配布用やデモ用のファイル群を自動でビルドすることができます。
コンポーネントの実装とデモページの作成
さて、ここまで準備ができたら、コンポーネント自体を実装していきましょう。
index.js の実装
index.js の初期状態は以下のようになっています。
A-Frameのコンポーネントが持つ、各プロパティとイベントのひな形が書かれています。
各イベントに対しての実装は、必ずしもされていなくても問題ないので、必要なイベント部分だけ実装していきましょう。
デモ用のjsをビルドする
実装がうまくできたら、以下を実行します。
npm run build
するとexample/
ディレクトリ下に build.js
というファイルが新たにできます。
なぜこうなるのか軽く説明していきます。まず、package.json
の中に、以下のような記載があります。
"scripts":{ "build": "browserify examples/main.js -o examples/build.js", (略) }
これによって、このプロジェクト内では、npm run build
が browserify 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
として書き出してくれたというわけですね。
ここまでを図にまとめると以下のようになります。
ここから分かるように、examplesに含めたいデモに他のnpmモジュールも利用したい場合は、
npm install --save-dev {package_name}
などでpackage.json
の devDependencies
項目にそのモジュールを登録した上で、main.js
内でそのモジュールをrequire すればいいというわけです!
実装した内容の確認
ビルドができたら、以下のコマンドを打ってみましょう。
npm run dev
ブラウザが立ち上がり、examples/index.html
が表示されるはずです。
そこからBasic
をクリックして、自分のモジュールが正しく動いているか確認しましょう。
examples/basic/index.html
は自動的にexamples/build.js
を読みこむようになっているので、そのコンポーネントの機能がわかりやすいようなデモを実装しましょう。リソースファイルの置き方などは、すでに公開されているコンポーネント群を聖地巡礼して参考にすると良いと思います。
ちなみに、このコマンドはpackage.json
で budo examples/main.js:build.js --dir examples --port 8000 --live --open"
にエイリアスが張られています。
budo は、nodeで簡単にウェブサーバーが立てられるnpmモジュール。今回は8000番ポートでexamples/ を表示しています。--live
オプションがついているので、budoのLiveReload機能により、javascriptファイルが更新されるとブラウザ側でも自動的に更新が行われます。これは本当に便利。
README.md の記述
ここまでで、自分のライブラリが正しく動いていることが確認できたら、README.mdを記述していきましょう。
こちらも、aframe-component-boilerplateのREADME.md
に雛形が用意されているので参考にしながら以下の項目を記述しましょう。
- Summary
- コンポーネントの概要
- gifアニメーションを用意して、初めて見た人がすぐ理解できるようにするのがおすすめです
- API
- コンポーネントに入力することができる変数
- Usage
- コンポーネントの使い方
- Installation
- ブラウザ経由の場合
- npm経由の場合
npmモジュールとしての公開
ここまで来たらあとは公開するのみ!
公開用モジュールのビルド
公開用にnpm run dist
を実行しましょう。すると、以下のように、dist以下に、ブラウザで直接実行可能なjsファイルがビルドされます。
裏ではpackage.json
で定義された"webpack index.js dist/aframe-crawling-cursor.js && webpack -p index.js dist/aframe-crawling-cursor.min.js"
が実行されています。*3
npmへのサインアップ
npmにモジュールをアップロードするために、まずnpm公式サイトからユーザーを作成します。
登録完了したら
npm adduser {username}
で現在のプロジェクトに自分のnpmユーザーアカウントを紐付けます。
公開ッ!!
ここまで完了したら、重大なバグがないことを強く念じながら、以下のコマンドを打ちます。
npm publish
やったーーーーーーー!!!\(^o^)/
Github Pageの公開
URLひとつで他の人にコンテンツをシェアできるのがWebVRの魅力。なんとaframe-component-boilerplateには、サンプルページを1コマンドでgithub.io に公開出来る機能も備わっています。
以下のコマンドを打ってみましょう。
npm run ghpages
すると、自動的にリポジトリに gh-pages
ブランチが作成され、
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コマンドで自作のライブラリを落としてこれるのは結構感動ものです。
aframe本体などと一緒に読み込んで、ブラウザで問題なく動くか確認しましょう。
ちなみに、npm install
時に、package.json
の dependencies
に書かれているモジュールは読み込まれ、devDependencies
に書かれているモジュールは読み込まれません。実行に不要なモジュールをdependencies
書かないように注意しましょう。
リポジトリ全体をビルドしてサンプルを使ってみるパターン
A-Frameでコンポーネントを探す際には、実際にサンプルシーンを手元でビルドしてみて、パフォーマンスや挙動を確かめることが多々あります。
このパターンは、以下の流れで試すことができます。
npm install {package_name} cd ./node_modules/{package_name} npm run install npm run build npm run dev
A-Frame 開発コミュニティへの連絡
TwitterもしくはA-FrameのSlack で開発者に直接知らせましょう!良いモジュールであれば取り上げてもらえるかもしれません!
以上、npmとaframe-component-boilerplate
について一通り説明してみました。
あまりに至れり尽くせりで、他のツールにゲス不倫する気も起きないくらい素晴らしいですね。ぜひみなさんも自作コンポーネントを公開し、A-Frameコミュニティをトランプ現象以上に盛り上げていきましょう!
自作コンポーネントを登録すれば、あなたも完璧にA-Frameコンポーネント開発者の一員、すなわちPPAP(Perfectly Part of A-Frame-component Publisher)です!
ん?PPAP????
♪PPAP〜
♪PPAP〜
♪ペンパイナッポーアッポーペン!!!
来年もよろしくお願いします!!!!
*1:なお筆者はjavascriptの開発環境の複雑さについては全く明るくないので、用語の使い方など不適切なところがあればTwitterなどでご指摘ください。
*2:afarme-component-boilerplateの方をcloneしてきてから向き先のgitリポジトリを変更する方法でも問題ないと思います
*3:webpackもBrowserifyと同様、node記法で書かれたjsをブラウザで実行可能にするnodeモジュールです。