unknownの説明の拡充、ビルドツール周りを更新

Author: shibukawa

baseenv.rst

@@ -38,8 +38,6 @@
 
   TypeScript対応の環境で、最小設定ですぐに使い始められるのはVisual Studio Codeです。しかも、必要な拡張機能をプロジェクトファイルで指定して、チーム内で統一した環境を用意しやすいので、推奨環境として最適です。EclipseなどのIDEの時代とは異なり、フォーマッターなどはコマンドラインでも使えるものを起動するケースが多いため、腕に覚えのある人はVimでもEmacsでもなんでも利用は可能です。
 
-.. todo:: lyntのTypeScript対応状況を注視する
-
 これらのツールを組み合わせて環境を作っていきます。昔のJavaScriptの開発環境は、ビルドツール（GruntやGulp）を使ってこれらのツールの組み合わせを手作業をで行う必要がありましたが、ツールが複雑になってプロジェクトのテンプレート化が進んだことや、TypeScriptの人気が上がるにつれてTypeScriptを考慮したツールが増えてきました。そのため、現在は比較的簡単に導入できます。
 
 ツールは日々改良されているため、どの目的に対してどのツールを利用するのがベストかは一概には言えませんが、比較的に広く使われていて、安定していて、かつ利便性が高い物はいくつかピックアップできます。次の表はその対応表になります。フォルダ作成は\ ``package.json``\ を含むプロジェクトのフォルダを作成することを意味します。
@@ -73,29 +71,41 @@
    - * React + SSR
      * `Next.js <https://nextjs.org/>`_
      * ○
-     * (オプション)
+     * (tsconfig.jsonを作成したら有効)
      * -
    - * Vue.js
      * `@vue/cli <https://cli.vuejs.org/>`_
      * ○
      * (オプション)
      * (オプション)
+   - * Nuxt.js
+     * `nuxi <https://v3.nuxtjs.org/getting-started/installation>`_
+     * ○
+     * ○
+     * (オプション)
    - * Angular
      * `@angular/cli <https://angular.io/>`_
      * ○
      * ○
      * ○
    - * ウェブ全般
-     * `Parcel <https://en.parceljs.org/>`_
+     * `Parcel <https://parceljs.org/>`_
      * -
      * ○
      * -
+   - * ウェブ全般
+     * `Vite.js <https://vaitejs.dev/>`_
+     * ○
+     * (オプション)
+     * -
 
 本章では、これらのツール間で共通となる情報を紹介します。
 
 作業フォルダの作成
 -------------------------
 
+この作業はツールによっては行ってくれるため不要です。
+
 出力先フォルダの作成はプロジェクト構成ごとに変わってくるため、入力側だけをここでは説明します。プロジェクトごとにフォルダを作成します。ウェブだろうがライブラリだろうが、 ``package.json`` が必要なツールのインストールなど、すべてに必要になるため、 ``npm init`` でファイルを作成します。ツールによってはこのフォルダの作成と\ ``package.json``\ の作成を勝手にやるものもあります。
 
 .. code-block:: bash
@@ -414,9 +424,19 @@ ESLintの警告はなるべく適用したいが、特別なコードだけ除
 
 ユニットテスト環境も作ります。TypeScriptを事前に全部ビルドしてからJasmineとかも見かけますが、公式でTypeScriptを説明しているJestにしてみます。
 
+Jest、Jestの型定義、TypeScriptを読み込めるようにするトランスレータの3つはセットで入れます。
+
+.. code-block:: bash
+
+   $ npm install jest @types/jest ts-jest --save-dev
+
+``jest --init``\ を起動するといくつか質問されて設定ファイルの雛形が生成されます。
+
 .. code-block:: bash
 
-   $ npm install --save-dev jest ts-jest @types/jest eslint-plugin-jest
+   $ npx jest --init
+
+``npm test``\ で実行できるようにするかの質問が最初にされるのでYを選択します。TypeScriptを\ **設定ファイルに**\ 使うかの質問はどちらでも良いです。こちらを選んでもTypeScriptを有効化する設定は必要です。Nodeかjs-domかは、純粋なロジックのテストがしたいか、ブラウザのテストをしたいか次第です。必要であれば後から足せます。あとはカバレッジ計測、モックのリセットを毎回行うかといった質問です。
 
 scripts/testと、jestの設定を追加します。古い資料だと、transformの値がnode_modules/ts-jest等になっているのがありますが、今はts-jestだけでいけます。
 
@@ -471,3 +491,40 @@ JestでもMochaでも、人気のフレームワークはテスト専用の関
 
 .. todo:: eslintやテストの書き方の紹介
 
