Nuxt 4時代のSCSS共通化戦略 - 変数とMixinの効率的な管理手法

エンジニアブログ

最終更新日：2025年08月27日｜公開日：2025年08月24日

writer：益子竜与志

フロントエンド開発において、スタイリングの選択は開発効率と保守性を左右する重要な意思決定です。2024年7月に正式リリースされたNuxt 4では、Viteビルダーがデフォルトとなり、SCSSの扱い方にも若干の変化が生まれました。

本記事では、Nuxt 4環境でSCSSの変数やMixinを効率的に共通化する最新の手法と、プロダクション環境での実践的な活用パターンを解説します。PostCSSかSCSSかという選択の本質的な判断基準から、実装の詳細、そして開発チームの生産性を最大化するための戦略まで、実務で直面する課題に対する具体的な解決策を提示していきます。

Nuxt 4時代のSCSS共通化戦略 - 変数とMixinの効率的な管理手法

フロントエンド開発において、CSSプリプロセッサの選択は単なる技術的な判断以上の意味を持ちます。特に「内製化支援」という文脈では、技術の習得コスト、ドキュメンテーション、そして長期的な保守性を総合的に考慮する必要があります。

なぜSCSSを選択するのか - PostCSSとの本質的な違い

SCSSが持つ「完成されたエコシステム」の価値

SCSSを採用する最大の理由は、その「完成度」にあります。PostCSSが「プラグインによる拡張」を前提とした設計思想を持つのに対し、SCSSは必要な機能が最初から全て揃っています。この違いは、プロジェクトの規模が拡大するにつれて顕著な差となって現れます。

PostCSSプロジェクトでよく見られる課題として、プラグインの組み合わせが複雑化し、新規メンバーが参画する度に「なぜこのプラグインを使っているのか」「どういう順序で処理されるのか」といった説明が必要になります。一方でSCSSは、Sass公式ドキュメントを参照すれば、誰でも同じ理解に到達できます。

内製化支援における「学習可能性」の重要性

クライアント企業への技術移管を前提とする場合、「公式リファレンスの充実度」は極めて重要な要素となります。SCSSは長い歴史を持ち、豊富な事例とドキュメントが蓄積されています。新しいメンバーが参画した際も、Stack OverflowやGitHubで解決策を見つけやすいという利点があります。

PostCSSの柔軟性は確かに魅力的ですが、その柔軟性ゆえに「プロジェクト固有の設定」が生まれやすく、結果として属人性が高まるリスクを内包しています。私たちがSCSSを推奨するのは、このような「秘伝のタレ化」を防ぎ、持続可能な開発体制を構築するためです。

Nuxt 4のアーキテクチャ変更がもたらす影響

Viteビルダーのデフォルト採用による恩恵

Nuxt 4は2024年7月に正式リリースされ、ビルドツールとしてViteがデフォルトとなりました。この変更により、SCSSの設定方法も若干の調整が必要となりましたが、同時に開発体験は大幅に向上しています。

Viteの高速なHMR（Hot Module Replacement）により、SCSSの変更が即座にブラウザに反映されます。これは開発者の生産性に直接的な影響を与え、スタイリングの微調整にかかる時間を大幅に削減します。特に、デザインシステムの構築やコンポーネントの見た目の調整を頻繁に行うプロジェクトでは、この恩恵は計り知れません。

sass-embeddedによるビルド高速化の実現

Viteはsass-embeddedパッケージが利用可能な場合、自動的にこれを優先して使用します。sass-embeddedはDart Sassのバイナリ版で、従来のJavaScript実装と比較して大幅なパフォーマンス向上を実現しています。

実際のプロジェクトでの計測では、1000を超えるコンポーネントを持つ大規模アプリケーションにおいて、ビルド時間が約30%短縮されました。この高速化は、CI/CDパイプラインの実行時間短縮にも寄与し、開発サイクル全体の効率化につながります。

Nuxt 4でのSCSS共通化実装パターン

基本的な環境構築

まず、必要なパッケージをインストールします。Nuxt 4環境では、SCSSを利用するために必要なのは「sass」パッケージのみです。

# 必須パッケージ
npm install --save-dev sass

# パフォーマンス向上のためのオプション
npm install --save-dev sass-embedded

