CSS Modules をもっと試す

2018年2月20日 0 開発 , , , ,

業務プロジェクトへ CSS Modules 導入を検討中。しかし JS/CSS ともに大きく設計変更されるため、いきなり採用するのは怖い。というわけで、そこそこの規模と複雑さを持つ examples-electron/audio-player で試してみた。このプロジェクトは Electron 製の簡易音楽プレーヤーになる。JS/CSS まわりはこんな感じ。

  • JavaScript
    • AltJS は Babelbabel-preset-env、ES.next 範疇の機能と構文のみ使用、ターゲット設定は electron なので少し古い Chorome 相当になる
    • View は React
    • Flux は material-flux、いずれ reduxmobx あたりへ乗り換える予定
    • Bundler は webpack
    • Electron の Main/Renderer プロセスともに Bundle/Transpile 対象
  • CSS
    • AltCSS は Stylus
    • Bundler/Transpiler ともに stylus で完結
    • CSS クラスは BEM、定義で楽するため Stylus のネスト機能に強く依存している
    • IcoMoon で生成した Icon Font を利用

このような環境に CSS Modules (with Sass) を導入して遭遇した問題や対策を記録する。

webpack.config.js

Sass を試す の CSS Modules (with Sass) + webpack 構成を踏襲しながら少し修正。Babel や package.json は CSS Modules とあまり関係ないので webpack.config.js のみ掲載。webpack v3 の設定になる。近くリリースされるという webpack v4 で変更が必要になるかもしれないけど、CSS Modules 部分はそのまま維持できると思う。

import WebPack from 'webpack'
import MinifyPlugin from 'babel-minify-webpack-plugin'
import ExtractTextPlugin from 'extract-text-webpack-plugin'

export default (env) => {
  const MAIN = env && env.main
  const PROD = !!(env && env.prod)

  return {
    target: MAIN ? 'electron-main' : 'web',
    entry: MAIN ? './src/js/main/App.js' : './src/js/renderer/App.js',
    output: {
      path: PROD ? `${__dirname}/dist/src/assets` : `${__dirname}/src/assets`,
      filename: MAIN ? 'main.js' : 'renderer.js'
    },
    devtool: PROD ? '' : 'source-map',
    node: {
      __dirname: false,
      __filename: false
    },
    module: {
      rules: [
        {
          test: /\.js$/,
          exclude: /node_modules/,
          use: {
            loader: 'babel-loader'
          }
        },
        {
          test: /\.scss$/,
          use: ExtractTextPlugin.extract([
            {
              loader: 'css-loader',
              options: {
                modules: true,
                localIdentName: PROD ? '[hash:base64]' : '[name]-[local]-[hash:base64:5]',
                url: false,
                importLoaders: 1,
                sourceMap: !(PROD),
                minimize: PROD ? { autoprefixer: false } : false
              }
            },
            {
              loader: 'sass-loader',
              options: {
                outputStyle: PROD ? 'compressed' : 'expanded',
                sourceMap: !(PROD)
              }
            }
          ])
        }
      ]
    },
    plugins: PROD ? [
      new MinifyPlugin({
        replace: {
          'replacements': [
            {
              'identifierName': 'DEBUG',
              'replacement': {
                'type': 'numericLiteral',
                'value': 0
              }
            }
          ]
        }
      }, {}),
      new WebPack.DefinePlugin({
        'process.env.NODE_ENV': JSON.stringify('production')
      }),
      new ExtractTextPlugin({ filename: 'bundle.css' })
    ] : [
      new ExtractTextPlugin({ filename: 'bundle.css' })
    ]
  }
}

デバッグ用 CSS クラス名

CSS Modules は CSS クラス名を自動的にハッシュ化してくれるのだが、このままだと DevTools から確認したいときに困る。Source Maps があれば元のスタイルを参照できるものの、HTML 要素の class 属性から React コンポーネントを人間が識別するのは難しい。よって css-loader の options を工夫する。

{
  localIdentName: PROD ? '[hash:base64]' : '[name]-[local]-[hash:base64:5]'
}

