npm 開発で脱 Babel してみる

2017年1月25日 0 開発 , , ,

自作 npm の開発で脱 Babel したときの対応と問題点まとめ。

  • 2017/1/31 訂正
    power-assert の作者、t_wada さんより power-assert は babel-register を通すなどしないと assert 置換が働かず素の assert になってしまうという指摘があったのでユニットテスト関連の記述を訂正

脱 Babel を決めた背景

私はいくつか自作 npm を公開している。これらは ES2015 以降の機能と構文を利用して npm publish の際に Babel で ES5 相当へ transpile している。この運用で特に問題も起きていない。またプリセットに babel-preset-latest を採用することで ES 関係の規格追従を Babel 任せにできる安心感もあり、ずっとこのままでいいと思っていた。

ある日、職場で Node アプリを開発している人から「Babel 依存は怖くないですか?」という質問があった。Babel にバグがあったら調査や修正は困難だし、使わなくてよいならばそうするに越したことはないのでは?と。

これまで C++、C#、Java などコンパイル前提の言語で開発した経験から、よほどのことがない限りコンパイル結果は信頼に足ると判断していた。また、コンパイルされたマシン語や中間言語を人間が直に記述するのは非常にキツイ。そのため脱コンパイラーという選択肢は現実的ではないと認識している。

一方、JavaScript における transpile は高級言語どうしの変換となる。その気になれば人間が書けるのだ。

transpiler への慣れから、この事実をすっかり忘れていた。Node であれば Web フロントエンドと異なり動作環境の分岐は少なく、package.json の engines にて対象環境を限定することも可能である。ならば新しい Node を前提として脱 Babel を検討してみるのもよさそうと考えはじめた。

そんな折、npm-run-all が v4.0.0 で Babel による transpile を廃止。Node は v4 時点で ES Modules を除く大半の ES2015 機能が実装されているため、この範囲で足りるなら transpile せずにそのままリリース可能だ。その前例として普段利用しているツールが脱 Babel したのはインパクトある。

これらを踏まえ、まずは自作 npm のうちダウンロード数の少なくニッチな wpxml2md から脱 Babel を試してみることにした。

脱 Babel への道のり

脱 Babel 対応で実施したことを書く。

Node 環境の明示的な指定

脱 Babel における前提条件として動作環境とする Node のバージョンを決める。npm-run-all は Node v4 を下限としているようだが、wpxml2md では v6 としておく。

開発と検証コストを考慮して自作 npm の動作環境は「最新 + 最新 LTS」としている。2017/1 時点の最新 Node は v7 系、LTS は v6 と v4 があるため対象は「v7 + v6」となる。これまでは Babel による transpile で v4 以下でも動作していたのだが、これを廃止することで明示的な下限の指定が必要となった。これは package.json の engines プロパティに記述する。

{
  "engines": {
    "node": ">= 6"
  }
}

ちなみに

node v6, v7

というバッヂを用意していて前から README へ掲載していた。今回の対応により、ようやくこれが本来の意味をあらわすようになった。

Babel の transpile を廃止

これまでは Babel の transpile を前提として以下のような Babel 設定と npm-scripts を利用していた。

{
  "babel": {
    "presets": [
      "latest"
    ],
    "env": {
      "development": {
        "presets": [
          "power-assert"
        ]
      }
    }
  },
  "scripts": {
    "test": "mocha --timeout 50000 --compilers js:babel-register test/**/*.test.js",
    "watch": "babel src --out-dir ./ --watch",
    "start": "npm run watch",
    "build": "babel src --out-dir ./",
    "prepublish": "npm run build"
  }
}
script 内容
test 予約された npm run のタスク。 mocha と power-assert によるユニット テスト。
watch 開発用。ファイル監視による自動 transpile を実行。
start 予約された npm run のタスク。watch を呼び出すだけ。
build リリース用。現時点のソース コードで transpile を実行。
prepublish 予約された npm publish 時に呼び出されるタスク。build を呼び出しているため npm として公開されるイメージは transpile されたものになる。なお prepublish は現在 deprecated になっていて prepare へ修正すべきなのだが直し忘れていた。

これが脱 Babel によりこうなる。

{
  "babel": {
    "env": {
      "development": {
        "presets": [
          "power-assert"
        ]
      }
    }
  },
  "scripts": {
    "test": "mocha --timeout 50000 --compilers js:babel-register test/**/*.test.js"
  }
}

