テックブログ2023-12-23

Vue3アップグレード要点解説②：移行ビルド導入の注意点まとめ

shin

こんにちは、LAPRASの業務委託エンジニアのしんです。
この記事はLAPRASアドベントカレンダー 23日目の記事 && Vue3対応解説シリーズの第二弾です。

前回の記事では「移行ビルド導入前に行うべき作業」について解説しました。本記事では「移行ビルド導入作業における注意点」を解説していきます。


第二弾公開がVue2のEOL目前になってしまい恐縮ですが、公式ガイドに書いていない注意点も載せていますので、ぜひご一読ください！

移行ビルド導入の注意点


以下、公式ガイドの各ステップに沿って解説しますので副読本のようにお使いください。


準備（スロット構文の仕様変更対応）

このステップに関しては前回記事のようにVue3用のESLintルールを入れておくと、修正すべき箇所がわかるため捗ります。
該当するルールはvue/no-deprecated-slot-attributeです。

ステップ1・2（ライブラリのアップデート）

これらに関しては特に注意すべき点はなさそうでした。
ガイド通りに進めれば大丈夫と思われます。

ステップ3（ビルド設定の修正）

ガイドには'vue'のaliasとして@vue/compat を設定するように書いてありますが、一部のプロダクトではこれでは動かず、代わりに完全ビルドの@vue/compat/dist/vue.esm-bundler.js を指定する必要があります。

コンソールに以下のような警告が出ていた場合は完全ビルドのほうを指定しましょう。

[Vue warn]: Component provided template option but runtime compilation is not supported in this build of Vue. Configure your bundler to alias "vue" to "vue/dist/vue.esm-bundler.js".


ステップ4（型定義の追加）

Vue3用ESLintルールを導入している場合、vue/prefer-import-from-vueルールに引っかかると思います。
ただ何か問題があるわけでもないため、eslint-disable-next-lineコメントなどで無視すればOKです。

ステップ5（コンパイルエラーの修正）

ガイドにもある通り、コンパイルエラーを全て駆逐すればコンパイラをVue 3モードに設定することができます。

注意点として、移行ビルドのMODE はコンパイラ側とランタイム側の2種類が存在するのですが、今回Vue3モードに変えていいのはコンパイラ側のみです！

// ステップ3で追加した箇所
compilerOptions: {
  compatConfig: {
    MODE: 3 // ここは3にしてOK
  }
}


ここで誤ってランタイム側のMODE を3にしてしまうと、移行ビルドを削除したのと同じような状態になってしまいます。

import { configureCompat } from 'vue'

configureCompat({
  MODE: 3 //　こっちに書くと移行ビルドの互換機能がほぼ全てOFFに
})


実際コンパイラをMODE: 3 にしてもVue3の機能が全てオプトインされるわけではありません。というかほとんどVue2のままです。

例えばVue3からはv-model と連携するためのprop名がmodelValue に変わりましたが、コンパイラをVue 3モードにしただけでそうなるわけではなく、有効化するためにはランタイム側のconfigureCompat に設定する必要があります。 

import { configureCompat } from 'vue'

configureCompat({
  COMPONENT_V_MODEL: false, 　// trueの場合、移行ビルドの互換機能により v-model がVue2の挙動になる
})




このステップまで完了するとコンパイル自体は通るようになっていると思います。
（ただしこの状態ではまだページが正しく表示されていなかったり、コンソールにエラーが沢山出ている可能性も高いと思います）

ステップ6（コンソールの警告について）

このステップは移行ビルドが出す警告（Vue Warn）を消すためのTipsが色々書いてあるだけで、具体的なアクションは特にありません。

移行ビルドが出すVue Warnは（移行ビルドを入れている限りは）修正の必要がありませんが、たまに移行ビルドと無関係なVue Warnもあり、それらは直さないとアプリが動かなかったりするため注意が必要です。

ステップ7（transitionクラスの修正）

このステップに関してはこちらの手順がわかりやすかったです。

ステップ8〜10（Vueのマウント方法修正、VuexとVue-routerのアップデート）

これらについては特に詰まった点はありませんでした。

ステップ11(Vue Warnの修正)

ここからは移行ビルドを削除するための手順です。まずはステップ6でも触れたVue Warn達を修正していきます。

基本的な進め方としては、「破壊的変更の一覧の各項目について、適宜修正したあと対応する移行ビルドのフラグをconfigireCompatで無効化していく」を繰り返します。

例えばOPTIONS_BEFORE_DESTROY フラグの破壊的変更に関して対応したら以下のように追記していくイメージです。