デバッグ時は [name]-[local]-[hash:base64:5] としておく。生成されたクラス名は AudioPlayerControl-player-1sCWC のような感じとなり人間にもわかりやすい。終端のハッシュでユニークさも担保される。モジュールとクラス名だけでユニークさを保証できるならハッシュを外してもよい。私は保険のためにつけてる。

リリース版についてはお好みで。私はエンド ユーザー仕向けなので実装の詳細は見せないほうがよいと考えており、それを明示するための難読化としてハッシュ化することにした。エンド ユーザーに開発の協力をあおぐとしてもデバッグ版を提供すればよい。

Sass の @import と CSS Modules の注意点

Sass の SCSS 内で @import するとその単位で参照が解決される。これと CSS Modules を組み合わせる場合は注意が必要。例えば Test.scss に

.test {
  color: red;
}

を定義して Content.scss と Footer.scss がそれぞれ @import したとする。これらを更に JavaScript から参照すると Test.scss の内容が Content.scss と Footer.scss で個別に展開されてから CSS Modules に結合されるため

/* Content.scss から @import "Test.scss" した部分 */
._3lCv-t9tW054o8vckddf2y {
  color: red;
}

/* Footer.scss から @import "Test.scss" した部分 */
._15Cb513oAuCYe4NCm3MT69 {
  color: red;
}

のように重複してしまう。CSS Modules は JavaScript からの参照解決だけを担当してモジュール内の参照は考慮しないようだ。

これを避けるために共用したい SCSS は CSS セレクターとして有効な定義をせず、変数や Mix-In に限定すればよい。そもそも CSS セレクターを参照しても利用する方法がないわけで、継承とか合成ならば Sass として @mixin@extend が提供されている。

CSS Modules の結合順とグローバル

CSS Modules の結合は JavaScript 側の参照順となる。CSS Modules を利用しようと考える時点で JS/CSS は疎結合になっているだろうから、普段は順番を意識することはない。しかし例えば

  • <html><body> などのスタイルを CSS 全体で一度だけ定義したい
  • アイコン フォントは個別に参照せずグローバルに一度だけ定義したい

ということもあるだろう。これを実現してみる。

まずは CSS の参照位置。これは JavaScript 側のエントリー ポイント冒頭にする。例えば App.js がエントリー ポイントなら

import './App.scss'

// 以下、エントリー ポイント処理...

のように読み込む。JavaScript 側で直に参照するものはないため from は不要。考え方としては babel-polyfill に近い。これで App.scss に定義されたスタイルは CSS の先頭に展開される。

次にグローバルな CSS クラス名。これは css-modules/css-modules の README で解説されているとおり :global で囲む。例えば .app というクラス名をハッシュ化せず維持したいなら以下のようにすればよい。

:global {
  .app {
    width: 100%;
    height: 100%;
    background-color: $color_white;
  }
}

これはサード パーティ製 CSS 内のハッシュ化を防ぐためにも使える。

:global {
  @import "~library.css";
}

こうすれば対象となる CSS 内に定義されたクラス名が維持される。配布形態が npm なら ~モジュール名 とすることで node_modules 配下のパスを省略も可能。

ただしこの機能にはバグがある。2018/2 時点の css-loader だと :global 内に font-face があると { font-face {} } のように余計なブラケットで囲まれてしまう。そのため font-awesome を対象にすると CSS が壊れてしまう。

アイコン フォントのクラス名

アイコン フォントを利用する場会は前述の問題があるため font-face:global に囲えない。よってアイコンの CSS クラス名を維持するならそこだけを :global に囲み font-face はむき出しにする必要がある。CSS クラス名を維持せずハッシュ化を許容するとしても別問題がある。

例えば

[class^="icon-"], [class*=" icon-"] {
  font-family: "icon";
  speak: none;
  font-style: normal;
  font-weight: normal;
  font-variant: normal;
  text-transform: none;
  line-height: 1;

  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
}

.icon-rew:before {
  content: "\e800";
}

.icon-warning:before {
  content: "\e801";
}

のようにセレクター名で共通部分を定義する場合、そこを維持しなければならない。これは「デバッグ用 CSS クラス名」の項で書いたように css-loader の localIdentName を工夫すれば解決可能ではある。しかしこの方法だと全 CSS クラス名に影響するため設計的に好ましくない。またアイコン フォントは複数箇所から同時に利用したくなるだろうし、その場合は性質としてグローバルだ。

