GulpでSwiperをローカル配置するまでの道のり【実体験】

こんにちは。いっきー(@ikirin_web)です。

SwiperをCDNではなくローカルで管理しようとしたところ、思わぬ落とし穴にはまりました。今回はその原因と解決までの流れを記録しておきます。

環境

• Gulp 5
• Sass（Dart Sass）
• FLOCSS構成
• Node.js（最終的にv18で解決）

やろうとしたこと

SwiperのCSSをSassフォルダで管理しようと考え、_swiper.scssというファイルを作り、SwiperのCSSをそのまま貼り付けました。

src/
  assets/
    sass/
      foundation/
        _swiper.scss  ← ここにSwiperのCSSを入れようとした

最初のエラー：SassがSwiperのCSSを解釈しようとする

_swiper.scssを作ってSwiperのCSSを貼り付けたものの、SassコンパイラがSCSSとして解釈しようとしたが、SwiperのCSSは純粋なCSSのため構文エラーになりました。

解決策①：CSS用フォルダを別に作る

「SwiperはCSSファイルのままコピーするだけでいい」という発想に切り替えました。

src/
  assets/
    css/
      swiper-bundle.min.css  ← ここに置く
    sass/
      ...（Sassファイルはここのまま）

Gulpには、SwiperのCSSとJSをそれぞれコンパイルせずそのままコピーするだけのタスクを別途追加しました。minifyも不要なので、コピーのみです。

watchとbuildにもそれぞれ追記して対応しました。

次のエラー：Gulpのビルドタスクが動かない

Gulpのビルドタスクを実行しようとしたところ、今度は別のエラーが出ました。

sh: gulp: command not found

調べていくと、node_modulesが不完全な状態でインストールされていたことが原因でした。削除して入れ直したところ、別のエラーに変わりました。

Cannot find module ‘vinyl-contents/node_modules/bl/bl.js’

大元の原因：Node.jsのバージョンが新しすぎた

ここで根本的な原因が見えてきました。

• 私の環境：Node.js v23（新しすぎる）
• Gulp 5の動作検証済み環境：Node.js v18〜v20

使っていたプラグインの一部が古く、Node.js v23に対応していなかったのです。node_modulesを入れ直しても、インストールされるパッケージのバージョンは変わらないため、同じエラーが出続けていました。

Node.js自体のバージョンを下げる必要がありました。

解決策②：nvmでNode.jsをv18に切り替える

nvmはNode.jsのバージョンを複数管理できるツールです。プロジェクトごとに必要なバージョンへ切り替えられます。

導入手順は別記事にまとめています。→ nvmでNode.jsのバージョンを切り替える

もう一つの落とし穴：min.min.jsが生成される

Gulpが動くようになって出力フォルダを確認すると、swiper-bundle.min.min.jsというファイルが生成されていました。

原因はminJsタスクが対象にするファイルの範囲が広すぎたことでした。

// 変更前：サブフォルダも含む全.jsファイルが対象
gulp.src("./src/assets/js/**/*.js")

// 変更後：直下のファイルのみ対象
gulp.src("./src/assets/js/*.js")

**/*.jsはサブフォルダを含む全ファイルを対象にするため、lib/フォルダに入れたSwiperのJSまで拾ってしまっていました。

*.jsに変更して直下のみを対象にすることで解決しました。

src/
  assets/
    js/
      main.js  ← minJs()が対象（直下のみ）
      lib/
        swiper-bundle.min.js   ← コピータスクが対象

まとめ：今回学んだこと

① SwiperのCSSファイルをSassフォルダに置かない

SwiperのCSSには &記法が含まれているため、sassフォルダに置くとエラーになる。cssフォルダを別に作ってそこで管理する。

② Gulpタスクは役割ごとに分ける

「minifyして出力するタスク」と「そのままコピーするタスク」は別に持つ。1つの仕事に1つの関数。

③ ファイルの指定範囲が広すぎると意図しないファイルまで処理される

• *.js → 直下のファイルのみ
• **/*.js → サブフォルダを含む全ファイル

④ Node.jsのバージョン管理はnvmで行う

プロジェクトごとに必要なNode.jsバージョンが異なるため、nvmで切り替えられる環境を整えておく。

小さなつまずきでしたが、Gulpの仕組みとNode.jsのバージョン管理まで理解が深まった良い経験になりました。