前書きとかその周辺修正

Author: shibukawa

.gitignore

@@ -4,3 +4,4 @@ node_modules
 docs/.doctrees
 _build/latex
 .DS_Store
+node_modules

baseenv.rst

@@ -6,17 +6,15 @@
 プロジェクトでのコーディングであれば、誰が書いても同じスタイルになるなど、コード品質の統一が大切になりますので、単なる個人用の設定ではなく、それをシェアできるというのも目的として説明していきます。
 ここでは、基本的にすべてのプロジェクトでJest、ESLint、Prettierなどを選択しています。まあ、どれも相性問題が出にくい、数年前から安定して存在している、公式で推奨といった保守的な理由ですね。きちんと選べば、「JSはいつも変わっている」とは距離を置くことができます。
 
-.. todo::
-
-   ESLintのTypeScript対応はまだまだ開発途上で厳しそうなのでTSLintに書き戻す？
-
 * Jest
 
   テスティングフレームワークはたくさんありますが、avaとJestがテスト並列実行などで抜きん出ています。JestはTypeScript用のアダプタが完備されています。avaはBabel/webpackに強く依存しており、単体で使うなら快適ですが、他のBabel Configと相性が厳しくなるのでJestにしています。
 
 * ESLint
 
-  公式が押しているのでこれですね。
+  公式が押しているのでこれですね。かつてはTSLintというツールがデファクトスタンダードでしたが、最適化の限界があることなどを理由に、TypeScriptが公式にESLintをメインのLinterとすることが宣言されました。よほどの理由がないかぎりはESLintを使うべきです。
+
+  ESLintはプラグインを使うことでさまざまなルールを足せますし、プラグインを通じて設定を一括で変更できます。これはツール同士の干渉を避けるためだったり、推奨のルールセットを配布する手段として利用されています。
 
   * @typescript-eslint/eslint-plugin
 
@@ -211,4 +209,7 @@ Visual Stuido Codeでフォルダを開いたときに、eslintの拡張と、ed
      "files.autoSave": "off"
    }
 
-.. todo:: tsdocとかドキュメントツールを紹介
+.. todo:: tsdocとかドキュメントツールを紹介
+
+.. todo:: eslintやテストの書き方の紹介
+

clienv.rst

@@ -1,23 +1,36 @@
-CLIツール作成のための環境設定
-=========================================
+===============================================
+CLIツール・ウェブサーバー作成のための環境設定
+===============================================
 
-TypeScriptを使ってNode.jsのためのCLIツールを作成するための環境構築方法を紹介していきます。
+TypeScriptを使ってCLIツールやウェブサーバーなどのNode.jsやDenoがある環境で動作するソフトウェアを作成するための環境構築方法を紹介していきます。2つ方法があります。
 
-作業フォルダを作る
-------------------------
+* Node.jsがインストールされている環境向け
+* Denoががインストールされている環境向け
 
-ライブラリの時は、ES2015 modulesとCommonJSの2通り準備しましたが、CLIの場合はNode.jsだけ動かせば良いので、出力先もCommonJSだけで十分です。
+どちらも、TypeScriptをJavaScript変換して1ファイルにまとめたファイルを作成します。
 
-.. code-block:: bash
+Node.jsの環境構築
+===============================
+
+Node.js向けには@zeit/nccを利用します。
+
+@zeit/nccはTypeScriptに最初から対応したコンパイラで、コマンドラインツールやウェブサーバーなどのNode.jsアプリケーションを1ファイルにするために作られています。@zeit/ncc自体も自分自身を使ってバンドル化されており、ごく小さいサイズですばやくインストールできます。Goを参考にしており、\ ``tsconfig.json``\ 以外の設定は不要です。もちろん、
+
+他に実績のあるツールとしてはBrowserifyがあります。これも、tsifyというプラグインと併用することでTypeScript製アプリケーションをバンドルして1ファイルにできます。このツールはメインの目的としてはNode.js製アプリケーションをブラウザでも動くようにするために作られました。後発の@zeit/nccに比べると設定が多いのと、TypeScriptの設定を変えてcommon.js形式のパッケージにしないと扱えないのがnccと比べると煩雑です。また、\ ``tsc``\ を使いバンドルせずにTypeScriptをJavaScriptに変換するだけを行って配布する方法もありますが、バンドルをしないとさまざまなファイルが入ってくるため、配布サイズも大きくなりがちです。
+
+作業フォルダを作る
+------------------------
 
-   $ mkdir dist   # commonJSだけなので1つだけ
+フォルダを作成し、JavaScriptのいつものプロジェクトのように\ ``npm init -y``\ を実行して\ ``package.json``\ を作成しましょう。
 