よって font-face 以外は :global でまるごと保護する方が運用しやすい。React コンポーネント側はそのまま直値で CSS クラス名を指定する。

font-faceurl 参照

font-face の参照で src:url() にローカルの相対パスを指定した場合、css-loader の処理時点で参照が解決されなければならない。そのため

.
├── assets
│   ├── index.html
│   └── fonts
│       ├── icon.eot
│       ├── icon.svg
│       ├── icon.ttf
│       └── icon.woff
└── js
    ├── App.js
    └── App.scss

のような構成で以下のように定義しているとエラーになる。

@font-face {
  font-family: "icon";
  src:url("fonts/icon.eot");
}

CSS の出力先が assets/ であっても css-loader は CSS から参照されているものを直に解決しようとするため、App.scss から fonts/icon.eot が見えないといけない。これを防ぐためには css-loader の optionsurl: false を設定する。これで src: url() の参照を無視してくれる。自前でアイコン フォントを用意するなら、これとグローバル指定を組み合わせて CSS のエントリー ポイントへまとめて定義するとよい。

@charset "UTF-8" 問題

アイコン フォントの定義で content: "\e800"; のように非 ASCII 文字を指定すると sass-loader が気を利かせて @charset "UTF-8"; を挿入してくれる。しかし「Sass の @import と CSS Modules の注意点」で書いた問題を考慮しなければならない。

例えば <html><body> などのスタイルを Base.scss、アイコン フォント系を Icon.scss に定義したとしよう。これらをエントリー ポイントになる App.scss で

@import "Base.scss";
@import "Icon.scss";

のように読み込んだ場合、

html, body {
  width: 100%;
  height: 100%;
  margin: 0;
  padding: 0;
}

@charset "UTF-8";
@font-face {
}

という感じで出力される。Icon.scss で初めて非 ASCII 文字が登場したため、このファイルを展開する位置に @charset "UTF-8"; が挿入されてしまった。これは @charset で解説されているとおり CSS として不正である。

対策するなら

  • 順番を意識して慎重に @import する
  • グローバルなものはファイル分割せず、エントリー ポイントで直に定義する

ことになる。私は設計的に単純な後者を採用した。直に定義するとファイルが長くなる懸念はある。しかし CSS Modules を採用しているならグローバルは少なくなるはず。そうでないならコンポーネントやモジュールの分割に問題があるため、設計を見直したほうがいい。

npm の font-awesome を利用するなら?

npm の font-awesome を利用するなら、ここまで書いたアイコン フォントに絡む問題をすべて解決しなければならない。

CSS クラス名の維持

CSS クラス名を維持する場合は :globalfont-face が壊れる問題を対策する。そのためには npm で配布されたファイルを加工する必要がある。font-face 以外を :global で囲むことになるだろう。これは npm 管理の観点からおこなうべきではない。配布されたものをそのまま利用できないなら、npm を採用する意味がない。

font-facesrc:url() 問題

font-facesrc:url() 問題について。これは大まかに二つの対策がある。

  1. url-loader で参照解決して出力 CSS に base64 文字列としてフォント ファイルを埋め込む
  2. 参照をスキップさせて CSS 出力先へフォント ファイルを都度コピーする

1 は CSS ファイルが巨大になる問題あり。これを許容できるなら Bundler という観点として正当な方法といえる。2 は出力された CSS から参照できればよい点は好ましいのだけど font-awesome の font-face 定義は

@font-face {
  font-family: 'FontAwesome';
  src: url('../fonts/fontawesome-webfont.eot?v=4.7.0');
  src: url('../fonts/fontawesome-webfont.eot?#iefix&v=4.7.0') format('embedded-opentype'), url('../fonts/fontawesome-webfont.woff2?v=4.7.0') format('woff2'), url('../fonts/fontawesome-webfont.woff?v=4.7.0') format('woff'), url('../fonts/fontawesome-webfont.ttf?v=4.7.0') format('truetype'), url('../fonts/fontawesome-webfont.svg?v=4.7.0#fontawesomeregular') format('svg');
  font-weight: normal;
  font-style: normal;
}