sass-embeddedはオプショナルですが、プロダクション環境での採用を強く推奨します。ビルド時間の短縮は、デプロイ頻度が高いプロジェクトほど効果を発揮します。

ディレクトリ構造の設計思想

SCSS資産の配置は、プロジェクトの規模と成長性を考慮して設計する必要があります。以下は、実務で実績のある構造です。

assets/
  scss/
    foundation/
      _variables.scss    # カラー、フォント、ブレークポイント等
      _functions.scss    # カスタム関数
      _mixins.scss       # 汎用Mixin
    tokens/
      _colors.scss       # デザイントークン：カラーパレット
      _typography.scss   # デザイントークン：タイポグラフィ
      _spacing.scss      # デザイントークン：スペーシング
    utilities/
      _helpers.scss      # ユーティリティクラス
    main.scss           # グローバルスタイル

この構造は「関心の分離」を意識しており、変数定義、デザイントークン、ユーティリティをそれぞれ独立して管理できます。特にデザイントークンの概念を導入することで、デザインシステムとの連携が容易になります。

namespace無しパターン - シンプルさを優先する場合

小規模から中規模のプロジェクトでは、namespaceを使用しない直接参照パターンが効率的です。

// nuxt.config.ts
export default defineNuxtConfig({
  vite: {
    css: {
      preprocessorOptions: {
        scss: {
          additionalData: `
            @use "~/assets/scss/foundation/_variables.scss" as *;
            @use "~/assets/scss/foundation/_mixins.scss" as *;
            @use "~/assets/scss/foundation/_functions.scss" as *;
          `
        }
      }
    }
  },
  css: ['~/assets/scss/main.scss'] // グローバルスタイルの適用
})

「as *」を使用することで、変数やMixinを直接参照できるようになります。これにより、コンポーネント内でのスタイル記述が簡潔になります。

<template>
  <div class="card">
    <h2 class="card__title">タイトル</h2>
    <p class="card__description">説明文</p>
  </div>
</template>

<style lang="scss" scoped>
.card {
  background-color: $color-surface;
  border-radius: $radius-medium;
  padding: $spacing-large;

  @include elevation(2);

  &__title {
    color: $color-text-primary;
    @include typography-heading-2;
  }

  &__description {
    color: $color-text-secondary;
    margin-top: $spacing-small;
  }
}
</style>

このパターンの利点は、記述量が少なく、直感的であることです。ただし、変数名の衝突リスクがあるため、命名規則の統一が重要になります。

namespace付きパターン - 大規模プロジェクトでの管理

複数のデザインシステムを扱う場合や、サードパーティライブラリとの衝突を避けたい場合は、namespace付きの管理が有効です。

// nuxt.config.ts
export default defineNuxtConfig({
  vite: {
    css: {
      preprocessorOptions: {
        scss: {
          additionalData: `
            @use "~/assets/scss/foundation/_variables.scss" as var;
            @use "~/assets/scss/foundation/_mixins.scss" as mx;
            @use "~/assets/scss/foundation/_functions.scss" as fn;
            @use "~/assets/scss/tokens/_colors.scss" as colors;
            @use "~/assets/scss/tokens/_typography.scss" as type;
          `
        }
      }
    }
  }
})

namespace付きの場合、各リソースの出所が明確になり、大規模チームでの開発において「この変数はどこから来たのか」という疑問が生じません。

<style lang="scss" scoped>
.component {
  background: colors.$background-primary;
  color: colors.$text-primary;

  @include mx.responsive(tablet) {
    padding: var.$spacing-large;
  }

  &__heading {
    @include type.heading-large;
    margin-bottom: fn.calculate-spacing(2);
  }
}
</style>

「注入」と「配信」の使い分け - additionalDataとcss配列の本質的な違い

additionalDataの正しい使い方

Vite公式ドキュメントが明確に示すように、additionalDataは「コード注入」のための機能です。ここに実際のスタイルルールを記述すると、全てのSCSSファイルに重複して注入され、最終的なバンドルサイズが不必要に増大します。

additionalDataには以下の要素のみを含めるべきです。

additionalDataに含めるべき要素の判断基準を明確にすることで、バンドルサイズの最適化が可能になります。

