Storybook6.x から8.x のマイグレーションの対応とエラーの対処方法

こんにちは、Gaji-Labo フロントエンドエンジニアのたにもとです。

まだ Storybook 8 にマイグレーションできてない…。
そんな方のために Storybook6 から Storybook8 にマイグレーション時の対応方法を残します！

本記事は、Next.js を利用したプロジェクトを前提としております。
ご承知の上読み進めていただけますと幸いです。

マイグレーション時の対応

Storybook 6.x から Storybook 8.x へのマイグレーションで対応したのは以下の通りです。

• webpack から vite を利用したビルド方法に変更
• プラグインの精査
• package.json の scripts を変更

対応した内容の詳細を解説します。

webpack から vite を利用したビルド方法に変更

webpackFinal を利用した書き方

webpackFinal: async (config) => {
  config.module.rules.push({
    test: /\.scss$/,
    use: [
      'style-loader',
      {
        loader: 'css-loader',
        options: {
          importLoaders: 1,
          modules: {
            auto: true,
          },
        },
      },
      'sass-loader',
    ],
    include: path.resolve(__dirname, '../'),
  })
  return config
},

viteFinal を利用した書き方

async viteFinal(config) {
  return mergeConfig(config, {
  plugins: [
　　 // emotion を利用している場合はここに設定を記述する
    react({
      exclude: [/\.stories\.(t|j)sx?$/, /node_modules/],
      jsxImportSource: '@emotion/react',
      babel: {
        plugins: ['@emotion/babel-plugin'],
      },
    }),
    // svg の属性が反映されないなど build に関連の不備がある場合は記述します。
    // 'vite-plugin-svgr' を利用して設定を記載しました。
    svgr({
      include: '**/*.svg',
      svgrOptions: {},
    }),
  ],
})

vite 関連のパッケージも import する必要があります。

import { mergeConfig } from 'vite'
import react from '@vitejs/plugin-react'
import svgr from 'vite-plugin-svgr'

preview.js も vite を利用するように追記します。

const preview = {
  parameters: {},
  // ここに追記
  core: {
    builder: 'vite',
  },
}

export default preview

プラグインの精査

@storybook/addon-actions と @storybook/addon-viewport はアンインストールし、@storybook/addon-essentials をインストールしておきます。
@storybook/addon-essentials は、推奨構成がセットになっており、addon-actions と addon-viewport が含まれているためです。
詳細については、Storybook の公式サイトを確認してください！

package.json の scripts を変更

Storybook のバージョン6からマイグレーションする場合は scripts のコマンドも変更しましょう。

// 修正前のコード
"scripts": {
  "storybook": "start-storybook -p 6006",
  "build-storybook": "build-storybook -s public/",
}

// 修正後のコード
"scripts": {
  "storybook": "storybook dev -p 6006",
  "build-storybook": "storybook build public/",
}

変更点は以下の3点です。

• start-storybook → storybook（Storybook7 の変更点）
• build-storybook → storybook（Storybook7 の変更点）
• build コマンド-s フラグの削除（Storybook8 の変更点）

発生した具体的なエラー内容と対応方法

yarn storybook や yarn build を実行した時に発生したエラーは以下の通りです。

• The CJS build of Vite’s Node API is deprecated. See https://vite.dev/guide/troubleshooting.html#vite-cjs-node-api-deprecated for more details.
• Global built-in functions are deprecated and will be removed in Dart Sass 3.0.0. Use color.mix instead.
• Storybook にて public ディレクトリから読み込んでいる画像が表示されない

The CJS build of Vite’s Node API is deprecated.

古い vite のバージョンを利用していることが問題でした。
私の場合は vite のバージョンを 4系にアップデートしたことで解消できました。

Storybook で vite を利用しようとした時に発生する可能性があります。
ビルダー関連のエラーが発生した場合は、@storybook/builder-vite も確認してみてください。

Global built-in functions are deprecated and will be removed in Dart Sass 3.0.0. Use color.mix instead.

グローバル関数が新しいバージョンでは非推奨になるため変更が難しい場合は、.storybook/main.jsにて古い API lagacy.ks-apiを利用することを明示して回避します。

async viteFinal(config) {
  return mergeConfig(config, {
  plugins: [],
  // scss を利用している場合であたらしい API が利用できない場合はこちらに記述
  css: {
    preprocessorOptions: {
      scss: {
        silenceDeprecations: ['legacy-js-api'],
      },
    },
  },
})

Storybook にて画像が表示されない

画像パスの指定方法が間違っていることが原因であることも考えられますが、next/image を利用されている場合は別の対策が必要です。

next/image を利用していましたが、public ディレクトリから読み込んでいる画像や外部から読み込んでいる画像が表示されない事象が発生しました。

そこで main.js にて next/image を img タグに置換する処理を追加して解消しました。

1 .storybook/main.js の編集

async viteFinal(config) {
  return mergeConfig(config, {
  plugins: [],
  // ここに追記します。
  resolve: {
    alias: {
      'next/image': path.resolve(__dirname, './NextImage.tsx'),
    },
  },
})

2 .storybook/ の配下に置き換え用のコンポーネントを作成

import React from 'react'

const Image = ({ src, alt, ...props }) => {
  return <img src={src} alt={alt} {...props} />
}

export default Image

Storybook のマイグレーションは問題の切り分けを意識すること

Storybook のバージョンだけでなく、フレームワークのバージョンによってもエラーが発生します。
Storybook か フレームワークどちらの問題なのか切り分けるとスムーズにマイグレーションできると考えています。

過去の歴史的なコードがエラーの原因になっていることも多いので、一度同じフレームワークのバージョンをそろえた新しい環境に最新の Storybook を入れて差分を確認するのも1つの方法です。

Gaji-Labo が支援しているプロダクトチームでも Storybook を活用していることが多いことからマイグレーションに関する知見があったことも良かったです。

この記事がマイグレーションの際にお役立ていただけますと幸いです。