のように ../fonts/ を参照しているため、出力先でこの構造を再現しなければならない。例えば

.
├── index.html
├── css
│   └── bundle.css
└── fonts
    ├── FontAwesome.otf
    ├── fontawesome-webfont.eot
    ├── fontawesome-webfont.svg
    ├── fontawesome-webfont.ttf
    ├── fontawesome-webfont.woff
    └── fontawesome-webfont.woff2

こんな感じ。Bundler で単一 CSS ファイルを出力していると、それひとつだけ格納するフォルダーを用意するのは抵抗がある。webpack loader/plugin を駆使してパスを書き換える手もあるだろうけど font-awesome の定義変更に影響されるため微妙。

@charset "UTF-8" 問題

font-awesome の @import を全 CSS の先頭にもってくればよい。

これは制約になるためコミット ログだけでなくコメントでソース自体に明記しておいたほうがよい。第三者が @import 周りを整理しようとして事故らないためにも。

そもそも Bundler と相性よくない

font-awesome を Bundler と組み合わせて利用したい需要はそれなりにあるようで、

といった記事で対策が紹介されている。しかし特定 npm の設計による問題を解決するために特別な npm や設定を用意するのは泥縄ではないか。問題が問題を呼んでいる。依存も増えるし労に見合わない。

よって私が Font Awesome を利用するとしたら npm ではなく静的リソースとして直に組み込む。fonts/ を好みの場所に置き、CSS も書き換える。Releases – FortAwesome を見るに更新頻度はさほどでもないし、手動で管理しても大した手間ではないだろう。なお npm 版は CSS/SCSS/LESS ファイルをまとめて提供してくれるため、手動で組み込むための元ネタとしてインストールする価値はある。

Babel や Sass のように Font Awesome が公式に webpack loader/plugin をサポートしてくれることへ期待している。

JS/CSS の配置

CSS Modules を採用することで CSS は特定の React コンポーネント専用になる。よって JS/CSS は併置すると運用しやすい。例えばこんな感じで。

.
├── AlbumListContainer.js
├── AlbumListContainer.scss
├── AlbumListHeader.js
└── AlbumListHeader.scss

併置することで JavaScript 側から参照するときの相対パスが短くなる。ファイル名は一緒にして拡張子だけ変えると関連していることがわかりやすい。ただし同名ゆえに参照する際は拡張子まで記述すること。拡張子を省略すると参照している自身と区別できないので。

CSS クラスのネストについて

CSS Modules を利用しない場合、CSS クラスはすべてグローバルになることを前提に名前衝突を避けるため様々な工夫が必要だった。私も命名規則として BEM (Block Element Modifier) を採用していた。しかしベタに書いてゆくと

.button {}
.button--state-success {}
.button--state-danger {}

のようになってダルいため Stylus のネスト機能を使って

.button {
  &--state {
    &-success{}
    &-danger {}
  }
}

のように定義していた。CSS Modules を利用するなら衝突を気にする必要がないため、ネストさせず

.button {}
.success {}
.danger {}

のように書けばよい。モジュール分割されることでその単位のコンテキストが明示されるから従属しているものを簡素なクラス名にしても通じる。この例であればファイル名が Button.scss なら .button.container.base といった基礎部分をあらわすようにしてもよいだろう。

DOM 要素、擬似要素、擬似クラスに関しては CSS Modules の範疇外だが、これらも

.button {
  img {}
  &:hover {}
}

とするよりは

.button img {}
.button:hover {}

のように CSS 標準で書くほうがよいのかもしれない。これについては私もどうするか迷っている。しかし CSS 標準に寄せておけば CSS Modules や Sass への依存度をなるべく下げることでツールを捨てやすくなる。CSS を第三者と共有する際にも前提知識が CSS 標準の範疇で済むため混乱が起きにくいだろう。というわけで新たに書くならネストなしを採用する予定。

CSS Modules と CSS in JS について

React コンポーネントと CSS を連携させる手段として CSS Modules の他に CSS in JS という勢力がある。これらの違いについては古い記事だけど以下がわかりやすい。

