Vite で Master CSS を設定する

React、Vue、React Router のフレームワークモード、TanStack Start など、Vite でビルドするアプリに Master CSS を追加します。インテグレーションはソース内の完全なクラス名から CSS を生成します。フレームワークの既存の Vite プラグインとマウントコードを保持してください。Master CSS は共通のスタイルシートを通してビルドに加わります。

#インストール

1. #Master CSS を追加する

   既存の Vite プロジェクトのルートで、フレームワーク表の --framework 値を指定してインストーラーを実行します。既定は静的モードで、ソース内の完全なクラス名が通常の CSS になります。

   npm create @master/css@2.0.0 -- --framework vite --yes

2. #CSS エントリーを確認する

   インストーラーは Vite プラグインに masterCSS() を追加し、フレームワークごとのエントリーに示すスタイルシートを更新します。プレーン JavaScript のスターターでは次のファイルです：

   src/style.css

   @import '@master/css';

   アプリからこのエントリーをインポートしたままにしてください。異なるファイル名を使うプロジェクトでは、インストーラーの出力を確認し、そのファイルをインポートします。インストーラーはフレームワークのアプリを作成せず、マウントコードも置き換えません。

3. #Master CSS を使い始める

   #app 要素があるプレーン JavaScript のスターターでは、次のエントリーを使い npm run dev を実行します。フレームワークのアプリでは、以下の対応するコンポーネント例を使ってください。

src/main.js

import './style.css'document.querySelector('#app').innerHTML = `  <p id="master-check" class="w-fit m(0) p-md b-solid b(1) b-line-divider r-md text-sm font-regular bg-surface-raised fg-text-strong">    Hello World  </p>`

ニュートラルなサーフェス、細い枠線、小さな角丸、各辺に 1rem の内側余白を持つ例です。

#フレームワークごとのエントリー

アプリに対応するインストーラーの値を選びます。以下は一般的なスターターのパスです。React と Vue では、対応する別の既存 CSS エントリーも再利用できます。このフラグを省くと、インストーラーがプロジェクトからフレームワークを検出します。

#React

Vite でビルドする React プロジェクトで、src/App.tsx を置き換えます。src/main.tsx の src/index.css インポートは保持してください。

export default function App() {  return (    <p id="master-check" className="w-fit m(0) p-md b-solid b(1) b-line-divider r-md text-sm font-regular bg-surface-raised fg-text-strong">      Hello World    </p>  )}

#Vue

Vue プロジェクトで src/App.vue を置き換えます。アプリのエントリーの src/assets/main.css インポートは保持してください。

<template>  <p id="master-check" class="w-fit m(0) p-md b-solid b(1) b-line-divider r-md text-sm font-regular bg-surface-raised fg-text-strong">    Hello World  </p></template>

#React Router

React Router のフレームワークモードのプロジェクトでは、インストーラーが app/root.tsx から app/app.css をインポートします。ホームのルートを置き換え、app/routes.ts の登録は保持します。app/root.tsx の Links、Scripts、Outlet、ドキュメント構造は残してください。ページとスタイルシートを配信するために必要です。

export default function Home() {  return (    <p id="master-check" className="w-fit m(0) p-md b-solid b(1) b-line-divider r-md text-sm font-regular bg-surface-raised fg-text-strong">      Hello World    </p>  )}

#TanStack Start

Vite でビルドする TanStack Start プロジェクトで、インデックスルートを置き換えます。インストーラーは src/routes/__root.tsx から src/styles/app.css をインポートするため、すべてのルートで同じ CSS エントリーが読み込まれます。

import { createFileRoute } from '@tanstack/react-router'export const Route = createFileRoute('/')({  component: Home})function Home() {  return (    <p id="master-check" className="w-fit m(0) p-md b-solid b(1) b-line-divider r-md text-sm font-regular bg-surface-raised fg-text-strong">      Hello World    </p>  )}

#設定を確認する

開発サーバーの実行中に、ソースの p-md を p-lg に変えます。パディングが 1rem から 1.5rem に増えるはずです。p-md に戻してからアプリをビルドします：

npm run build

プロジェクトのプレビューまたは起動コマンドで本番出力を配信します。プレーン Vite、React、Vue のスターターは通常 npm run preview を使います。React Router と TanStack Start は設定されたサーバーやデプロイアダプターを使います。段落に 1rem のパディングが残り、静的モードでは Master CSS のブラウザーランタイムが配信されないことを確認してください。

