Nuxt 3 전역 Style 및 variable 적용 (SCSS)

Hyeon·2025년 7월 25일

Nuxt

목록 보기

2/5

Nuxt 3 프로젝트에서 SCSS를 활용해 전역 스타일과 변수를 설정하려 했으나, 예상대로 작동하지 않는 문제가 발생했습니다.
공식 문서를 참고해 다양한 방법을 시도한 결과, 다음과 같은 방식으로 해결할 수 있었습니다.

스타일 구조

전역 스타일은 styles/ 폴더에 다음과 같이 구성했습니다.

global.scss: 각종 스타일 파일을 @forward로 모아둔 파일입니다.

/* global.scss */
@forward './utils/utils';
@forward 'fonts';
@forward 'palettes';
@forward 'reset';

index.scss: global.scss를 한 번 더 @forward 하여 외부에서 사용하기 쉽게 구성한 진입점입니다.

/* index.scss */
@forward 'global';

Nuxt.config.ts

위 파일들을 Nuxt에서 전역으로 불러오기 위해 다음과 같이 nuxt.config.ts에 설정했습니다.

export default defineNuxtConfig({
	css: ['~/styles/index.scss'],
})

Error

그러나 컴포넌트의 <style> 영역에서 선언한 변수를 사용하려 할 때, 아래와 같은 오류가 발생했습니다.

  [sass] Undefined variable.
  4 │     background-color: $support-04;

additionalData

공식 문서를 참고해보면, SCSS 변수 사용을 위해 vite 설정의 additionalData를 활용하라고 안내되어 있습니다.

/* colors.scss */
$primary: #49240F;
$secondary: #E4A79D;

// nuxt.config.ts
export default defineNuxtConfig({
  vite: {
    css: {
      preprocessorOptions: {
        scss: {
          additionalData: '@use "~/assets/_colors.scss" as *;'
        }
      }
    }
  }
})

Nuxt.config.ts

이에 따라 아래와 같이 설정을 변경했습니다.

export default defineNuxtConfig({
	vite: {
      css: {
        preprocessorOptions: {
          scss: {
            additionalData: '@use "~/styles/index.scss" as *;',
          },
        },
      },
  },
})

이제 변수와 믹스인 등은 정상적으로 인식되었지만, 또 다른 문제가 발생했습니다.

⚠️ 전역 스타일이 실제로 적용되지 않음

아래와 같이 reset.scss에서 정의한 전역 스타일들이 실제 화면에 적용되지 않았습니다.

/* reset.scss */
* {
  margin: 0;
  padding: 0;
  box-sizing: border-box;
}

html,
body {
  @include font-family('sans');

  width: 100%;
  height: 100%;
}

a,
a:active,
a:hover {
  text-decoration: none;
  color: inherit;
}

특히, html, body, * 등 기본 요소에 대한 스타일이 적용되지 않았습니다. 반면 Vue 컴포넌트 내부에서 사용하는 a 태그에는 스타일이 정상적으로 적용되는 모습을 볼 수 있었습니다.

이러한 현상은 vite.css.preprocessorOptions.scss.additionalData에 정의된 SCSS는 스타일을 실제로 브라우저에 주입하지 않기 때문입니다. 즉, 이 설정은 변수와 믹스인 등 선언적 자원만 전달할 뿐, 실제 스타일은 렌더링되지 않습니다.

선언과 스타일 분리하기

이를 해결하기 위해 다음과 같이 Nuxt 설정을 두 부분으로 나누어 선언했습니다.

// nuxt.config.ts
export default defineNuxtConfig({
	// 1. 전역 스타일을 실제로 브라우저에 적용 (reset 등)
  	css: ['~/styles/ui/index.scss'],
    
    // 2. SCSS 변수, mixin 등을 전역으로 주입
	vite: {
      css: {
        preprocessorOptions: {
          scss: {
            additionalData: '@use "~/styles/index.scss" as *;',
          },
        },
      },
  	},
})