特に後者ではそれぞれの弱点をとりあげていて納得感もある。しかし私は Free-Style の弱点で触れられている

CSS Modules は CSS で書くので、「いつでも引き返せる」みたいな安心感は CSS Modules の方が強いと思う

を重視するため CSS Modules を選ぶことにした。CSS in JS は Free-Style 以外にもいくつかあって、これも古い記事になるけど

が参考になる。で、この「いくつかあって」というのが問題。

CSS の Property/Value 記法は JavaScript オブジェクトの Key/Value と似ているため、ほぼそのまま書けそうに思える。しかし擬似要素や擬似クラスなどは対応しそうな構文がないため、諦めるか特別な記法を持ち込むことになる。そしてこの対策がツール間でまちまちなのだ。依存すると引き返すのが難しくなる。

CSS in JS を利用する動機として JavaScript から動的に変更しやすいというのがある。これについては外観に関わるものなら値そのものを書き換えるより CSS クラスを変更する従来式で十分だと考えてる。

静的でよければ Sass や Stylus にも変数はあるので外観プリセット切り替えのような目的には対応できる。動的なものとしても CSS 標準で calc などが控えてる。ならばわざわざ JavaScript 側でがんばらなくてよいのでは?というのが私の見解。

高機能なのはわかるけど、それなしに CSS 標準へ寄せて運用できるならそうしたい。この辺、CSS in JS について解説してる記事を読んでもピンとこなかったところなので識者の意見をうかがいたい。

gulp で uglify-es を利用する

2017年6月14日 0 開発 , ,

タスクランナーは npm-scripts 派なのだけど、akabekobeko/examples-web-app に公開している front-end-starter には gulp 版も用意してある。かつて gulp を利用していたこと、世間では現在もそれなりに Web フロントエンド開発で gulp が採用されていることから動向チェック用にメンテナンスしている。

front-end-starter は Electron も含む Web フロントエンド開発環境の変更を気が向いたときに反映しているのだが、そういえば uglify-es を gulp で利用したくなったらどうするのだろう?というのが気になったので試してみた。

gulp-uglify

gulp で uglify-js を利用する場合、gulp wrapper となる gulp-uglify を採用するのが一般的だろう。では uglify-es はどうなのか。uglify-js 本家が uglify-es を独立したパッケージとしているように gulp-uglify-es があるとか?と予想したが gulp-uglify として js/es を切り替えられるようになっていた。

README の Using a Different UglifyJS から引用する。

By default, gulp-uglify uses the version of UglifyJS installed as a dependency. It’s possible to configure the use of a different version using the “composer” entry point.

標準では dependency としてインストールされた uglify-js を使用するが、composer を利用することで js/es を分岐できるとのこと。以下は README に併記されているサンプル コード。

var uglifyjs = require('uglify-js'); // can be a git checkout
                                     // or another module (such as `uglify-es` for ES6 support)
var composer = require('gulp-uglify/composer');
var pump = require('pump');

var minify = composer(uglifyjs, console);

gulp.task('compress', function (cb) {
  // the same options as described above
  var options = {};

  pump([
      gulp.src('lib/*.js'),
      minify(options),
      gulp.dest('dist')
    ],
    cb
  );
});

gulp ストリーム (pipe) をそのまま使用せず pump で wrap している点を除けば、割りと簡単に切り替えられるようだ。

gulp タスク修正

gulp-uglify としては pump を推奨しているようだが、以下のように gulp-watchify と組み合わせていると書き換えが多くなるので、

// ...import や gulp-load-plugins の設定など

gulp.task('js', $.watchify((watchify) => {
  const time = process.hrtime()

  return gulp.src([ config.dir.js + 'App.js' ])
    .pipe($.plumber())
    .pipe(watchify({
      watch: config.isWatchify,
      basedir: './',
      debug: true,
      transform: [ 'babelify' ]
    }))
    .pipe(VinylBuffer())
    .pipe($.if(!(config.isRelease), $.sourcemaps.init({ loadMaps: true })))
    .pipe($.if(config.isRelease, $.uglify()))
    .pipe($.rename('bundle.js'))
    .pipe($.if(!(config.isRelease), $.sourcemaps.write('./')))
    .pipe($.if(config.isRelease, gulp.dest(config.dir.dist), gulp.dest(config.dir.assets)))
    .on('end', () => {
      const taskTime = PrettyHRTime(process.hrtime(time))
      $.util.log('Bundled', $.util.colors.green('bundle.js'), 'in', $.util.colors.magenta(taskTime))
    })
}))