- ``.gitignore`` も、出力先フォルダを1つだけに修正しましょう。
+ライブラリの時は、ES2015 modulesとCommonJSの2通り準備しましたが、CLIの場合はNode.jsだけ動かせば良いので、出力先は一つになります。コンパイルしたファイル置き場は\ ``dist``\ フォルダになりますが、コンパイル時に自動で作られるので作成しておく必要はありませんが、\ ``.gitignore``\ には登録しておきましょう。
 
 ビルド設定
 ---------------------------
 
-Node.jsの機能を使うことになるため、Node.jsのAPIの型定義ファイルは入れておきましょう。
+まずは@zeit/nccをインストールします。
+
+Node.jsの機能を使うことになるため、Node.jsのAPIの型定義ファイルは入れておきましょう。TypeScriptはnccにバンドルされていますが、バンドルされている処理系のバージョンが古いことがあります。インストールしてあるTypeScriptを優先的に使ってくれるので入れておくと良いでしょう。
 
 コマンドラインで良く使うであろうライブラリを追加しておきます。
 カラーでのコンソール出力、コマンドライン引数のパーサ、ヘルプメッセージ表示です。
@@ -27,12 +40,15 @@ Node.jsの機能を使うことになるため、Node.jsのAPIの型定義ファ
 
 .. code-block:: bash
 
-   $ npm install --save cli-color command-line-args
-      command-line-usage source-map-support
+   $ npm install --save-dev @zeit/ncc typescript
+
    $ npm install --save-dev @types/node @types/cli-color
       @types/command-line-args @types/command-line-usage
       @types/source-map-support
 
+   $ npm install --save cli-color command-line-args
+      command-line-usage source-map-support
+
 TypeScriptのビルド設定のポイントは、ブラウザからは使わないので、ターゲットのバージョンを高くできる点にあります。
 ローカルでは安定版を使ったとしてもNode.js 10が使えるでしょう。
 
@@ -73,13 +89,48 @@ TypeScriptのビルド設定のポイントは、ブラウザからは使わな
        "awesome-cmd": "dist/index.js"
      },
      "scripts": {
-       "build": "tsc --project .",
+       "build": "ncc build main.ts --minify --v8-cache --source-map",
+       ”watch": "ncc build main.ts --watch",
+       "start": "ncc run main.ts",
        "lint": "eslint .",
        "fix": "eslint --fix ."
      }
    }
 