transpile 不要となるため関連するタスクが消え、ユニット テストだけが残った。ただし power-assert を利用しているなら標準 assert を置換するための transpile が必要なので、このための設定は維持する。

env.development.presetspower-assert だけ指定することで、Babel 依存がユニット テストに限定されていることが明示されるだろう。必要な Babel 関連の npm も babel-registerbabel-preset-power-assert だけになる。

ES Moduels を CommonJS 化する

Node の ES Modules 対応については以下が詳しい。

なお現時点の最新 Node である v7 においても ES Modules には対応していないため、export/import は CommonJS の exports/require へ修正する必要がある。例えば

export const Options = {
};

export default class CLI {
}

const Options = {
};

class CLI {
}

module.exports = {
  Options: Options,
  CLI: CLI
};

とする。読み込む側は

import CLI from `cli.js`;
import { Options } from `cli.js`;

const CLI = require( `cli.js` ).CLI;
const Options = require( `cli.js` ).Options;

とする。ひとつのモジュールから exportdefault export で複数のインターフェースを公開していると面倒である。しかし ES Modules で書いていたなら import はソース コード冒頭に集約されているから悩む余地なく機会的な作業になる。なんなら正規表現でまとめて変換できる。

ユニット テストについても同様に対応すること。

余談。

CommonJS にした後でも将来の ES Modules 移行を容易にするため require はソース コード冒頭へ書く習慣をつけたほうがよいかもしれない。その場合、読み込み先を camelCase で命名しているとローカル変数と競合する可能性が高くなるため PascalCase にしたくなり、私はそうしている。例えば fsFs と命名している。

Node と CommonJS だとスコープを意識して require を使い分け、なるべく関数ローカルで宣言する派が多数な感じなので ES Modules 対応されたときが気になる。私のようにするか、それともよりよい慣習となるのか?実に楽しみだ。

ESDoc 対応

npm のコード ドキュメント生成に ESDoc を採用している場合、そのままでは CommonJS を解釈できないので対応が必要になる。CommonJS は

上記 issue で紹介されている esdoc-node により対応できる。ESDoc にプラグイン機能があることを初めて知った。これを指定することでコードが ESDoc に解釈される前処理を実行できるらしい。例えば esdoc-node は CommonJS を ES Modules に変換して ESDoc に渡す。

さっそく使ってみよう。まず esdoc-node をプロジェクトに追加。

$ npm install -D esdoc-node

次にこれを ESDoc 設定へ追加する。私は ESDoc の設定を package.json に定義しているので

{
  "esdoc": {
    "source": "./src",
    "destination": "./esdoc",
    "test": {
      "type": "mocha",
      "source": "./test"
    },
    "plugins": [
      { "name": "esdoc-node" }
    ]
  }
}

このようにした。設定後、ESDoc を実行して CommonJS なコードも正しく解析されることを確認。

ただしローカル実行ではなく ESDoc Hosting Service は CommonJS やプラグインに対応していないようだ。試しに wpxml2md の API Document を生成 してみたのだが、2017/1/25 時点では esdoc-node 未指定の状態と同様に CommonJS の絡むものが解釈できていない。

この点について要望 issue を登録してみたのだけど、もしプラグイン対応する場合

  • Hosting Service 側でプラグインを網羅しておき選択実行する
    • プラグインを中央管理する仕組みがないと網羅できない
    • プラグインのバージョンはどうするのか?常に最新?
  • プロジェクトの ESDoc 設定と package.json から動的にプラグインを決定する
    • プラグインのインストールはどうする?
    • ドキュメント生成とごにプラグインをインストールすると Hosting Service の負荷が大きい
    • CI 系サービスのように VM や Docker コンテナで対応するとしても負荷は大きい

といった問題が予想されるため難しそうだ。しかし要望があることだけは記録しておきたかったので issue 登録することにした。

別の方法として ESDoc 本体が esdoc-node 処理を取り込むという選択肢もある。ただ、いずれ Node が ES Modules へ正式に対応するとしたら CommonJS は過渡期の存在である。

  • そのために対応コストを割くのか?
  • ESDoc と名乗るツールとして ECMAScript とは直に関係しない CommonJS へ対応することは設計思想として望ましくないのでは?

という考えもあるだろう。どのような対応、または非対応のままになったとしても ESDoc 作者の意向を尊重したい。