+.. _change_import_path:
+
+プロジェクト内のファイルの参照方法を\ ``@/``\ にする
+-------------------------------------------------------------------
+
+プロジェクト内のファイルの\ ``import``\ では、現在のファイルから相対パスで書く方法と、\ ``tsconfig.json``\ の\ ``compilerOptions.baseDir``\ を起点とした絶対パスで書く方法がありました。
+
+それ以外に近年広く使われている記法が、プロジェクトのベースフォルダを\ ``@/``\ と表記する方法です。
+
+.. code-block:: ts
+
+   import { MyComponent } from "@/components/mycomponents";
+
+もし、すべてのコードが\ ``src``\ フォルダ以下にあるのであれば、次のように\ ``tsconfig.json``\ を変更します。もしプロジェクトにJavaScriptファイルものこっているのであれば、同一の内容を\ ``jsconfig.json``\ に書けば、Visual Studio Code、Next.js、Veterなどが解釈してくれますし、\ ``babel-plugin-module-resolver``\ を入れれば他のプロジェクトでもこの表記が可能です。
+
+.. code-block:: json
+   :caption: tsconfig.json
+
+   {
+     "compilerOptions": {
+       "baseUrl": ".",
+       "paths": {
+         "@/src/*": ["src/*"]
+       }
+     }
+   }
+
+Jestはこのファイルから情報を取得してくれませんので専用の設定が必要です。
+
+.. code-block:: json
+
+   {
+     "moduleNameMapper": {
+       "^@/(.*)$": "<rootDir>/src/$1"
+   }
+
+単なるエイリアスなので、この設定を入れなくてもできることは変わりませんが、特にテストコードからプロジェクトのファイルを参照したい場合など、\ ``import { Targert } from "../../../../src/components/Target";``\ のように\ ``import``\ が長くなる可能性があります。\ ``import``\ 文を他のファイルからコピーするときも、どのフォルダであってもそのまま使えるというメリットもあります。

browserenv.rst

@@ -29,6 +29,31 @@ JavaScriptでビルドといっても、いろいろなステップがありま
 
 webpackは細かくカスタマイズできますし、豊富な開発リソースで頻繁にリリースされています。ツリーシェイキングといった不要なコードを除外してサイズを小さくする機能にいち早く取り組んだり、業界をリードしています。困った時に検索すると情報も多く出てきます。一方で、TypeScript対応で開発サーバーやCSS対応など、機能を足していこうとすると設定やプラグインが増えていきます。特に、ReactのJSX構文を利用する場合は、バンドラーの処理の前段でTypeScriptをJavaScriptに変換したあとにBabelを使い、最後にバンドラーで1ファイルや複数ファイルにまとめるなど、ビルドのパイプラインが多段になりがちです。ReactやVueの環境構築ツールやNext.js、Nuxt.jsなどはwebpackを内包して、少ない設定の量で一定の機能を備えたビルド環境を整えてくれます。本書でも、webpackそのものを紹介することはしませんが、これらのツールの紹介をします。
 
-他にも数多くのバンドラーがあります。webpack以降に出てきたものの多くは設定が少ない、あるいは設定ファイルが不要（ゼロコンフィギュレーション）を売りにしたものが数多くあります。Rollupは人気のあるバンドラーで、TypeScriptを使うにはプラグインが必要ですが、そうでないのであれば設定がほとんど必要ありません。RollupをベースにTypeScriptサポートを最初から組み込んだmicrobundleもあります。HTMLやCSSのビルドもできて開発サーバーも全てついてくるオールインワンでビルド速度を重視したParcelや、Go製でビルド速度に特化したesbuildもあります。一方で、カスタマイズが必要なので最初からカスタマイズ前提でCLIを提供しないFuseboxなどもあります。
+他にも数多くのバンドラーがあります。webpack以降に出てきたものの多くは設定が少ない、あるいは設定ファイルが不要（ゼロコンフィギュレーション）を売りにしたものが数多くあります。Rollupは人気のあるバンドラーで、TypeScriptを使うにはプラグインが必要ですが、そうでないのであれば設定がほとんど必要ありません。
 
+Angular/Vue/Reactを使う場合は、それぞれの公式のツールも利用できます。AngularはTypeScript必須なので、TypeScriptしかサポートしていません。他の2つはオプションやテンプレートでTypeScript設定済みのプロジェクトが作成できます。Vue.jsとReactについては本書でも触れます。
 
+* Angularの\ `@angular/cli <https://angular.io/cli>`_
+* Reactの\ `create-react-app <https://create-react-app.dev/>`_
+* Vue.jsの\ `@vue/cli <https://cli.vuejs.org/>`_
+
+ReactとVue.js, Svelteにいろいろなコンポーネントを付与してオールインワンになった\ `Next.js <https://nextjs.org/docs>`_\ と\ `Nuxt.js <https://v3.nuxtjs.org/getting-started/installation>`_\ , \ `SvelteKit <https://kit.svelte.dev/docs>`_\ を使う場合はそれぞれ公式の初期化方法があり、必要なものが設定済みの環境が作られます。
+
+* Next.jsは\ `npx create-next-app`
+* Nuxt.jsは\ `npx nuxi init`
+* SvelteKitは\ `npm init svelte@next`
+
+webpackとRollup以外だと次のようなツールがあります。以下もすべてTypeScriptに対応しています。Parcelについては本書で解説しています。
+
+* RollupをベースにTypeScriptサポートを最初から組み込んだ\ `microbundle <https://www.npmjs.com/package/microbundle>`_
+* .js/.tsの変換に特化して高速なビルド応答性を重視し、本番環境のバンドル作成はプラグインを使ったオプション(webpack/Rollup)としている\ `Snowpack <https://www.snowpack.dev/>`_
+* HTMLやCSSのビルドもできて、package.jsonに書かれた定義(mainやtypesなど)をもとにビルドを行い、開発サーバーも全てついてくるオールインワンでビルド速度を重視した\ `Parcel V2<https://v2.parceljs.org/>`_
+* Go製でビルド速度に特化した\ `esbuild <https://esbuild.github.io/>`_
+* microbundleに似ているが、React/Vue.js/Svelte/Lit-Element/素のHTML+JS(Vanilla)向けの環境構築までやってくれる\ `vite.js <https://vitejs.dev/>`_
+
+どのツールを使っても、コードを書く側のタスクはあまり変わりません。まずはESLint, Prettier, Jestあたりの設定をきちんと独立して作りましょう。ツールはたくさんありますし、日々いろいろ登場しますが、ツールの完成度やレベルは上がっており、細かい設定を書かなくてもいい世界になっていってきています。基本の設定がしっかりしていれば、良さそうなツールがあれば自由に移行できます。
+
+ツールの選択は個人の好みもありますが、筆者の場合は2021年現在、次のように決めています。
+
+* Next.js, Nuxt.js, SvelteKit, Angular, Vue.jsはそれぞれ固有のツール
+* React単体、Svelte単体、その他はvite.js

docs/.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: c67336abd1a4f2919adb4ca58fa8e25d
+config: 65f1bc4d6239bd5f9e4ded52b2175125
 tags: 645f666f9bcd5a90fca523b33c5a78b7

docs/_sources/baseenv.rst.txt

@@ -38,8 +38,6 @@
 
   TypeScript対応の環境で、最小設定ですぐに使い始められるのはVisual Studio Codeです。しかも、必要な拡張機能をプロジェクトファイルで指定して、チーム内で統一した環境を用意しやすいので、推奨環境として最適です。EclipseなどのIDEの時代とは異なり、フォーマッターなどはコマンドラインでも使えるものを起動するケースが多いため、腕に覚えのある人はVimでもEmacsでもなんでも利用は可能です。
 
-.. todo:: lyntのTypeScript対応状況を注視する
-
 これらのツールを組み合わせて環境を作っていきます。昔のJavaScriptの開発環境は、ビルドツール（GruntやGulp）を使ってこれらのツールの組み合わせを手作業をで行う必要がありましたが、ツールが複雑になってプロジェクトのテンプレート化が進んだことや、TypeScriptの人気が上がるにつれてTypeScriptを考慮したツールが増えてきました。そのため、現在は比較的簡単に導入できます。
 
 ツールは日々改良されているため、どの目的に対してどのツールを利用するのがベストかは一概には言えませんが、比較的に広く使われていて、安定していて、かつ利便性が高い物はいくつかピックアップできます。次の表はその対応表になります。フォルダ作成は\ ``package.json``\ を含むプロジェクトのフォルダを作成することを意味します。
@@ -73,29 +71,41 @@
    - * React + SSR
      * `Next.js <https://nextjs.org/>`_
      * ○
-     * (オプション)
+     * (tsconfig.jsonを作成したら有効)
      * -
    - * Vue.js
      * `@vue/cli <https://cli.vuejs.org/>`_
      * ○
      * (オプション)
      * (オプション)
+   - * Nuxt.js
+     * `nuxi <https://v3.nuxtjs.org/getting-started/installation>`_
+     * ○
+     * ○
+     * (オプション)
    - * Angular
      * `@angular/cli <https://angular.io/>`_
      * ○
      * ○
      * ○
    - * ウェブ全般
-     * `Parcel <https://en.parceljs.org/>`_
+     * `Parcel <https://parceljs.org/>`_
      * -
      * ○
      * -
+   - * ウェブ全般
+     * `Vite.js <https://vaitejs.dev/>`_
+     * ○
+     * (オプション)
+     * -
 
 本章では、これらのツール間で共通となる情報を紹介します。
 
 作業フォルダの作成
 -------------------------
 
+この作業はツールによっては行ってくれるため不要です。
+
 出力先フォルダの作成はプロジェクト構成ごとに変わってくるため、入力側だけをここでは説明します。プロジェクトごとにフォルダを作成します。ウェブだろうがライブラリだろうが、 ``package.json`` が必要なツールのインストールなど、すべてに必要になるため、 ``npm init`` でファイルを作成します。ツールによってはこのフォルダの作成と\ ``package.json``\ の作成を勝手にやるものもあります。
 
 .. code-block:: bash
@@ -414,9 +424,19 @@ ESLintの警告はなるべく適用したいが、特別なコードだけ除
 
 ユニットテスト環境も作ります。TypeScriptを事前に全部ビルドしてからJasmineとかも見かけますが、公式でTypeScriptを説明しているJestにしてみます。
 
+Jest、Jestの型定義、TypeScriptを読み込めるようにするトランスレータの3つはセットで入れます。
+
+.. code-block:: bash
+
+   $ npm install jest @types/jest ts-jest --save-dev
+
+``jest --init``\ を起動するといくつか質問されて設定ファイルの雛形が生成されます。
+
 .. code-block:: bash
 
-   $ npm install --save-dev jest ts-jest @types/jest eslint-plugin-jest
+   $ npx jest --init
+
+``npm test``\ で実行できるようにするかの質問が最初にされるのでYを選択します。TypeScriptを\ **設定ファイルに**\ 使うかの質問はどちらでも良いです。こちらを選んでもTypeScriptを有効化する設定は必要です。Nodeかjs-domかは、純粋なロジックのテストがしたいか、ブラウザのテストをしたいか次第です。必要であれば後から足せます。あとはカバレッジ計測、モックのリセットを毎回行うかといった質問です。
 
 scripts/testと、jestの設定を追加します。古い資料だと、transformの値がnode_modules/ts-jest等になっているのがありますが、今はts-jestだけでいけます。
 
@@ -471,3 +491,40 @@ JestでもMochaでも、人気のフレームワークはテスト専用の関
 
 .. todo:: eslintやテストの書き方の紹介
 
+.. _change_import_path:
+
+プロジェクト内のファイルの参照方法を\ ``@/``\ にする
+-------------------------------------------------------------------
+
+プロジェクト内のファイルの\ ``import``\ では、現在のファイルから相対パスで書く方法と、\ ``tsconfig.json``\ の\ ``compilerOptions.baseDir``\ を起点とした絶対パスで書く方法がありました。
+
+それ以外に近年広く使われている記法が、プロジェクトのベースフォルダを\ ``@/``\ と表記する方法です。
+
+.. code-block:: ts
+
+   import { MyComponent } from "@/components/mycomponents";
+
+もし、すべてのコードが\ ``src``\ フォルダ以下にあるのであれば、次のように\ ``tsconfig.json``\ を変更します。もしプロジェクトにJavaScriptファイルものこっているのであれば、同一の内容を\ ``jsconfig.json``\ に書けば、Visual Studio Code、Next.js、Veterなどが解釈してくれますし、\ ``babel-plugin-module-resolver``\ を入れれば他のプロジェクトでもこの表記が可能です。
+
+.. code-block:: json
+   :caption: tsconfig.json
+
+   {
+     "compilerOptions": {
+       "baseUrl": ".",
+       "paths": {
+         "@/src/*": ["src/*"]
+       }
+     }
+   }
+
+Jestはこのファイルから情報を取得してくれませんので専用の設定が必要です。
+
+.. code-block:: json
+
+   {
+     "moduleNameMapper": {
+       "^@/(.*)$": "<rootDir>/src/$1"
+   }
+
+単なるエイリアスなので、この設定を入れなくてもできることは変わりませんが、特にテストコードからプロジェクトのファイルを参照したい場合など、\ ``import { Targert } from "../../../../src/components/Target";``\ のように\ ``import``\ が長くなる可能性があります。\ ``import``\ 文を他のファイルからコピーするときも、どのフォルダであってもそのまま使えるというメリットもあります。