変数定義（$color-primary、$spacing-unitなど）
Mixin定義（@mixin responsive、@mixin elevationなど）
関数定義（@function calculate-rem、@function color-shadeなど）
プレースホルダーセレクタ（%button-base、%card-shadowなど）

これらは「定義」であり、それ自体はCSSを出力しません。一方で、実際のスタイルルールは含めるべきではありません。

css配列によるグローバルスタイルの配信

リセットCSS、ベーススタイル、ユーティリティクラスなど、実際にCSSとして出力したいスタイルは、nuxt.config.tsの「css」配列で指定します。

// nuxt.config.ts
export default defineNuxtConfig({
  css: [
    '~/assets/scss/main.scss'
  ]
})

main.scssの構造例を示します。

// assets/scss/main.scss

// リセット・ノーマライズ
@use 'modern-normalize/modern-normalize.css';

// ベーススタイル
@use './base/typography';
@use './base/forms';

// レイアウトヘルパー
@use './layouts/grid';
@use './layouts/container';

// ユーティリティクラス
@use './utilities/spacing';
@use './utilities/text';
@use './utilities/display';

この分離により、「どこでも使える変数・Mixin」と「実際に適用されるスタイル」が明確に区別され、メンテナンス性が向上します。

パフォーマンス最適化の実践テクニック

Partial（アンダースコア付きファイル）の活用

Sassの「Partial」機能を正しく活用することで、不要なCSSの生成を防げます。アンダースコアで始まるファイル名（_variables.scss）は、それ単体ではCSSファイルを生成しません。

// _variables.scss（Partial）
$primary-color: #007bff;

// variables.scss（通常ファイル）
$primary-color: #007bff;
// このファイルはvariables.cssを生成してしまう

Partialの使用は、ビルド時の処理を効率化し、出力ファイルの管理を簡潔にします。特に大規模プロジェクトでは、この差が顕著に現れます。

@useと@forwardによるモジュール管理

Sass公式は@importを非推奨とし、@useと@forwardの使用を推奨しています。これらの新しいディレクティブは、名前空間の管理とカプセル化を実現します。

// foundation/_index.scss
@forward 'variables';
@forward 'mixins';
@forward 'functions';

// コンポーネントでの使用
@use '~/assets/scss/foundation' as f;

.component {
  color: f.$text-color;
  @include f.responsive(tablet) {
    // タブレット向けスタイル
  }
}

@forwardを使用することで、複数のPartialを単一のエントリーポイントから公開でき、インポート文の簡潔化が図れます。

実装時の落とし穴と対策

javascriptEnabledオプションの誤用

Nuxt 3からNuxt 4への移行時によく見られる誤りとして、「javascriptEnabled: true」の設定があります。これは「Less」プリプロセッサ用のオプションであり、SCSSでは不要です。

// 誤った設定（削除すべき）
export default defineNuxtConfig({
  vite: {
    css: {
      preprocessorOptions: {
        scss: {
          javascriptEnabled: true, // ← これは不要
          additionalData: '...'
        }
      }
    }
  }
})

このオプションを残しても動作に影響はありませんが、設定の意図が不明確になり、メンテナンス性を損なう要因となります。

ソースマップの適切な管理

開発環境とプロダクション環境でソースマップの扱いを分けることで、デバッグ効率と本番パフォーマンスの両立が可能です。

// nuxt.config.ts
export default defineNuxtConfig({
  vite: {
    css: {
      preprocessorOptions: {
        scss: {
          sourceMap: process.env.NODE_ENV === 'development',
          additionalData: '...'
        }
      }
    }
  }
})

開発環境ではソースマップを有効にすることで、ブラウザの開発者ツールでSCSSファイルの該当行を直接確認できます。一方、プロダクション環境では無効化することで、配信サイズを削減できます。

循環参照の回避戦略

SCSSファイル間の循環参照は、ビルドエラーの原因となります。特に@useディレクティブを使用する場合、この問題が顕在化しやすくなります。

循環参照を防ぐための設計原則として、以下の階層構造を維持することが重要です。

基礎層（Foundation）：他のどこからも参照されない基本定義
トークン層（Tokens）：基礎層のみを参照
コンポーネント層（Components）：基礎層とトークン層を参照
ページ層（Pages）：全ての層を参照可能

この階層を守ることで、循環参照のリスクを構造的に排除できます。

