Skip to content

Commit 14090b3

Browse files
shibukawashibukawa
committed
unknownの説明の拡充、ビルドツール周りを更新
1 parent 7d03993 commit 14090b3

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

56 files changed

+3545
-7199
lines changed

‎baseenv.rst

+62-5
Original file line numberDiff line numberDiff line change
@@ -38,8 +38,6 @@
3838

3939
TypeScript対応の環境で、最小設定ですぐに使い始められるのはVisual Studio Codeです。しかも、必要な拡張機能をプロジェクトファイルで指定して、チーム内で統一した環境を用意しやすいので、推奨環境として最適です。EclipseなどのIDEの時代とは異なり、フォーマッターなどはコマンドラインでも使えるものを起動するケースが多いため、腕に覚えのある人はVimでもEmacsでもなんでも利用は可能です。
4040

41-
.. todo:: lyntのTypeScript対応状況を注視する
42-
4341
これらのツールを組み合わせて環境を作っていきます。昔のJavaScriptの開発環境は、ビルドツール（GruntやGulp）を使ってこれらのツールの組み合わせを手作業をで行う必要がありましたが、ツールが複雑になってプロジェクトのテンプレート化が進んだことや、TypeScriptの人気が上がるにつれてTypeScriptを考慮したツールが増えてきました。そのため、現在は比較的簡単に導入できます。
4442

4543
ツールは日々改良されているため、どの目的に対してどのツールを利用するのがベストかは一概には言えませんが、比較的に広く使われていて、安定していて、かつ利便性が高い物はいくつかピックアップできます。次の表はその対応表になります。フォルダ作成は\ ``package.json``\ を含むプロジェクトのフォルダを作成することを意味します。
@@ -73,29 +71,41 @@
7371
- * React + SSR
7472
* `Next.js <https://nextjs.org/>`_
7573
* ○
76-
* (オプション)
74+
* (tsconfig.jsonを作成したら有効)
7775
* -
7876
- * Vue.js
7977
* `@vue/cli <https://cli.vuejs.org/>`_
8078
* ○
8179
* (オプション)
8280
* (オプション)
81+
- * Nuxt.js
82+
* `nuxi <https://v3.nuxtjs.org/getting-started/installation>`_
83+
* ○
84+
* ○
85+
* (オプション)
8386
- * Angular
8487
* `@angular/cli <https://angular.io/>`_
8588
* ○
8689
* ○
8790
* ○
8891
- * ウェブ全般
89-
* `Parcel <https://en.parceljs.org/>`_
92+
* `Parcel <https://parceljs.org/>`_
9093
* -
9194
* ○
9295
* -
96+
- * ウェブ全般
97+
* `Vite.js <https://vaitejs.dev/>`_
98+
* ○
99+
* (オプション)
100+
* -
93101

94102
本章では、これらのツール間で共通となる情報を紹介します。
95103

96104
作業フォルダの作成
97105
-------------------------
98106

107+
この作業はツールによっては行ってくれるため不要です。
108+
99109
出力先フォルダの作成はプロジェクト構成ごとに変わってくるため、入力側だけをここでは説明します。プロジェクトごとにフォルダを作成します。ウェブだろうがライブラリだろうが、 ``package.json`` が必要なツールのインストールなど、すべてに必要になるため、 ``npm init`` でファイルを作成します。ツールによってはこのフォルダの作成と\ ``package.json``\ の作成を勝手にやるものもあります。
100110

101111
.. code-block:: bash
@@ -414,9 +424,19 @@ ESLintの警告はなるべく適用したいが、特別なコードだけ除
414424

415425
ユニットテスト環境も作ります。TypeScriptを事前に全部ビルドしてからJasmineとかも見かけますが、公式でTypeScriptを説明しているJestにしてみます。
416426

427+
Jest、Jestの型定義、TypeScriptを読み込めるようにするトランスレータの3つはセットで入れます。
428+
429+
.. code-block:: bash
430+
431+
$ npm install jest @types/jest ts-jest --save-dev
432+
433+
``jest --init``\ を起動するといくつか質問されて設定ファイルの雛形が生成されます。
434+
417435
.. code-block:: bash
418436
419-
$ npm install --save-dev jest ts-jest @types/jest eslint-plugin-jest
437+
$ npx jest --init
438+
439+
``npm test``\ で実行できるようにするかの質問が最初にされるのでYを選択します。TypeScriptを\ **設定ファイルに**\ 使うかの質問はどちらでも良いです。こちらを選んでもTypeScriptを有効化する設定は必要です。Nodeかjs-domかは、純粋なロジックのテストがしたいか、ブラウザのテストをしたいか次第です。必要であれば後から足せます。あとはカバレッジ計測、モックのリセットを毎回行うかといった質問です。
420440

