TypeScript ベースの VuePress v2 (alpha) に更新する

VuePress v2 (alpha)

製作・運用しているウェブサイトの VuePress を v2 (alpha) に上げた。

Flutter Osaka | ドキュメント一覧

これは Flutter 日本ユーザグループ (大阪) のドキュメントサイトで、主にハンズオンやミートアップ等で開発者と技術情報を共有するため 2 年前に開設した。

docs/.vuepress/config.ts でナビゲーションバー並びにサイドバーの設定を書く。これは VuePress 1 系と比べて書き方は一切変わらないので今回は割愛させていただく。

VuePress 2 の特長

VuePress は Markdown をベースに書ける静的サイトジェネレータで適宜 Vue コンポーネントを使ってカスタマイズできる。

この度 VuePress 2 最大の特徴として型安全に書けるようになったことを挙げる。

※ VuePress 2 は 8 月 3 日現在 α 版です。

TypeScript で書けるようになった
Vue 3 で書けるようになった
webpack 5 サポート

このように TypeScript で書けるのと同時に Vue 3 でも書けるようになった。

::: message is-primary

これまでの Vue 2 系の書き方ではなく createApp で生成された app インスタンスに対し use を使ってプラグインを注入して書けば良い。

Vue コンポーネントを読み込む
サードパーティ製プラグインを読み込む

import { defineClientAppEnhance } from '@vuepress/client'

import Example from './components/Example.vue'

export default defineClientAppEnhance(({ app, router, siteData }) => {
  app.component('Example', Example)
})

:::

また内部的に Vite が入っており体感的にビルド速度が速くなった。

Roadmap #68

TypeScript で書けるようになった

docs/.vuepress/config.ts でウェブサイトの設定を書く。

かつて JavaScript で書いた設定を defineUserConfig<DefaultThemeOptions> という型定義の下で書けるようになった。

import { defineUserConfig } from 'vuepress'
import type { DefaultThemeOptions } from 'vuepress'

export default defineUserConfig <
  DefaultThemeOptions >
  {
    //
  }

meta 周りの書き方で VuePress 1 系と違う点が存在しハマった。

lib/types/head.d.ts を見ると、第 1 引数にヘッダタグを必ず追加する必要がある。

CSS を読み込む際に link を追加する
JavaScript を読み込む際に script を追加する

export declare type HeadConfig = [HeadTagEmpty, HeadAttrsConfig] | [HeadTagNonEmpty, HeadAttrsConfig, string];

export declare type HeadTagNonEmpty = 'title' | 'style' | 'script' | 'noscript' | 'template';

export declare type HeadTagEmpty = 'base' | 'link' | 'meta' | 'script';

export declare type HeadAttrsConfig = Record<string, string | boolean>;

この規則を頭に入れておけばハマる心配も無くなる。

head: [
  [
    `meta`,
    {
      hid: `title`,
      name: `title`,
      content: `<TITLE>`,
    },
  ],
  [
    `meta`,
    {
      hid: `description`,
      name: `description`,
      content: `<DESCRIPTION>`,
    },
  ],
]

その他ハマった点

先述の Vue 3 について、これまで使えていたプラグインが使えなくなることもある。

Flutter 日本ユーザグループのウェブサイトでは YouTube の配信動画を埋め込むため vue-youtube というプラグインを利用している。

しかし VuePress 2 ではそのプラグインが動かない。

Not compatible with Vue 3 RC #61

それもそのはず、まだ Vue 3 に対応していないため。

<template>
  <YouTube :video-id="videoId" :player-vars="playerVars" />
</template>

<script>
import YouTube from 'vue-youtube'

export default {
  components: {
    YouTube
  },
  props: {
    videoId: {
      type: String,
      default: ''
    }
  },
  data() {
    return {
      playerVars: {
        origin: `${location.protocol}//${location.hostname}/`
      }
    }
  }
}
</script>

そこで Vue 3 に対応しているプラグイン (があったので、それ) に乗り換えた。

vue3-youtube

先の vue-youtube と違い YouTube URL を引数にして渡している。

<template>
  <YouTube :src="`https://www.youtube.com/watch?v=${videoId}`" @ready="onReady" ref="youtube" />
</template>

<script lang="ts">
import YouTube from 'vue3-youtube'

export default {
  components: {
    YouTube
  },
  props: {
    videoId: {
      type: String,
      default: ''
    }
  },
  methods: {
    onReady() {
      this.$refs.youtube.playVideo()
    }
  }
}
</script>

あくまで違う方が開発されておりこの辺りの仕様が違っている点は仕方ありません。