開発チームの生産性を最大化するベストプラクティス

スタイルガイドの自動生成

SCSSの変数やMixinが増えてくると、チームメンバーが利用可能なリソースを把握することが困難になります。この課題に対しては、スタイルガイドの自動生成が有効です。

// _colors.scss
/// プライマリーカラー
/// @group colors
$color-primary: #007bff !default;

/// セカンダリーカラー
/// @group colors
$color-secondary: #6c757d !default;

SassDocを使用することで、これらのコメントからドキュメントを自動生成できます。新規メンバーの立ち上がりを早め、既存メンバーの認知負荷を軽減します。

デザイントークンとの連携

デザインシステムとの連携を考慮する場合、デザイントークンをSCSS変数として管理する仕組みが重要になります。

// scripts/generate-tokens.ts
import { readFileSync, writeFileSync } from 'fs';

const tokens = JSON.parse(readFileSync('./design-tokens.json', 'utf-8'));

let scss = '// Auto-generated from design-tokens.json\\\\n\\\\n';

Object.entries(tokens.colors).forEach(([key, value]) => {
  scss += `$color-${key}: ${value};\\\\n`;
});

writeFileSync('./assets/scss/tokens/_generated.scss', scss);

このようなビルドスクリプトを用意することで、デザイナーとエンジニア間の認識齟齬を防ぎ、一貫性のあるUIを実現できます。

コンポーネントカタログとの統合

StorybookやHistoireなどのコンポーネントカタログツールと連携する際、SCSS変数をJavaScriptから参照したいケースがあります。

// _export.scss
:export {
  primaryColor: $color-primary;
  secondaryColor: $color-secondary;
  spacingUnit: $spacing-unit;
}

CSS Modulesの:export機能を活用することで、SCSS変数をJavaScriptモジュールとしてインポートできます。これにより、スタイルとロジックの一貫性を保てます。

Nuxt 4移行時のチェックリスト

既存のNuxt 3プロジェクトをNuxt 4に移行する際の、SCSS関連の確認事項をまとめます。

移行作業を効率的に進めるために、以下のチェックリストを活用してください。

nuxt.config.tsからjavascriptEnabledオプションを削除
@importディレクティブを@useまたは@forwardに置き換え
Partialファイル名にアンダースコアを追加（variables.scss → _variables.scss）
additionalDataに実スタイルが含まれていないか確認
sass-embeddedパッケージの導入検討
ソースマップ設定の環境別分離
循環参照のチェックと解消

まとめと今後の展望

Nuxt 4におけるSCSSの共通化は、単なる技術的な設定以上の価値を持ちます。適切な設計と実装により、開発効率の向上、保守性の確保、そしてチーム全体の生産性向上を実現できます。

特に重要なのは、「注入（additionalData）」と「配信（css配列）」の使い分けを理解し、それぞれの役割に応じた適切な利用をすることです。また、namespace付き/なしの選択は、プロジェクトの規模と成長性を考慮して判断する必要があります。

今後、Web ComponentsやCSS-in-JSソリューションとの共存も視野に入れながら、SCSSの強みを活かした開発を続けていくことが重要です。デザインシステムの成熟とともに、スタイリング戦略も進化し続けるでしょう。

私たちは、技術の選択において「流行」ではなく「本質的な価値」を重視しています。SCSSがもたらす開発効率と保守性の向上は、プロジェクトの成功に直結する重要な要素です。この記事で紹介した手法を活用し、より良いフロントエンド開発を実現していただければ幸いです。

この記事を書いた人

ソリューションアーキテクト益子竜与志

複数のITベンチャーで技術責任者／経営企画を歴任し、事業戦略とプロダクト成長を主導。2017年にRagate株式会社を創業し、サーバーレス技術の黎明期よりAWS・サーバーレス開発プロジェクトを牽引し、AWS Top Engineers 2024 ( Service ) ・AWS Rising Star Partners of the Year – Japan賞を受賞。経営課題/戦略を起点としたDX戦略策定とクラウドシステムデリバリを強みに、SMB市場を中心に数多くの企業変革を支援。GLOBIS経営大学院MBAで培った経営戦略・マーケティングミックスの知見と、AWS／先端技術の深い専門性を掛け合わせ、価値創出を加速させている。

【保有資格・認定】