gulp ストリームのまま移行する。

// ...import や gulp-load-plugins の設定など

// 追加
import UglifyES from 'uglify-es'
import UglifyComposer from 'gulp-uglify/composer'

gulp.task('js', $.watchify((watchify) => {
  const time = process.hrtime()

  // uglify-es で minify するための関数設定
  const minify = UglifyComposer(UglifyES, console)

  return gulp.src([ config.dir.js + 'App.js' ])
    .pipe($.plumber())
    .pipe(watchify({
      watch: config.isWatchify,
      basedir: './',
      debug: true,
      transform: [ 'babelify' ]
    }))
    .pipe(VinylBuffer())
    .pipe($.if(!(config.isRelease), $.sourcemaps.init({ loadMaps: true })))
    // uglify-es で minify
    .pipe($.if(config.isRelease, minify({})))
    .pipe($.rename('bundle.js'))
    .pipe($.if(!(config.isRelease), $.sourcemaps.write('./')))
    .pipe($.if(config.isRelease, gulp.dest(config.dir.dist), gulp.dest(config.dir.assets)))
    .on('end', () => {
      const taskTime = PrettyHRTime(process.hrtime(time))
      $.util.log('Bundled', $.util.colors.green('bundle.js'), 'in', $.util.colors.magenta(taskTime))
    })
}))

このサンプルには掲載していないが、別のリリース用イメージ生成タスクで config.isReleasetrue にしてから js タスクを実行することで、uglify-es による minify 処理が走ることを確認できた。

まとめ

Electron や Chrome (Chromium) のように先進的な環境を決め打ちで開発したり、babel-preset-env で環境を抽象化しつつ変換を最小におさえると minify 対象となるコードに ES.next 部分があらわれる。その際は minify ツール側も ES.next 対応が求められるため uglify-esbabili を利用することになるだろう。gulp に関しては本記事のように gulp-uglify の機能として uglify-es を採用するとよい。

ところで gulp-uglify の設計は gulp wrapper における問題へのよき回答にもなっており、感心した。

gulp を想定していない npm を gulp ストリームにのせる場合、vinyl-buffer などで頑張るか、そのような処理で wrap した gulp プラグインとする必要がある。前者はエンド ユーザー負担が大きすぎるので後者を選ぶことが多いのだけど、こちらだと gulp プラグインの dependency で wrap 対象 npm の更新へ追従しなければならない。

gulp-uglify/composer 方式なら自身の dependency が古びても、エンド ユーザー側から任意バージョンの npm を指定できる。つまり gulp 化の恩恵を享受しつつ、最新 npm に置き換えられるのだ。対象 npm のインターフェースが維持されていることは前提となるが、うまい方法である。自身の dependency + 同一インターフェース npm をサポートできる。

私がタスクランナーを gulp から npm-scripts へ移行した理由のひとつは gulp プラグインの陳腐化なのだけど、この設計が普及すれば、この問題に関しては概ね解決しそうである。gulp プラグインのガイドラインに含めてもよいのでは、とも思う。

この記事を書いた後に気付いたのだが babili の gulp 版として gulp-babili が提供されている。こちらは Babel/babili 本家なので、Babel ファミリーを好むなら uglify-es の代りに採用してもよいだろう。

npm 開発で再び Babel を導入することにした

2017年4月17日 0 開発 , , ,

以前、npm 開発で脱 Babel してみるという記事を書いた。そして二ヶ月ほど特に問題なく運用できていたのだが、babel-preset-env を試してみたら考えが変わった。

脱 Babel を決めた時点では latest で常時 ES5 変換か plugin を細かく組み合わせることを想定していた。しかし babel-preset-env なら明示的に Node のバージョンを指定することで必要最小の変換をおこなえる。Node としては ES Modules 以外の ES.next 仕様へ積極対応しているため、Active な LTS を下限としておけば変換は ES Modules + α ぐらいで済む。

