Skip to content

Commit f48c316

Browse files
nozomuikutanozomuikuta
committed
docs: add contents and ideas
1 parent aad947e commit f48c316

File tree

3 files changed

+229
-22
lines changed

3 files changed

+229
-22
lines changed

‎docs/.vitepress/config/ja.ts

+2-2
Original file line numberDiff line numberDiff line change
@@ -67,8 +67,8 @@ export const jaConfig = defineConfig({
6767
text: 'プロジェクトのセットアップ',
6868
link: '/ja/hands-on/project-setup',
6969
},
70-
// { text: 'Hello, chibivite!', link: '/ja/hands-on/hello-chibivite' },
71-
// { text: 'chibivite CLI', link: '/ja/hands-on/chibivite-cli' },
70+
{ text: 'Hello, chibivite!', link: '/ja/hands-on/hello-chibivite' },
71+
// { text: 'chibivite CLIのビルド', link: '/ja/hands-on/cli-build-setup' },
7272
],
7373
},
7474
],

‎docs/content/ja/hands-on/cli-build-setup.draft.md

+219
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,219 @@
1+
# chibivite CLIのビルド
2+
3+
::: tip このページのゴール
4+
✅ chibivite CLIをTypeScriptで実装してビルドできるようにしましょう
5+
:::
6+
7+
chibivite CLIの詳細をTypeScriptで実装できるようにして、より堅牢なコードベースで開発できるようにしましょう！
8+
9+
このハンズオンでは、Viteと同様に[Rollup](https://rollupjs.org/)を使ってビルドをおこないます。
10+
11+
---
12+
13+
まずは、Rollupをインストールして基本のビルドパイプラインを設定しましょう！
14+
15+
```bash
16+
cd packages/chibivite
17+
```
18+
19+
```bash
20+
pnpm install [email protected]
21+
```
22+
23+
::: info パッケージのバージョンについて
24+
ほとんどのパッケージは[セマンティックバージョニング](https://semver.org/)を採用しているため、マイナーバージョンの差分は安全に適用することができます。実際のところ、Rollupのバージョンを指定せずに以下のようにインストールしても、それがRollup v4系であれば基本的には問題ありません。
25+
26+
```bash
27+
pnpm install rollup
28+
```
29+
30+
しかし、マイナーバーアップデートに破壊的変更が含まれている可能性があります。このハンズオンでは、このハンズオンにしたがって開発したchibiviteが将来にわたって動作することを保証するため、すべての依存パッケージのバージョンを指定してインストールします。
31+
:::
32+
33+
以下のように `package.json` が書きかわっていれば成功です。
34+
35+
<!-- prettier-ignore -->
36+
```json
37+
{
38+
// ...
39+
"dependencies": {}, // [!code --]
40+
"dependencies": { // [!code ++]
41+
"rollup": "4.17.2" // [!code ++]
42+
}, // [!code ++]
43+
// ...
44+
}
45+
```
46+
47+
つぎに、`rollup.config.mjs` を作成して、以下のコードをコピーしましょう。
48+
49+
```js{8-12}
50+
import path from 'node:path'
51+
import { fileURLToPath } from 'node:url'
52+
import { defineConfig } from 'rollup'
53+
54+
const __dirname = fileURLToPath(new URL('.', import.meta.url))
55+
56+
export default defineConfig({
57+
input: path.resolve(__dirname, 'src/cli.mjs'),
58+
output: {
59+
dir: './dist',
60+
format: 'esm'
61+
}
62+
})
63+
```
64+
65+
Rollupでビルドをおこなうためには、入力元（エントリーポイント）と出力パス、そして出力形式の設定が必要です。
66+
それぞれ、`input` オプション、`output.dir`オプション、`output.format`オプションに対応しています。
67+
68+
::: details `__dirname` について
69+
`rollup.config.mjs`はECMAScript Module（ESM）であるため、CommonJS Moduleが提供している[`__dirname`](https://nodejs.org/docs/latest/api/modules.html#__dirname)定数が利用できません。
70+
ESMでは、代わりに `fileURLToPath(new URL('.', import.meta.url))` のイディオムを使って同様の値を得ることができます。
71+
今後、このイディオムを毎回記述しなくてすむように、`__dirname` という名前の変数に代入して利用しています。
72+
73+
結果として、`path.resolve(__dirname, 'src/cli.mjs')` は `/path/from/root/dir/to/packages/chibivite/src/cli.mjs` に解決されます。
74+
:::
75+
76+
`src/cli.mjs` はまだ存在しないため、ファイルを作成して、以下のコードをコピーしましょう。
77+
78+
```js
79+
console.log('Hello, chibivite!')
80+
```
81+
82+
<!-- このコードは `packages/chibivite/bin/chibivite.js` のコードから[shebang](https://en.wikipedia.org/wiki/Shebang_(Unix))を除いたものです。`bin/chibivite.js`を書きかえて、ビルドされた -->
83+
84+
Rollupを実行できるようにnpm scriptを定義しましょう。
85+
86+
<!-- prettier-ignore -->
87+
```json
88+
{
89+
// ...
90+
"scripts": {}, // [!code --]
91+
"scripts": { // [!code ++]
92+
"build": "rollup --config rollup.config.mjs" // [!code ++]
93+
}, // [!code ++]
94+
// ...
95+
}
96+
```
97+
98+
この状態で以下のコマンドを実行してみましょう。`dist/cli.js`が作成されれば成功です。
99+
100+
```bash
101+
pnpm run build
102+
```
103+
104+
以下のコマンドで、ビルドされた `dist/cli.js` を実行してみましょう。ターミナルに `Hello, chibivite!` と表示されれば成功です。
105+
106+
```bash
107+
node dist/cli.js
108+
```
109+
110+
`bin/chibivite.js`を以下のように変更して、`bin/chibivite.js`から`dist/cli.js`を呼び出すようにしましょう。これで、プレイグラウンドでビルドしたCLIを利用できるようになります。
111+
112+
```js
113+
#!/usr/bin/env node
114+
115+
function start() {
116+
console.log('Hello, chibivite!') // [!code --]
117+
return import('../dist/node/cli.js') // [!code ++]
118+
}
119+
120+
start()
121+
```
122+
123+
プレイグラウンドで以下のコマンドを実行してみましょう。ターミナルに `Hello, chibivite!` と表示されれば成功です。
124+
125+
```bash
126+
cd path/to/playground
127+
```
128+
129+
```bash
130+
pnpm run dev
131+
```
132+
133+
::: info なぜ`bin/chibivite.js`としてビルドしないのか
134+
Rollupを以下のように設定してビルドの出力先を直接 `bin/chibivite.js` にしても、プレイグラウンドでビルドしたCLIを利用できます（[shebang](<https://en.wikipedia.org/wiki/Shebang_(Unix)>)のあつかいは省略しています）。
135+
136+
```js
137+
export default defineConfig({
138+
input: path.resolve(__dirname, 'src/cli.mjs'),
139+
output: {
140+
dir: './bin',
141+
entryFileNames: 'chibivite.js',
142+
format: 'esm',
143+
},
144+
})
145+
```
146+
147+
このハンズオンでは、Viteにならいビルドの出力先を別途設定しています。くわしくは[コマンドラインインターフェース](/ja/concepts/command-line-interface)のページを参照してください。
148+
:::
149+
150+
---
151+
152+
ここから、TypeScriptをJavaScriptにトランスパイルするための設定をしていきましょう！
153+
154+
まず、Rollupを使ってTypeScriptをトランスパイルするために必要なパッケージをインストールしましょう。
155+
156+
```bash
157+
pnpm install -D @rollup/[email protected] [email protected]
158+
```
159+
160+
以下のように `package.json` が書きかわっていれば成功です。
161+
162+
<!-- prettier-ignore -->
163+
```json
164+
{
165+
// ...
166+
"devDependencies": {} // [!code --]
167+
"devDependencies": { // [!code ++]
168+
"@rollup/plugin-typescript": "11.1.6", // [!code ++]
169+
"tslib": "2.6.2" // [!code ++]
170+
} // [!code ++]
171+
}
172+
```
173+
174+
つぎに、`rollu.config.mjs`を以下のように書きかえ、`src/cli.mjs` を `src/cli.ts` にリネームしてTypeScriptファイルにしましょう。
175+
176+
```js
177+
import path from 'node:path'
178+
import { fileURLToPath } from 'node:url'
179+
import { defineConfig } from 'rollup'
180+
import typescript from '@rollup/plugin-typescript' // [!code ++]
181+
182+
const __dirname = fileURLToPath(new URL('.', import.meta.url))
183+
184+
export default defineConfig({
185+
input: path.resolve(__dirname, 'src/cli.mjs'), // [!code --]
186+
input: path.resolve(__dirname, 'src/cli.ts'), // [!code ++]
187+
output: {
188+
dir: './dist',
189+
format: 'esm',
190+
},
191+
plugins: [
192+
// [!code ++]
193+
typescript(), // [!code ++]
194+
], // [!code ++]
195+
})
196+
```
197+
198+
```bash
199+
mv src/cli.mjs src/cli.ts
200+
```
201+
202+
では、Rollupでビルドしてみましょう。ただし、`src/cli.ts`のコードにTypeScript特有の内容がふくまれていないため、トランスパイルできているかを確かめることができません。検証のため、以下のようにコードを書き換えてビルドしてみましょう。`dist/cli.js`で型宣言が消えていれば成功です。
203+
204+
```js
205+
type MyType = true // [!code ++]
206+
console.log('Hello, chibivite!')
207+
```
208+
209+
```bash
210+
pnpm run build
211+
```
212+
213+
検証がおわったら、型宣言は`src/cli.ts`から削除しましょう。
214+
215+
TODO: tsconfig.jsonのセットアップ
216+
217+
---
218+
219+
おめでとうございます！これでchibivite CLIをTypeScriptで実装してビルドできるようになりました！🎉

‎docs/content/ja/hands-on/hello-chibivite.draft.md ‎docs/content/ja/hands-on/hello-chibivite.md

+8-20
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# Hello, chibivite!
22

33
::: tip このページのゴール
4-
✅ chibiviteのパッケージ[コマンドラインインターフェース](/ja/concepts/command-line-interface)を実装しましょう
4+
✅ chibiviteの[コマンドラインインターフェース](/ja/concepts/command-line-interface)を実装しましょう
55

66
✅ chibiviteを実際に動作させることができるプレイグラウンドを立ち上げましょう
77
:::
@@ -24,21 +24,14 @@ start()
2424

2525
chibiviteをパッケージマネージャーでインストールした開発者がこのファイルを実行できるようにするため、`package.json` に以下の内容を設定しましょう。
2626

27+
<!-- prettier-ignore -->
2728
```json
2829
{
29-
"name": "chibivite",
30-
"private": true,
31-
"version": "0.0.0",
32-
"type": "module",
33-
"sideEffects": false,
34-
"engines": {
35-
"node": ">=20.12.0"
36-
},
30+
// ...
3731
"packageManager": "[email protected]",
3832
"bin": "bin/chibivite.js", // [!code ++]
3933
"scripts": {},
40-
"dependencies": {},
41-
"devDependencies": {}
34+
// ...
4235
}
4336
```
4437

@@ -58,6 +51,7 @@ packages:
5851
5952
つぎに `playground/package.json` を作成して、以下のコードをコピーしましょう。
6053

54+
<!-- prettier-ignore -->
6155
```json
6256
{
6357
"name": "playground",
@@ -97,18 +91,12 @@ pnpm install
9791
<!-- prettier-ignore -->
9892
```json
9993
{
100-
"name": "playground",
101-
"private": true,
102-
"version": "0.0.0",
103-
"type": "module",
104-
"sideEffects": false,
94+
// ...
10595
"scripts": {}, // [!code --]
10696
"scripts": { // [!code ++]
10797
"dev": "chibivite" // [!code ++]
10898
}, // [!code ++]
109-
"devDependencies": {
110-
"chibivite": "workspace:*"
111-
}
99+
// ...
112100
}
113101
```
114102

@@ -120,4 +108,4 @@ pnpm run dev
120108

121109
---
122110

123-
おめでとうございます！これでchibiviteパッケージをインストールして `chibivite` コマンドを利用できるようになりました！🎉
111+
おめでとうございます！これでchibivite CLIをプレイグラウンドで利用できるようになりました！🎉

0 commit comments

Comments
 (0)