-テストの設定、VSCodeの設定は変わりません。
+``ncc build``\ でビルドします。\ ``ncc run``\ でビルドして即座に実行します。設定ファイルはありません。必要十分な機能が揃っています。オプションで指定できるものは以下の通りです。
+
+* ``--minify``: ミニファイしてファイルを小さくする
+* ``--source-map``: ソースマップを出力
+* ``-e, --external [mod]``: バンドルをスキップするモジュール
+* ``--watch``: 変更を検知してビルド
+* ``--v8-cache``: V8のコンパイルキャッシュを生成
+
+テストの設定、VSCodeの設定は他の環境の設定と変わりません。
+
+もし、バイナリを入れる必要のあるライブラリがあると、ビルド時にエラーになります。その場合は、そのパッケージを ``--external パッケージ名`` で指定してバンドルされないようにします。
+ただし、この場合は配布環境でこのライブラリだけはnpm installしなければなりません。
+
+.. note::
+
+   **Node.js/Deno以外の処理系**
+
+   また、low.js [#]_ という、ES5しか動かないもののNode.jsと一部互換性があるモジュールを提供し、ファイルサイズがごく小さいインタプリタがありますが、これと一緒に使うこともできます。
+
+   low.jsはES5までしか対応しないため、出力ターゲットをES5にする必要があります。
+
+   .. code-block:: json
+      :caption: tsconfig.json (low.jsを使う場合)
+
+      {
+        "compilerOptions": {
+          "target": "es5",             // もしlow.jsを使うなら
+          "lib": ["dom", "es2017"]     // もしlow.jsで新しいクラスなどを使うなら
+        }
+      }
+
+   これで、TypeScript製かつ、必要なライブラリが全部バンドルされたシングルファイルなスクリプトができあがります。
+
+.. [#] https://www.lowjs.org/
 
 CLIツールのソースコード
 -----------------------------------
@@ -106,59 +157,9 @@ TypeScriptはシェバング(#!)があると特別扱いしてくれます。
 
    main();
 
-バンドラーで1つにまとめる
--------------------------------
-
-npmで配るだけであればバンドルは不要ですが、ちょっとしたスクリプトをTypeScriptで書いてDockerサーバーで実行したいが、コンテナを小さくしたいのでnode_modulesは入れたくないということは今後増えていくと思いますので、そちらの方法も紹介します。
-また、low.js [#]_ という、ES5しか動かないもののNode.jsと一部互換性があるモジュールを提供し、ファイルサイズがごく小さいインタプリタがありますが、これと一緒に使うこともできます。
-
-バンドラーでは一番使われているのは間違いなくwebpackですが、昔ながらのBrowserifyは設定ファイルレスで、ちょっとした小物のビルドには便利です。BrowserifyはNode.jsのCommonJS形式のコードをバンドルしつつ、Node.js固有のパッケージは互換ライブラリを代わりに利用するようにして、Node.jsのコードをそのままブラウザで使えるようにするものです。オプションでNode.jsの互換ライブラリを使わないようにもできます。
 
-webpackでもちょっと設定ファイルを書けばいけるはずですが、TypeScript対応以外に、shebang対応とかは別のプラグインが必要だったり、ちょっと手間はかかります。
-
-Browserifyをインストールします。tsifyはBrowserifyプラグインで、TypeScriptのコードを変換します。
-バンドルしてしまうので、バイナリのインストールが必要なパッケージ以外の各種ライブラリはすべて--save-devで入れても大丈夫です。
-
-.. code-block:: bash
-
-   $ npm install --save-dev browserify tsify
-
-``tsconfig.json`` に関してはそのままで問題ありません。この手のバンドラーから使われる時は、.tsと.jsの1:1変換ではなくて、複数の.tsをメモリ上で.jsに変換し、そのあとにまとめて1ファイルにするn:1変換になります。そのため、個別の変換ファイルを出力しないnoEmit: trueをつけたりdistDirを消したりする必要がありますが、そのあたりはtsifyが勝手にやってくれます。
-
-ただし、ES5しか動作しないlow.jsを使う場合は、出力ターゲットをES5にする必要があります。
-
-.. code-block:: json
-   :caption: tsconfig.json (low.jsを使う場合)
-
-   {
-     "compilerOptions": {
-       "target": "es5",             // もしlow.jsを使うなら
-       "lib": ["dom", "es2017"]     // もしlow.jsで新しいクラスなどを使うなら
-     }
-   }
-
-ビルドスクリプトは次の形式になります。
-``--node`` をつけないと、ブラウザ用のコードを生成しますが、ファイル入出力などが使えなくなりますので、CLIでは ``--node`` を忘れずにつけます。
-TypeScript変換のために、 ``-p`` で ``tsify`` を追加しています。
-もしminifyとかしたくなったら、minifyifyなどの別のプラグインを利用します。
-
-.. code-block:: json
-
-   {
-     "scripts": {
-       "build": "browserify --node -o dist/script.js -p [ tsify -p . ] src/index.ts"
-     }
-   }
-
-もし、バイナリを入れる必要のあるライブラリがあると、Browserifyがエラーになります。その場合は、そのパッケージを ``--exclude パッケージ名`` で指定してバンドルされないようにします。
-ただし、この場合は配布環境でこのライブラリだけはnpm installしなければなりません。
-
-これで、TypeScript製かつ、必要なライブラリが全部バンドルされたシングルファイルなスクリプトができあがります。
-
-.. [#] https://www.lowjs.org/
-
-まとめ
---------------
+Node.jsのまとめ
+-------------------
 
 コマンドラインツールの場合は、npmで配布する場合はライブラリ同様、バンドラーを使わずに、TypeScriptだけを使えば大丈夫です。
 ここにある設定で、次のようなことが達成できました。
@@ -173,6 +174,9 @@ npmコマンドを使って行うことができます。すべてライブラ
 
 .. code-block:: bash
 
+   # ビルドして実行
+   $ npm start
+
    # ビルドしてパッケージを作成
    $ npm run build
    $ npm pack
@@ -186,3 +190,12 @@ npmコマンドを使って行うことができます。すべてライブラ
    # フォーマッター実行
    $ npm run fix
 
+Deno
+============
+
+Denoは新しい処理系です。Node.jsと同じくV8をベースとしている兄弟処理系ですが、TypeScriptにデフォルトで対応していたり、ネイティブコード部分はRustを使って実装されています。
+サードパーティのパッケージはnpmコマンドではなくdenoコマンドを使ってダウンロードします。
+
+Node.jsを置き換えるものかというと、現時点ではまだパッケージやツールが足りていません。特にNode.jsのnpmはウェブフロントエンドのライブラリなどの配布にも使われており、ウェブフロントエンドの開発のためのプラットフォームとしても活用されています。Denoはコマンドラインツールやウェブサービスの開発に特化しています。
+
+こちらもGoを参考にしたコマンドを持っています。それ単体でビルドして配布できます。