2 万行の WordPress プラグインの JavaScript を、画面の動きを変えずに TypeScript へ移している

自社の WordPress プラグイン AW Genko は、縦書きの 400 字詰め原稿用紙で文章を書き、docx と PDF に書き出すためのものだ。 AW Genko は自社のサイトで使うために作っているもので、販売はしていない(非売品)。本記事は、その作り直しの記録として書く。 ブラウザーで動く部分は素の JavaScript で書いてきて、いちばん大きな書く画面のファイルは 8,639 行あった。 これを、画面の動きをまったく変えないまま、少しずつ TypeScript に移している。 本記事では、移す意味として何を見込んでいるのか、動きを変えないために何で確かめているのか、いまどこまで進んだのかをまとめる。

なぜ TypeScript にするのか

1. 型が、壊れ方を書く前に教えてくれる

いちばん分かりやすい利点は、静的な型による安定性だ。 関数に渡す値の形、null かもしれない値、呼び出す側と呼ばれる側の食い違いを、ブラウザーで動かす前に tsc が見つける。 設定は strict を始めとする厳しいものにし、any は外から来る値(JSON や DOM)の入口だけに限る方針にした。

素の JavaScript では、こうした食い違いは利用者の画面で初めて表に出る。 とくに書く画面は、変換中の入力、選択、取り消し、保存、サイトとの同期が絡み合うので、1 か所の思い違いが離れた所で壊れて見える。 型はその種の壊れ方の多くを、手元で止めてくれる。

2. 部品の境目と、頼っているものがはっきりする

型の効き目は、実はそれだけではなかった。 書く画面は、1 つの大きな関数の中に数百の関数が並び、互いの変数を自由に読み書きする形だった。 これを TypeScript の部品へ移すには、その部品が何に頼っているかを、全部書き出す必要がある。

たとえば「サイトの原稿とのつなぎ」を移したときは、状態のほかに 31 個の道具(知らせを出す、原稿を開く、保存する など)を受け取る形になった。 ボタンやメニューの操作を振り分ける所では、受け取る道具が 48 個になった。 この一覧は TypeScript の interface として残るので、どの部品が何に頼っているのかが、読めば分かる。 今まで暗黙だった依存が目に見える形になることは、型の検査と同じくらい大きな利点だと感じている。

部品の境目は、試験の作りに合わせて決めることもあった。 ある試験は、保存や読み込みを試験用の道具に置き換えて、操作の振り分けだけを確かめている。 振り分けの一部だけを保存の部品に入れると、振り分けが部品の中の保存を直接呼ぶので、その置き換えが効かなくなる。 そこで、振り分けは振り分けだけで 1 つの部品にした。 ホイールでめくる判定も同じ理由で、めくり始めの処理とは別の部品にしている。

3. 試験を「文字の照らし合わせ」から「動かして確かめる」へ移せる

これまでの試験の多くは、JavaScript のソースの文字列を正規表現で照らしていた。 これは書き換えに弱く、意味の同じ書き換えでも落ちる。 部品に分けると、その部品だけを作って、代わりの道具を渡して動かせる。 TypeScript 化と一緒に、試験も少しずつ「関数を呼んで結果を見る」形に置き換えている。

4. 型が説明書になり、エディターが助けてくれる

型の宣言は、そのまま「この関数は何を受け取り、何を返すか」の説明になる。 半年後の自分や、ほかの人が読むときに、関数の中を追わなくても使い方が分かる。 エディターの補完や名前の変更も、型があると安心して使える。

5. 次に作るものの土台になる

同じ縦書きの仕組みを使う便箋のプラグインや、アプリ版を作る予定がある。 組版の規則や、試験に使うデータを共通のコアとして取り出し、原稿用紙と便箋の両方から使う計画だ。 コアを型付きの部品として持っておけば、使い回すときに約束(受け取る値と返す値)が崩れにくい。 規則の表は JSON にして、TypeScript と PHP の両方から同じものを読み、同じ試験のデータで照らす予定でいる。

6. 配る形は変えない

一方で、変えないと決めたこともある。 配る JavaScript(assets/js)は Git に入れたままにし、zip の作り方やサイトへの入れ方は今までどおりにした。 TypeScript から esbuild で、今までと同じ形(即時関数で包み、window に名前を出す形)の JavaScript を作る。 PR ごとに「配る JavaScript が TypeScript のソースと合っているか」を確かめ、合っていなければ落とす。 プラグインを入れる側から見ると、何も変わらない。