クライアントレンダリングのアプリが段落を作るには JavaScript が必要です。サーバーレンダリングが有効な React Router または TanStack Start のルートでは、JavaScript を無効にして再読み込みし、サーバーの HTML に同じスタイルシートが適用されるか確認してください。

ファイルは読み込まれるのに一つのクラスがない場合は、ソースに完全な名前を記述してください。クラス名の走査も参照できます。すべてのユーティリティが動かない場合は、CSS エントリーのインポートと、Vite 設定でフレームワークのプラグインとともに masterCSS() が登録されているか確認します。スターターのスタイルが結果を覆う場合は、@import '@master/css'; を残して見た目のルールを削除してください。

#別のレンダリングモードを選ぶ

既定の静的モードでは、Master CSS の起動コードは不要です。モードを変えても CSS エントリーを保持してください：

npm create @master/css@2.0.0 -- --framework vite --mode runtime --yes

import './app.css'if (!import.meta.env.SSR) {  void import('virtual:master-css-runtime')}

import '../styles/app.css'if (!import.meta.env.SSR) {  void import('virtual:master-css-runtime')}

/// <reference types="@master/css/client" />

document.querySelector('#master-check').classList.add('underline')

#スタイルシートの読み込み方を選ぶ

ドキュメントのスタイルシートには通常の CSS インポートを使います。別の利用側が CSS テキストや URL を必要とする場合だけ、異なるリクエストを使ってください。これらはアプリの Master CSS エントリーを置き換えず、レンダリングモードも変えません。

たとえば、自分が管理するドキュメントに信頼できるビルド出力を挿入します：

import css from './app.css?inline'const style = document.createElement('style')style.textContent = cssdocument.head.append(style)

処理済みテキストにもインポートが残る場合があります。CSSStyleSheet.replaceSync() はインポートのない出力にだけ使ってください。インポートされたスタイルシートを読み込む機能はありません。シャドウルートでは、スタイルシートの順序とアセットのベースパス要件も含め、Lit の設定に従ってください。

#Sass と CSS Modules

プロジェクトの Sass 依存関係と Vite の前処理オプションを保持します。Sass が Master CSS に処理を残すよう、エントリーのインポートを CSS の URL インポートとして記述してください：

@import url("@master/css");

解決済みの Sass パーシャルは、それぞれのリソースディレクトリーを保持します。ソースマップは可能な限り診断を元のファイルに結び付けますが、生成された内容や対応付けのない内容では、前処理後の位置しか示せません。Master のミックスイン定義は .css に置くか、Sass 相互運用パターンを使ってください。

CSS Modules はスコープ付きのエクスポートと composes の関係を保持します。ネイティブの宣言は、グローバル出力を再度インポートせずにプロジェクトの定義を使えます。ページ再読み込みなしにクラス名のエクスポートを更新するには、フレームワークの HMR または利用側モジュールが変更を受け入れる必要があります。?inline はスコープ付き CSS テキスト、?raw は元のソースを返します。Vite 8.3.5 は .module.css と .module.scss の ?url リクエストを拒否するため、モジュールスタイルシートにこの経路を使わないでください。

#デプロイしたアセットを確認する

保持された子スタイルシート、画像、フォント、ランタイムプログラムも含め、本番出力をすべてデプロイします。Master CSS はインポートの media、supports、layer の条件を保持し、元の所有ファイルを基準にリソース URL を書き換えます。そのためインライン文字列にも別のアセットが必要な場合があります。この境界はインポートの仕様で説明しています。

SSR の ?inline 利用側では、URL に設定済みの公開 base を使います。Vite は既定で SSR アセットを出力しません。対応するクライアントビルドのアセットをデプロイするか、サーバービルドで公開する必要がある場合は build.ssrEmitAssets を有効にしてください。ビルドをデプロイ先へ移動した後で、配信レスポンスと Network パネルを確認します。その場でのビルドだけでは、URL の移植性は確認できません。

開発中に参照先リソースを削除するとコンパイルエラーが報告されますが、そのサーバーコンテキストが終了するまでは、公開済みのリソース版が利用できる場合があります。依存リソースを復元し、利用側が更新されてエラーが消えるか確認してください。ページのスタイルが残るだけでは、最新のコンパイル成功を確認できません。