ESDoc Hosting Service を利用しない場合、対象プロジェクトが GitHub で管理されているならそのリポジトリに対して GitHub Pages を使う手もある。ローカルの ESDoc + esdoc-node で出力したものを自前でアップロードするか、そういうタスクを npm-scripts に定義して CI サービス経由で生成から公開まで自動化するなどの方法が考えられる。

本記事を書いた直後に ESDoc 作者の @h13i32maru さんから見解が。

ESDoc Hosting Service 的にはセキュリティや負荷を考慮し、ESDoc 公式プラグインのみサポートしているとのこと。ただ Node の ES Modules 対応は相当に先となりそうなので、この長い過渡期に Node かつ脱 Babel したい開発者としてどうか?という悩ましい課題がある。

まとめ

一部、問題もあったが transpile 不要となったことで Node のバージョンだけを意識して開発すればよい。記述したコードはそのまま実行されることが保証される。Babel 由来の潜在的なトラブルを考えなくてよいため精神的に楽。

あと npm をユニット テストではなく普通のプログラムとして走らせて検証してみたい場合、いちいち transpile しなくて済むのも助かる。

検証はテストに定義すべきでは?という意見もあるだろうけどリポジトリの examples フォルダに npm として参照したときのサンプルを配置しているとき、その動作検証で npm publish する前の現行コードを試したくなったりする。その場合、transpile なしだとビルド系タスクを実行せず動かせてよい。

以上を踏まえ、他の npm についても気が向いたら脱 Babel してゆく予定。

npm-scripts でクロスプラットフォームに環境変数を参照するための npm を作成してみた

2016年5月19日 0 開発 , , , ,

以下の記事で npm-scripts から環境変数を参照する方法と問題点について書いた。

課題として npm run するプラットフォームによって変数の参照記法が異なるため、それらを統一できないという問題がある。npm-scripts でタスク管理したい派としては、これをどうしても解決したかったので、そのための npm を作成してみた。

以下に npm の設計などをまとめる。

npm-scripts における環境変数の参照記法

冒頭のリンク先でも解説してあるが、改めて。package.json に定義された値を npm-scripts から環境変数として参照する場合の記法は以下となる。

Platform Format
OS X, Linux $npm_package_NAME or $npm_package_config_NAME
Windows %npm_package_NAME% or %npm_package_config_NAME%

今のところ標準の npm run でこれを統一する方法はないらしい。よってプラットフォーム毎に script を分けるか cross-env のような npm により scripts を wrap して参照を解決しなくてはならない。

cross-conf-env

というわけで、npm-scripts 内の環境変数に対する参照記法をクロスプラットフォームに解決する npm を開発してみた。名づけて cross-conf-env。cross-env のアイディアと設計を参考にしたので、それに準じた命名にしてある。

まずはインストール。package.json が既に定義されている状態としてコマンドを実行。

$ npm i -D cross-conf-env

cross-conf-env では以下の参照記法をサポートしている。

Platform Format
OS X, Linux $npm_package_NAME or $npm_package_config_NAME
Windows %npm_package_NAME% or %npm_package_config_NAME%
独自 npm_package_NAME or npm_package_config_NAME

これらのどれを採用してもよいし、混在も許可している。独自を選ぶと記法が統一できる。それ以外を選んだ場合はプラットフォーム、cross-conf-env の順に記法が解決される。

package.json の利用例。

{
  "name": "sample",
  "version": "1.0.0",
  "config": {
    "app": "MyApp"
  },
  "scripts": {
    "var": "cross-conf-env echo npm_package_config_app npm_package_version",
    "var:bash": "cross-conf-env echo $npm_package_config_app $npm_package_version",
    "var:win": "cross-conf-env echo %npm_package_config_app% %npm_package_version%"
  },
  "devDependencies": {
    "cross-conf-env": "^1.0.0"
  }
}

script の先頭に cross-conf-env を宣言、その後に実行したいコマンドを続ける。cross-conf-env はそれらを引数として扱い、環境変数の参照を検出したら解決してから子プロセスとしてコマンドを実行する。

設計について。

npm-cross-conf-env/cross-conf-env.js のみで完結する小さな実装。これを npm の体裁でくるんでいるだけ。おこなっていることも単純で、

  1. process.env から npm_package_ を接頭語とするプロパティを列挙
  2. process.argv の index = 1 以降を抽出、argv とする
  3. argv から 1 のプロパティ名を含む値を検索
  4. もし含むならその部分を process.env の当該プロパティの値に置換
  5. argv の先頭をコマンド、以降を引数として子プロセス起動

という感じ。

より実践的な利用方法