動きを変えないために、何で確かめているか

書き換えで怖いのは、気づかないうちに動きが変わることだ。 そこで、版ごとに 3 つの確かめを重ねている。

  • 乱数で照らす:DOM に触らない関数は、書き換える前の関数と後の関数に、乱数で作った同じ入力を何十万回も渡し、結果がすべて同じかを見る。めくる動きの計算では 28 万 1 千回照らした。
  • 試験:JavaScript の試験 85 本を、版ごとにすべて通す。
  • 画面を動かして比べる:使い捨ての WordPress を 2 つ立て、片方に前の版、もう片方に新しい版を入れる。Playwright で、書く画面の一通りの操作(打つ、記法を付ける、保存する、サイトの原稿を開く・ごみ箱に入れる、全画面に出入りする など 179 段)を流し、段ごとに画面の状態を書き留めて比べる。Chromium と WebKit で 2 回ずつ流し、全段が同じことを確かめる。

3 つ目の比べは、仕組みよりも「同じ版どうしで差が出ないようにする」ことに手間がかかった。 書体の読み込みが間に合わない回、選択の変わり目の知らせが遅れて届く回、前の回の設定がサイトに残る回などがあり、その都度、台本の待ち方と後片付けを直した。 差が 0 の状態を作ってからでないと、書き換えによる差と、ただの揺れとを見分けられない。

もう 1 つ気をつけているのは、比べる台本が、移す所を本当に通っているかだ。 全画面、この端末の原稿を一覧から開く・消す、取り消す・やり直すは、移す番が来たときに調べると、台本が通っていなかった。 そのたびに段を足し、足した段で画面が実際に変わる(全画面の窓が開く、本文と名前が開いた原稿に替わる、一覧が 1 件減る など)ことを確かめてから比べている。 「全段が同じ」は、通っていない所については何も言っていないからだ。

いま、どこまで進んだか

手順は 5 つに分けている。

手順 中身 状態
1 道具をそろえる(TypeScript・esbuild・確かめの仕組み) 済
2 小さい部品を書き換える(組版、ルビ、保存、書き出しなど) 済
3 書く画面を、役割ごとの部品に分けながら書き換える 進行中
4 表示とめくる動き、ブロックの編集画面を書き換える 進行中
5 共通のコアを取り出し、組版を 2 層に分ける これから

2026 年 11 月 19 日の時点で、取り込みを終えた分を行数で見ると次のとおりだ。

行数
TypeScript にした分 12,393 行
手書きの JavaScript のまま残る分 8,935 行

行数だけで割ると、約 58% が移ったことになる。 書く画面のファイルは、初めの 8,639 行から 5,803 行になった。 ただし、作業量で見た進捗率は約 40% と見積もっている(前日の見積もりは約 30%)。 残っている書く画面の部分は、文字の入力と変換、選択、めくりと表示の位置合わせなど、DOM と出来事が絡む所で、1 行あたりの手間が今まで移した所よりずっと大きい。 また手順 5 のコアを取り出す作業は、行数には表れない大きな作業だ。

手順 重み 進み 寄与
1・2 20% 済 20%
3 書く画面 40% 約 50% 約 20%
4 表示とブロックの編集画面 15% 約 5% 約 1%
5 コアを取り出す 25% 0% 0%
計 約 41%

重みは筆者の見積もりで、進めながら見直していく。

これから

前日の時点で残っていた、操作のバーとメニュー、紙面の描き方、この端末の保存の安全、全画面は、移し終えた。 続けて、原稿の保存と開閉も移した。 操作の振り分け、取り消す・やり直す、ホイールでめくる判定は、移して確かめている途中だ。 書く画面で最後に残るのは、めくり始めと表示の位置合わせ、文字の入力と変換の出来事だ。 めくりと位置合わせは字を打つたびに通る道に近いので、移すときは描く速さも前の版と比べる。 その後、表示とブロックの編集画面に進み、最後にコアを取り出す。 どの段階でも、プラグインを使う人から見た動きは変えない。 節目ごとに、この記事の続きとして結果を書く予定だ。