421441
scripts/testと、jestの設定を追加します。古い資料だと、transformの値がnode_modules/ts-jest等になっているのがありますが、今はts-jestだけでいけます。
422442

@@ -471,3 +491,40 @@ JestでもMochaでも、人気のフレームワークはテスト専用の関
471491

472492
.. todo:: eslintやテストの書き方の紹介
473493

494+
.. _change_import_path:
495+
496+
プロジェクト内のファイルの参照方法を\ ``@/``\ にする
497+
-------------------------------------------------------------------
498+
499+
プロジェクト内のファイルの\ ``import``\ では、現在のファイルから相対パスで書く方法と、\ ``tsconfig.json``\ の\ ``compilerOptions.baseDir``\ を起点とした絶対パスで書く方法がありました。
500+
501+
それ以外に近年広く使われている記法が、プロジェクトのベースフォルダを\ ``@/``\ と表記する方法です。
502+
503+
.. code-block:: ts
504+
505+
import { MyComponent } from "@/components/mycomponents";
506+
507+
もし、すべてのコードが\ ``src``\ フォルダ以下にあるのであれば、次のように\ ``tsconfig.json``\ を変更します。もしプロジェクトにJavaScriptファイルものこっているのであれば、同一の内容を\ ``jsconfig.json``\ に書けば、Visual Studio Code、Next.js、Veterなどが解釈してくれますし、\ ``babel-plugin-module-resolver``\ を入れれば他のプロジェクトでもこの表記が可能です。
508+
509+
.. code-block:: json
510+
:caption: tsconfig.json
511+
512+
{
513+
"compilerOptions": {
514+
"baseUrl": ".",
515+
"paths": {
516+
"@/src/*": ["src/*"]
517+
}
518+
}
519+
}
520+
521+
Jestはこのファイルから情報を取得してくれませんので専用の設定が必要です。
522+
523+
.. code-block:: json
524+
525+
{
526+
"moduleNameMapper": {
527+
"^@/(.*)$": "<rootDir>/src/$1"
528+
}
529+
530+
単なるエイリアスなので、この設定を入れなくてもできることは変わりませんが、特にテストコードからプロジェクトのファイルを参照したい場合など、\ ``import { Targert } from "../../../../src/components/Target";``\ のように\ ``import``\ が長くなる可能性があります。\ ``import``\ 文を他のファイルからコピーするときも、どのフォルダであってもそのまま使えるというメリットもあります。

‎browserenv.rst

+26-1
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,31 @@ JavaScriptでビルドといっても、いろいろなステップがありま
2929

3030
webpackは細かくカスタマイズできますし、豊富な開発リソースで頻繁にリリースされています。ツリーシェイキングといった不要なコードを除外してサイズを小さくする機能にいち早く取り組んだり、業界をリードしています。困った時に検索すると情報も多く出てきます。一方で、TypeScript対応で開発サーバーやCSS対応など、機能を足していこうとすると設定やプラグインが増えていきます。特に、ReactのJSX構文を利用する場合は、バンドラーの処理の前段でTypeScriptをJavaScriptに変換したあとにBabelを使い、最後にバンドラーで1ファイルや複数ファイルにまとめるなど、ビルドのパイプラインが多段になりがちです。ReactやVueの環境構築ツールやNext.js、Nuxt.jsなどはwebpackを内包して、少ない設定の量で一定の機能を備えたビルド環境を整えてくれます。本書でも、webpackそのものを紹介することはしませんが、これらのツールの紹介をします。
3131

32-
他にも数多くのバンドラーがあります。webpack以降に出てきたものの多くは設定が少ない、あるいは設定ファイルが不要（ゼロコンフィギュレーション）を売りにしたものが数多くあります。Rollupは人気のあるバンドラーで、TypeScriptを使うにはプラグインが必要ですが、そうでないのであれば設定がほとんど必要ありません。RollupをベースにTypeScriptサポートを最初から組み込んだmicrobundleもあります。HTMLやCSSのビルドもできて開発サーバーも全てついてくるオールインワンでビルド速度を重視したParcelや、Go製でビルド速度に特化したesbuildもあります。一方で、カスタマイズが必要なので最初からカスタマイズ前提でCLIを提供しないFuseboxなどもあります。
32+
他にも数多くのバンドラーがあります。webpack以降に出てきたものの多くは設定が少ない、あるいは設定ファイルが不要（ゼロコンフィギュレーション）を売りにしたものが数多くあります。Rollupは人気のあるバンドラーで、TypeScriptを使うにはプラグインが必要ですが、そうでないのであれば設定がほとんど必要ありません。
3333

34+
Angular/Vue/Reactを使う場合は、それぞれの公式のツールも利用できます。AngularはTypeScript必須なので、TypeScriptしかサポートしていません。他の2つはオプションやテンプレートでTypeScript設定済みのプロジェクトが作成できます。Vue.jsとReactについては本書でも触れます。
3435

36+
* Angularの\ `@angular/cli <https://angular.io/cli>`_
37+
* Reactの\ `create-react-app <https://create-react-app.dev/>`_
38+
* Vue.jsの\ `@vue/cli <https://cli.vuejs.org/>`_
39+
40+
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>`_\ を使う場合はそれぞれ公式の初期化方法があり、必要なものが設定済みの環境が作られます。
41+
42+
* Next.jsは\ `npx create-next-app`
43+
* Nuxt.jsは\ `npx nuxi init`
44+
* SvelteKitは\ `npm init svelte@next`
45+
46+
webpackとRollup以外だと次のようなツールがあります。以下もすべてTypeScriptに対応しています。Parcelについては本書で解説しています。
47+
48+
* RollupをベースにTypeScriptサポートを最初から組み込んだ\ `microbundle <https://www.npmjs.com/package/microbundle>`_
49+
* .js/.tsの変換に特化して高速なビルド応答性を重視し、本番環境のバンドル作成はプラグインを使ったオプション(webpack/Rollup)としている\ `Snowpack <https://www.snowpack.dev/>`_
50+
* HTMLやCSSのビルドもできて、package.jsonに書かれた定義(mainやtypesなど)をもとにビルドを行い、開発サーバーも全てついてくるオールインワンでビルド速度を重視した\ `Parcel V2<https://v2.parceljs.org/>`_
51+
* Go製でビルド速度に特化した\ `esbuild <https://esbuild.github.io/>`_
52+
* microbundleに似ているが、React/Vue.js/Svelte/Lit-Element/素のHTML+JS(Vanilla)向けの環境構築までやってくれる\ `vite.js <https://vitejs.dev/>`_
53+
54+
どのツールを使っても、コードを書く側のタスクはあまり変わりません。まずはESLint, Prettier, Jestあたりの設定をきちんと独立して作りましょう。ツールはたくさんありますし、日々いろいろ登場しますが、ツールの完成度やレベルは上がっており、細かい設定を書かなくてもいい世界になっていってきています。基本の設定がしっかりしていれば、良さそうなツールがあれば自由に移行できます。
55+
56+
ツールの選択は個人の好みもありますが、筆者の場合は2021年現在、次のように決めています。
57+
58+
* Next.js, Nuxt.js, SvelteKit, Angular, Vue.jsはそれぞれ固有のツール
59+
* React単体、Svelte単体、その他はvite.js

‎docs/.buildinfo

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

‎docs/_sources/baseenv.rst.txt

+62-5
Original file line numberDiff line numberDiff line change
@@ -38,8 +38,6 @@
3838

3939
TypeScript対応の環境で、最小設定ですぐに使い始められるのはVisual Studio Codeです。しかも、必要な拡張機能をプロジェクトファイルで指定して、チーム内で統一した環境を用意しやすいので、推奨環境として最適です。EclipseなどのIDEの時代とは異なり、フォーマッターなどはコマンドラインでも使えるものを起動するケースが多いため、腕に覚えのある人はVimでもEmacsでもなんでも利用は可能です。
4040

41-
.. todo:: lyntのTypeScript対応状況を注視する
42-
4341
これらのツールを組み合わせて環境を作っていきます。昔のJavaScriptの開発環境は、ビルドツール（GruntやGulp）を使ってこれらのツールの組み合わせを手作業をで行う必要がありましたが、ツールが複雑になってプロジェクトのテンプレート化が進んだことや、TypeScriptの人気が上がるにつれてTypeScriptを考慮したツールが増えてきました。そのため、現在は比較的簡単に導入できます。
4442

4543
ツールは日々改良されているため、どの目的に対してどのツールを利用するのがベストかは一概には言えませんが、比較的に広く使われていて、安定していて、かつ利便性が高い物はいくつかピックアップできます。次の表はその対応表になります。フォルダ作成は\ ``package.json``\ を含むプロジェクトのフォルダを作成することを意味します。
@@ -73,29 +71,41 @@
7371
- * React + SSR
7472
* `Next.js <https://nextjs.org/>`_
7573
* ○
76-
* (オプション)
74+
* (tsconfig.jsonを作成したら有効)
7775
* -
7876
- * Vue.js
7977
* `@vue/cli <https://cli.vuejs.org/>`_
8078
* ○
8179
* (オプション)
8280
* (オプション)
81+
- * Nuxt.js
82+
* `nuxi <https://v3.nuxtjs.org/getting-started/installation>`_
83+
* ○
84+
* ○
85+
* (オプション)
8386
- * Angular
8487
* `@angular/cli <https://angular.io/>`_
8588
* ○
8689
* ○
8790
* ○
8891
- * ウェブ全般
89-
* `Parcel <https://en.parceljs.org/>`_
92+
* `Parcel <https://parceljs.org/>`_
9093
* -
9194
* ○
9295
* -
96+
- * ウェブ全般
97+
* `Vite.js <https://vaitejs.dev/>`_
98+
* ○
99+
* (オプション)
100+
* -
93101

94102
本章では、これらのツール間で共通となる情報を紹介します。
95103

96104
作業フォルダの作成
97105
-------------------------
98106

107+
この作業はツールによっては行ってくれるため不要です。
108+
99109
出力先フォルダの作成はプロジェクト構成ごとに変わってくるため、入力側だけをここでは説明します。プロジェクトごとにフォルダを作成します。ウェブだろうがライブラリだろうが、 ``package.json`` が必要なツールのインストールなど、すべてに必要になるため、 ``npm init`` でファイルを作成します。ツールによってはこのフォルダの作成と\ ``package.json``\ の作成を勝手にやるものもあります。
100110

101111
.. code-block:: bash
@@ -414,9 +424,19 @@ ESLintの警告はなるべく適用したいが、特別なコードだけ除
414424

415425
ユニットテスト環境も作ります。TypeScriptを事前に全部ビルドしてからJasmineとかも見かけますが、公式でTypeScriptを説明しているJestにしてみます。
416426

427+
Jest、Jestの型定義、TypeScriptを読み込めるようにするトランスレータの3つはセットで入れます。
428+
429+
.. code-block:: bash
430+
431+
$ npm install jest @types/jest ts-jest --save-dev
432+
433+
``jest --init``\ を起動するといくつか質問されて設定ファイルの雛形が生成されます。
434+
417435
.. code-block:: bash
418436
419-
$ npm install --save-dev jest ts-jest @types/jest eslint-plugin-jest
437+
$ npx jest --init
438+
439+
``npm test``\ で実行できるようにするかの質問が最初にされるのでYを選択します。TypeScriptを\ **設定ファイルに**\ 使うかの質問はどちらでも良いです。こちらを選んでもTypeScriptを有効化する設定は必要です。Nodeかjs-domかは、純粋なロジックのテストがしたいか、ブラウザのテストをしたいか次第です。必要であれば後から足せます。あとはカバレッジ計測、モックのリセットを毎回行うかといった質問です。
420440

421441
scripts/testと、jestの設定を追加します。古い資料だと、transformの値がnode_modules/ts-jest等になっているのがありますが、今はts-jestだけでいけます。
422442

@@ -471,3 +491,40 @@ JestでもMochaでも、人気のフレームワークはテスト専用の関
471491

472492
.. todo:: eslintやテストの書き方の紹介
473493

494+
.. _change_import_path:
495+
496+
プロジェクト内のファイルの参照方法を\ ``@/``\ にする
497+
-------------------------------------------------------------------
498+
499+
プロジェクト内のファイルの\ ``import``\ では、現在のファイルから相対パスで書く方法と、\ ``tsconfig.json``\ の\ ``compilerOptions.baseDir``\ を起点とした絶対パスで書く方法がありました。
500+
501+
それ以外に近年広く使われている記法が、プロジェクトのベースフォルダを\ ``@/``\ と表記する方法です。
502+
503+
.. code-block:: ts
504+
505+
import { MyComponent } from "@/components/mycomponents";
506+
507+
もし、すべてのコードが\ ``src``\ フォルダ以下にあるのであれば、次のように\ ``tsconfig.json``\ を変更します。もしプロジェクトにJavaScriptファイルものこっているのであれば、同一の内容を\ ``jsconfig.json``\ に書けば、Visual Studio Code、Next.js、Veterなどが解釈してくれますし、\ ``babel-plugin-module-resolver``\ を入れれば他のプロジェクトでもこの表記が可能です。
508+
509+
.. code-block:: json
510+
:caption: tsconfig.json
511+
512+
{
513+
"compilerOptions": {
514+
"baseUrl": ".",
515+
"paths": {
516+
"@/src/*": ["src/*"]
517+
}
518+
}
519+
}
520+
521+
Jestはこのファイルから情報を取得してくれませんので専用の設定が必要です。
522+
523+
.. code-block:: json
524+
525+
{
526+
"moduleNameMapper": {
527+
"^@/(.*)$": "<rootDir>/src/$1"
528+
}
529+
530+
単なるエイリアスなので、この設定を入れなくてもできることは変わりませんが、特にテストコードからプロジェクトのファイルを参照したい場合など、\ ``import { Targert } from "../../../../src/components/Target";``\ のように\ ``import``\ が長くなる可能性があります。\ ``import``\ 文を他のファイルからコピーするときも、どのフォルダであってもそのまま使えるというメリットもあります。

0 commit comments

Comments
 (0)