import { configureCompat } from 'vue'

configureCompat({
  // beforeDestroy を beforeUnmountに修正したので、移行ビルドの互換機能を無効化する
  OPTIONS_BEFORE_DESTROY: false.
  ...
})

フラグの一覧はここにあります。これらを全てfalse に設定すれば勝ちというわけです。

ただしここにもいくつか注意すべき点があります。

例えばATTR_FALSE_VALUE の警告は、実際には何ら問題がない箇所に対しても出ることがあります。ドキュメントでも「ほとんどの開発者には影響がない破壊的変更」と言われています（<option> 要素でたまに影響があるくらいですかね）。

そのうえ警告が邪魔だからとATTR_FALSE_VALUE: false を設定してもなぜか警告が消えないという事象もありました（ATTR_FALSE_VALUE: 'suppress-warning' にすれば警告自体は消えますが、互換機能は無効化されません） 。

その他の注意点

またCOMPONENT_V_MODEL の互換機能を切るとmodel オプションを使用しているコンポーネントが動かなくなるという事象にも遭遇しました。
あまり使っている人はいなそうですが、もし該当する場合はmodel を使わない形に書き直す必要があります。

ステップ11.1(ライブラリのVue3対応)

プロダクトコードではなくライブラリのコードに対しVue Warnが出ることもあります。そのためライブラリのアップデートや差し替えもステップ11でやっておく必要があるでしょう。
（ちなみに弊社ではここが最も時間のかかったステップでした。ほとんどのライブラリがVue3に対応していなかったため・・）

まずは前回の記事で作った表が役立つと思います。この表を元にどのようにVue3対応を進めるかですが、

  • ライブラリ作者自身がVue3対応していればそれを使い、
  • していなければフォークして自分でVue3対応する

が結局最も簡単だと思いました。

弊社でも初めは、有志の方がフォークしてVue3対応してくれたものの使用を検討していたのですが、フォークした人自身のユースケースにしか対応しておらず弊社のプロダクトでは動かないなんてこともあったため、結局は「自分でVue3対応したほうが早い」となりました。

自分でVue3対応と言っても、基本的にはライフサイクルフックの名前変更など軽微な修正がほとんどでした。GitHubの海をさまよって代替ライブラリを探すくらいであれば、自身でフォークした方がずっと楽かと思います。

ステップ12(移行ビルドの削除)

全ライブラリのVue3対応が終わり、全警告を取り除き、動作確認もできた後は、移行ビルドを削除することができます。

yarn remove @vue/compat


compilerOptions: {
  compatConfig: {
    MODE: 3
  }
}

ステップ3で導入したcompilerOptionsも削除します。

resolve: {		
    alias: [		      			
      {find: 'vue', replacement: 'vue/dist/vue.esm-bundler.js'},

vueのaliasも元に戻します。

declare module '*.vue' {
  import type { DefineComponent } from 'vue';
  const component: DefineComponent;
  export default component;
}

ステップ4で導入した移行ビルド用の型も削除し、上記のようなVue3用の型に変更

configureCompat({
  COMPONENT_V_MODEL: false,
  ...
})

ステップ11で追加したconfigureCompat も消します。

"vueCompilerOptions": {		
  "target": 3	
},

tsconfigにvolar用のvueCompilerOptions.target を設定していた場合はこれも3にしておきましょう。

またプロダクトによっては以下の対応も必要かもしれません。

  • TypeScriptの型の修正
  • テストの修正
  • Storybookの修正



ここまでが終われば完全にVue3の世界に入ることができます！

移行作業での学び

ライブラリは定期的に見直しておくべきだった

移行ビルド導入作業の大半は、更新が止まったライブラリのVue3対応作業でした。
ライブラリアップデート自体は以前から定期的なスケジュールで行っていたのですが、更新が止まったライブラリの差し替えまでは行なっていなかったので、今後は定期的にお掃除をしたほうがいいなと思いました。

また、フレームワークに依存したライブラリよりも汎用的なライブラリの方が、柔軟にアップデートでき更新も止まりにくいと思われるので、Vueに特化したライブラリは極力減らしていこうと思いました。

テクい書き方は修正しておくべきだった

ドキュメント化されていないAPIを使うなど、アクロバティックな書き方をしていた箇所は、Vue3で軒並み壊れていました。
開発者が想定していない使い方をするということは、壊れた際の対処法もすぐにはわからない可能性が高いということです。
特段の理由がない限り、技術的な問題の解決はできる限り基本的な方法の組み合わせで行ったほうがいいなと改めて思いました。


このエントリーをはてなブックマークに追加