⚡

VituumでVite環境にテンプレートエンジンを導入する

2023/12/03に公開

開発環境

概要

Vituum は、Vite用の静的サイトジェネレーターです。2023年6月27日に安定版（v1.0）がリリースされました。導入すると、様々なテンプレートエンジンやマルチページ対応、自動インポートなどの便利な機能が使えます。
公式サイトの説明によると、「Gulp など古いフロントエンドツールを使ってるプロジェクトに Vite を入れたい時の橋渡し的なツール」という立ち位置です。もし最新のプロジェクトの開発環境を作る場合、Astro や 11ty を使うことをオススメしています。（自分は Astro を使うと思います）
プロジェクトによっては、css や js のファイル名を固定しなくてはいけない場合があります。これまでそういうプロジェクトでは Vite と 11ty を組み合わせて環境をつくっていました。ただ、Vite と 11ty を２つ同時に動かす構成や面倒な設定をする必要があり、代わりとして Vituum を使える場合があるのではないかと考えています。

導入

Vituum を使用するにあたり、Vite のインストールから進めます。

まずは、Viteを入れる

node.js の準備をして（詳細は省略します。2023/12/01現在の安定版は 20.10.0）、Vite をインストールしましょう。

npm create vite@latest

今回は、Vanilla（フレームワークなし）と TypeScript を選択します。
指示通り進め、ローカルサーバーを立ち上げます。はじめのロゴ画面まで。

次に、Vituumを入れる

npm i vituum --save-dev

プロジェクトのルートに設定ファイル（vite.config.js）を作成し、以下を追記します。

import vituum from 'vituum';

export default {
  plugins: [vituum()],
};

Vituum を入れるだけで、Vite では少し手間だったマルチページ対応が自動で入ります。src/pages　内にページデータを追加しましょう。

src
└── pages
      ├── index.html
      └── second
            └── index.html

テンプレートエンジンを追加する

続いてテンプレートエンジンを追加します。
プロジェクトが進むにつれ「やっぱり 11ty がつかいたい」と思う場合があるかもしれません。Vituum でも 11ty でも使用できるテンプレートエンジンである liquid、handlebars、nunjucks、pug の中から、今回は nunjucks を選択します。
nunjucks のプラグインをインストールします。

npm i @vituum/vite-plugin-nunjucks --save-dev

vite.config.js を更新し、プラグインを登録します。

import vituum from 'vituum';
import nunjucks from '@vituum/vite-plugin-nunjucks';

export default {
  plugins: [vituum(), nunjucks()],
};

これで、nunjucks（.njk）が使用できます。
今回は、nunjucks の使い方は深くは触れません。公式サイトや他のブログなどを参照してください。layoutsやcomponentsを組み合わせることで、効率的な開発・運用ができるように設計できます。

Sassを入れる

実際にプロジェクトで使用することを想定して、Sass をインストールします。Vite では特に複雑な設定をする必要はありません。インストールするだけで .scssファイルを使用できます。

npm i sass --save-dev

ファイル管理のため、srcディレクトリの下にstylesディレクトリを新規作成し、scssファイルをつくりましょう。

src/
└── styles/
      └── common.scss

HTML（もしくはnunjucks）から読み込みます。

<head>
  ...
  <link rel="stylesheet" href="/src/styles/common.scss" />
</head>

Sass（正確に言うとdart-sass）にはglobbing（ファイルをまとめて読み込む）の仕組みがありません。これは、Vituum の import機能を使って解決できます。
impot機能は設定なしで使用できます。フォルダ内のファイルを読み込む「まとめファイル」が自動で生成されます。ただし、デフォルトではcssファイル（+.css）になっているので、Sass（+.scss）の対応を設定します。
vite.config.js の Vituum にオプションを設定します。cssでは書かないので空の配列を設定します。
（必要に応じてJavaScript / TypeScript の指定を追加しましょう）

import vituum from 'vituum';
import nunjucks from '@vituum/vite-plugin-nunjucks';

export default {
  plugins: [
    vituum({
      imports: {
        filenamePattern: {
          '+.css': [],
          '+.scss': 'src/styles',
        },
      },
    }),
    nunjucks(),
  ],
};

src/
└── styles/
      ├── base/
      │    ├── +.scss  <-このファイルが自動生成される
      │    ├── base.scss
      │    └── reset.scss
      └── common.scss

このような構成の場合、+.scss ファイルの中身はこうなります。

@import "base.scss";
@import "reset.scss";

この +.scss を common.scss からインポートします。以後、フォルダ内のファイルを追加／削除すると自動で更新されます。

@import "./base/+.scss";

Path Aliasを設定する

scssファイルやtsファイルの構造が複雑になってくると、 ../../../hoge という感じでimportが深くなります。これを避けるために Path Alias を設定します。
Path Alias を設定すれば、どのファイルからも同じルールで import を記述できます。もしディレクトリ構造を変更しても import のエラーが発生しません。
Pth Aliasを設定するため vite.config.js を更新し、scrディレクトリとstylesディレクトリにパスを通します。

import path from 'path';
import { fileURLToPath } from 'url';
const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

export default {
  resolve: {
    alias: {
      '@/': `${__dirname}/src/`,
      '@scss/': `${__dirname}/src/styles/`,
      "@ts/*": `${__dirname}/src/scripts/`,
    },
  },
  ...
};

この設定をした後、先ほどの common.scss はこのように書き換えることができます。

// @import "./base/+.scss";

@import "@scss/base/+.scss";
or
@import "@/styles/base/+.scss";

TypeScript（tsファイル）でも使えるようにするためには、TypeScript の設定ファイル（ tsconfig.json ）にも追記する必要があります。

{
  "compilerOptions": {

    ...省略...

    "baseUrl": "./",
    "paths": {
      "@/*": ["src/*"],
      "@ts/*": ["src/scripts/*"]
    }
  }
}

このままだと vite.config.js と tsconfig.json の二重管理になってしまいます。vite-tsconfig-paths というプラグインを使用すれば ts用の設定は tsconfig.json で一括管理できるのですが、scssファイル用の設定は vite.confing.js に書く必要があるため、完全な一括管理はできません。状況に合わせて導入を検討してください。
あわせて、VSCode の Path Autocomplete を設定すると、より快適にコーディングできます。

【課題】Viteのbase設定が無効になる

Vite には公開したいディレクトリーやURLを設定するbase設定があるのですが、Vituum と併せて使うことができません。Vituum が管理するページデータは src/pages/ に入っており、ここのパスが必ずドメインのルートになっており、baseで設定したパスとズレが生じます。
この問題の解決策を見つけることができませんでした。引き続き解決方法を調査します。

まとめ

Vite に便利な機能を追加できる Vituum を紹介しました。
Vituum が使える状況は結構あるのではないでしょうか。Vituum はViteプラグインの組み合わせでできているため、個別の機能だけでも使うことができます。Astro と Vituum のファイルimport機能を組み合わせるのがオススメです。
実際の案件で使用するには、コードの整理（linter、formatter）などが必要になります。その辺りの設定を追加したデータを GitHub にあげました。参考まで。

概要

導入