akabekobeko/examples-electron の各プロジェクトにある package.json を参照のこと。

これらは npm-scripts を共通にしつつ、実行ファイル名やパッケージ化に使用する Electron のバージョンを config に切り出している。そのため流用が容易になり、設定を変えたくなった場合も長大な script を慎重に直すのではなく config を書き換えるだけで済む。

環境変数の解決により npm-scripts からハードコード部分を減らせる。これを前提にするとタスクランナーとしての実用性がグッと増すはず。

Normalize.css を npm で管理して Stylus に組み込む

2016年4月19日 0 開発 , ,

これまで Stylus から Normalize.css を利用する場合、以下のように管理していた。

  1. bymathias/normalize.styl から normalize.styl をダウンロード
  2. プロジェクトの src/stylus/lib フォルダ内に normalize.styl を配置
  3. Stylus のエントリー ポイントで @import "lib/normalize.styl"

つまり静的リソースとして扱い、バージョン更新があれば手動で置き換えていた。面倒な作業だが、CSS では JavaScript における npm と Browserify/webpack のようなリンカー的な仕組みが確立していないと考えており、また、更新も滅多にないことから放置していた。

しかしふと、Normalize.css のサイトをチェックしたら 公式 npm が用意されていた。また Stylus 版の最終更新をみると 11 months ago である。necolas/normalize.css だと a day ago なので、確実に最新へ追従できていない。

というわけで、以下の対応を検討することにした。

  • Normalize.css を npm で管理する
  • npm でインストールした Normalize.css を Stylus に組み込む

Normalize.css を npm で管理する

公式 npm をインストールする。

$ npm i -S normalize.css

Normalize.css は以下の階層に配置されていた。

node_modules/normalize.css/normalize.css

JavaScript の場合、Browserify などが node_modules 配下をよしなに判定してパッケージ名による import/require 処理してくれるのだが、Stylus にそのような特別措置はないので、このパスが重要になる。

Stylus に Normalize.css を組み込む

私は Stylus のコンパイルは CLI で実行している。package.json の npm-scripts 定義は以下のようになる。

{
  "scripts": {
    "build:css": "stylus -c ./src/stylus/App.styl -o ./src/bundle.css -m --sourcemap-root ./stylus",
    "watch:css": "stylus -c -w ./src/stylus/App.styl -o ./src/bundle.css -m --sourcemap-root ./stylus",
    "release:css": "stylus -c ./src/stylus/App.styl -o ./dist/bundle.css"
  }
}

App.styl を Stylus のエントリー ポイントにして、Web サイトやアプリの部位ごとに定義した .styl ファイルを @import している。前述のように Normalize.css は外部の静的リソースということで lib に配置したものを参照。

@import "lib/Normalize.css"
@import "Base.css"
@import "Header.css"

これを npm 版に変更する。

@import "../../node_modules/normalize.css/normalize.css"
@import "Base.css"
@import "Header.css"

この状態でコンパイル実行してみると、生成された bundle.css では通常の @import になってしまった。

@import "../../node_modules/normalize.css/normalize.css"

/* Base.css と Header.css の定義 */

同一または下層の .styl であれば埋め込みになるので、npm 側もそうなると考えていたのだが、違った。Executable — Stylus を読むと @import を常に埋め込みとする場合は --include-css オプションが必要とのこと。

npm-scripts を修正する。

{
  "scripts": {
    "build:css": "stylus -c --include-css ./src/stylus/App.styl -o ./src/bundle.css -m --sourcemap-root ./stylus",
    "watch:css": "stylus -c -w --include-css ./src/stylus/App.styl -o ./src/bundle.css -m --sourcemap-root ./stylus",
    "release:css": "stylus -c --include-css ./src/stylus/App.styl -o ./dist/bundle.css"
  }
}

この状態で Stylus をコンパイルしたら、npm の Nomarlize.css が埋め込まれるようになった。

/*! normalize.css v4.1.1 | MIT License | github.com/necolas/normalize.css */

/**
 * 1. Change the default font family in all browsers (opinionated).
 * 2. Prevent adjustments of font size after orientation changes in IE and iOS.
 */

/* ...中略  */

/* Base.css と Header.css の定義 */

Stylus 内に node_moduels のパスを書くのは抵抗あるけど、しかたない。

この方法は bootstrapmaterial-ui みたいなフレームワークの利用には不向きだが、Normalize.css みたいに単体で完結した CSS ライブラリなら機能するだろう。