というわけで Babel を再導入することにした。

プロジェクト構成

Babel を再導入した akabekobeko/npm-xlsx-extractor の構成例。

.
├── package.json
├── examples/
├── dist/
└── src/
    ├── bin
    └── lib
名前 内容
package.json プロジェクト設定ファイル。
dist/ リリース用ディレクトリ。ビルドによって動的生成される。.gitignore 対象。
src/ 開発用ディレクトリ。
src/bin npm を CLI として実行した時のコードを格納するディレクトリ。
src/ npm を Node として実行した時のコードを格納するディレクトリ。

よくある構成だとこれに mocha などのユニット テストを格納するため test/ があるものだけど、Babel 再導入にあたりテストは対象となるコードのあるディレクトリに併置した。

プロジェクト設定

プロジェクト設定はすべて package.json に定義。必要最小の内容を抜粋する。

{
  "engines": {
    "node": ">= 6"
  },
  "main": "dist/lib/index.js",
  "bin": "dist/bin/index.js",
  "files": ["dist"],
  "esdoc": {
    "source": "./src",
    "destination": "./esdoc",
    "test": {"type": "mocha", "source": "./src"}
  },
  "babel": {
    "presets": [
      ["env", {"targets": {"node": 6}}]
    ],
    "env": {
      "development": {
        "presets": [
          "power-assert"
        ]
      }
    }
  },
  "scripts": {
    "test": "mocha --timeout 50000 --compilers js:babel-register src/**/*.test.js",
    "start": "npm run watch",
    "esdoc": "esdoc",
    "eslint": "eslint ./src",
    "build": "babel src --out-dir dist --ignore *.test.js,typedef.js",
    "watch": "babel src --out-dir dist --ignore *.test.js,typedef.js --watch",
    "prepare": "npm run build"
  },
  "devDependencies": {
    "babel-cli": "^6.24.1",
    "babel-preset-env": "^1.3.3",
    "babel-preset-power-assert": "^1.0.0",
    "babel-register": "^6.23.0",
    "esdoc": "^0.5.2",
    "eslint": "^3.15.0",
    "eslint-config-standard": "^6.2.1",
    "eslint-plugin-promise": "^3.4.2",
    "eslint-plugin-standard": "^2.0.1",
    "mocha": "^3.2.0",
    "power-assert": "^1.4.2"
  }
}

順に解説する。

ビルド設定

babel-preset-env を "node": 6 にする。2017/4/1 をもって Node v4 LST は Maintenance になったので、Active な v6 LTS を下限としている。すべての dependencies が v4 対応しているなら Babel がよしなに変換してくれるので "node": 4 にしてもよい。

Babel 再導入を機にコードを ES2015 以降の仕様で書き直した。Node は v6 で大半の ES2015 仕様に対応したので大きな変換は Modules と CommonJS 変換ぐらいとなる。ビルド関係の npm-scripts は以下。

{
  "scripts": {
    "build": "babel src --out-dir dist --ignore *.test.js,typedef.js",
    "watch": "babel src --out-dir dist --ignore *.test.js,typedef.js --watch"
  }  
}

ユニット テストは src/ 内で対象となるコードと併置している。また ESDoc 用に class や module として定義されないものを記述した typedef.js がある。これらは Babel 変換する意味がないので bbel-cli の --ignore オプションで除外。コード検証は基本的にユニット テストを利用するが、npm link で CLI の実操作を試しやすくするために watch タスクを定義している。

ビルド結果の出力先は dist/ にしている。以前はプロジェクト直下に bin/lib/ を生成していたが、現時点の npm react 構造を参考に変えた。node_modules の中身を気にするユーザーはそれほどいないし package.jsonmainbin を明示できるのだから階層が深くなっても問題ないはず。

注意点がひとつ。過去に Babel で変換していた時もそうしていたのだが、export default class XlsxExtractor が CommonJS 化されると exports.default = XlsxExtractor; になり、これをそのまま require した場合、constructor を利用できなくなる。この問題を回避するためには

import XlsxExtractor from './xlsx-extractor.js'
module.exports = XlsxExtractor

という仲介処理を定義し、それを npm の main にエントリー ポイント指定する。このファイルは以下のように変換され、

'use strict';

var _xlsxExtractor = require('./xlsx-extractor.js');

var _xlsxExtractor2 = _interopRequireDefault(_xlsxExtractor);

function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }

module.exports = _xlsxExtractor2.default;

通常の require で読んだ状態と等しくなる。Babel 変換対象の範囲内であればうまく解決されるのだが、npm としてエントリー ポイントを提供する場合は忘れずに対応しておく。

私はこれを忘れてリリースして examples が動かず冷や汗をかいた。

ユニット テスト、ESLint、ESDoc

wip-testable-js.md の影響でテスト用コードと対象を併置。具体的には以下となる。

.
├── bin
│   ├── cli.js
│   ├── cli.test.js
│   └── index.js
└── lib
    ├── index.js
    ├── xlsx-extractor.js
    ├── xlsx-extractor.test.js
    ├── xlsx-util.js
    └── xlsx-util.test.js

もともと Atom などテキスト エディター上でテストと対象コードを同時にタブ表示しても区別しやすくするため a.js のテストは a.test.js と命名していた。そのため併置によるファイル名の競合は発生しない。またきっかけとなった gist にも解説されているとおり

  • テストから対象への相対参照パスが短縮される
    • 併置されているため '../../src/lib/a.js'./a.js と書ける
    • ディレクトリ構造を変更してもテストと対象の併置を維持すればパス変更しなくて済む
  • テストと対象の距離が近い
    • これ以上ない近さ
    • 往復が容易なのでテストを書いたり内容を確認する負担が軽減される
  • テストの有無を視認しやすい
    • *.test.js の併置を確認すればよい
    • なければテストなしと判断できる

といったメリットがある。あらゆるコードが src 内に集約される。よってユニット テスト、ESLint、ESDoc もこのディレクトリだけを対象にすればよい。

{
  "esdoc": {
    "source": "./src",
    "destination": "./esdoc",
    "test": {
      "type": "mocha",
      "source": "./src"
    }
  },
  "scripts": {
    "test": "mocha --timeout 50000 --compilers js:babel-register src/**/*.test.js",
    "esdoc": "esdoc",
    "eslint": "eslint ./src"
  }
}

あと ESDoc で CommonJS をサポートするためには esdoc-node が必要だが ESDoc 公式 plugin ではないため ESDoc Hosting Service 上で動かせない。この点については作者の @h13i32maru さんと Twitter 上で相談して plugin の公式化を検討していただいている。しかし今回の対応で Babel 再導入を前提にコードを ES.next で書き直した。よって esdoc-node は不要となり、そのまま ESDoc Hosting Service を利用できる。

publish

Babel 再導入により npm を publish する際にビルドが必要となる。これは以前、prepublish で定義していたが npm v4 から deprecated になったので prepare を利用するように修正。

{
  "main": "dist/lib/xlsx-extractor.js",
  "bin": "dist/bin/index.js",
  "files": ["dist"],
  "scripts": {
    "build": "babel src --out-dir dist --ignore *.test.js,typedef.js",
    "prepare": "npm run build"
  }  
}

ビルド結果を dist にしているため、files の内容がスッキリした。

まとめ

対象 Node に応じたコード修正コストを babel-preset-env に丸投げできるのは便利だ。もっと早く知っていれば脱 Babel しなかったかもしれない。依然として変換品質の懸念はあるものの、自前で Node の Release note や ECMAScript 6 compatibility table を調べて対応するよりもはマシなはず。

他の npm も Babel 再導入とユニット テスト併置などを反映させてゆく予定。

併置といえば Web フロント エンド開発だと CSS Modules により View コンポーネントと CSS の関係も見直されている。これも面白い潮流だ。React の JSX において関心と技術の分離は異なるという話があった。ユニット テストや CSS も対象と密なら近接するのが自然である。

Transpiler や Bundler を前提とすることで JavaScript における動作環境や技術の分離に関する問題は解決されつつあり、より本質的な関心事にもとづいて設計できる時代になったと感じる。