Nuxt 레이어 작성하기

Nuxt는 기본 파일, 설정 등을 확장할 수 있는 강력한 시스템을 제공합니다.

Nuxt 레이어는 모노레포 내에서, 혹은 git 저장소나 npm 패키지로부터 부분적인 Nuxt 애플리케이션을 공유하고 재사용할 수 있게 해주는 강력한 기능입니다. 레이어의 구조는 표준 Nuxt 애플리케이션과 거의 동일하여 작성하고 유지 관리하기 쉽습니다.

Read more in Docs > 4 X > Getting Started > Layers.

최소한의 Nuxt 레이어 디렉터리는 레이어임을 나타내기 위해 nuxt.config.ts 파일을 포함해야 합니다.

base/nuxt.config.ts

export default defineNuxtConfig({})

추가로, 레이어 디렉터리 내의 특정 파일들은 자동으로 스캔되어 이 레이어를 확장하는 프로젝트에서 Nuxt에 의해 사용됩니다.

app/components/* - 기본 컴포넌트 확장
app/composables/* - 기본 composable 확장
app/layouts/* - 기본 레이아웃 확장
app/middleware/* - 기본 미들웨어 확장
app/pages/* - 기본 페이지 확장
app/plugins/* - 기본 플러그인 확장
app/utils/* - 기본 유틸리티 확장
app/app.config.ts - 기본 앱 설정 확장
server/* - 기본 서버 엔드포인트 & 미들웨어 확장
nuxt.config.ts- 기본 nuxt 설정 확장

기본 예제

nuxt.config.ts

export default defineNuxtConfig({
  extends: [
    './base',
  ],
})

레이어 우선순위

여러 레이어로부터 확장할 때는, 어떤 순서로 덮어쓰기가 되는지 이해하는 것이 중요합니다. 우선순위가 높은 레이어가 동일한 파일이나 컴포넌트를 정의할 경우 우선순위가 낮은 레이어를 덮어씁니다.

우선순위는 높은 것에서 낮은 것 순으로 다음과 같습니다:

프로젝트 파일 - 항상 가장 높은 우선순위를 가집니다
~~/layers 디렉터리의 자동 스캔된 레이어 - 알파벳 역순 정렬 (Z가 A보다 우선순위가 높음)
설정의 extends 내 레이어 - 첫 번째 항목이 두 번째 항목보다 우선순위가 높음

각 방식을 언제 사용할까

extends - 외부 의존성(npm 패키지, 원격 저장소)이나 프로젝트 디렉터리 밖의 레이어에 사용
~~/layers 디렉터리 - 프로젝트의 일부인 로컬 레이어에 사용

자동 스캔된 레이어의 순서를 제어해야 한다면, 숫자를 접두사로 붙일 수 있습니다: ~/layers/1.z-layer, ~/layers/2.a-layer. 이렇게 하면 2.a-layer가 1.z-layer보다 더 높은 우선순위를 갖게 됩니다.

예제

nuxt.config.ts

export default defineNuxtConfig({
  extends: [
    // 프로젝트 외부의 로컬 레이어
    '../base',
    // NPM 패키지
    '@my-themes/awesome',
    // 원격 저장소
    'github:my-themes/awesome#v1',
  ],
})

~~/layers/custom도 있는 경우, 우선순위는 다음과 같습니다:

프로젝트 파일 (가장 높음)
~~/layers/custom
../base
@my-themes/awesome
github:my-themes/awesome#v1 (가장 낮음)

이는 프로젝트 파일이 어떤 레이어보다도 우선하여 덮어쓰며, ~~/layers/custom이 extends 내의 모든 항목을 덮어쓴다는 의미입니다.

레이어 배포

원격 소스나 npm 패키지를 사용하여 레이어를 배포하고 공유할 수 있습니다.

Git 저장소

Git 저장소를 사용해 Nuxt 레이어를 공유할 수 있습니다. 예시는 다음과 같습니다:

nuxt.config.ts

export default defineNuxtConfig({
  extends: [
    // GitHub 원격 소스
    'github:username/repoName',
    // /base 디렉터리 내의 GitHub 원격 소스
    'github:username/repoName/base',
    // dev 브랜치의 GitHub 원격 소스
    'github:username/repoName#dev',
    // v1.0.0 태그의 GitHub 원격 소스
    'github:username/repoName#v1.0.0',
    // GitLab 원격 소스 예시
    'gitlab:username/repoName',
    // Bitbucket 원격 소스 예시
    'bitbucket:username/repoName',
  ],
})

비공개 원격 소스를 레이어로 확장하려면, 토큰을 제공하기 위해 GIGET_AUTH=<token> 환경 변수를 추가해야 합니다.

자가 호스팅된 GitHub 또는 GitLab 인스턴스의 원격 소스를 레이어로 확장하려면, GIGET_GITHUB_URL=<url> 또는 GIGET_GITLAB_URL=<url> 환경 변수로 해당 URL을 제공해야 합니다. 또는 nuxt.config에서 auth 옵션을 직접 설정할 수도 있습니다.

원격 소스를 레이어로 확장하는 경우, Nuxt 외부에서는 해당 레이어의 의존성에 접근할 수 없다는 점을 유의하세요. 예를 들어, 원격 레이어가 eslint 플러그인에 의존하는 경우, 이 플러그인은 eslint 설정에서 사용할 수 없습니다. 이는 이러한 의존성이 패키지 매니저에서 접근할 수 없는 특수 위치(node_modules/.c12/layer_name/node_modules/)에 위치하기 때문입니다.

git 원격 소스를 사용할 때, 레이어에 npm 의존성이 있고 이를 설치하고 싶다면, 레이어 옵션에 install: true를 지정하여 설치할 수 있습니다.

nuxt.config.ts

export default defineNuxtConfig({
  extends: [
    ['github:username/repoName', { install: true }],
  ],
})

npm 패키지

Nuxt 레이어를, 확장하려는 파일과 의존성을 포함하는 npm 패키지로 배포할 수 있습니다. 이를 통해 설정을 다른 사람과 공유하거나, 여러 프로젝트에서 사용하거나, 비공개로 사용할 수 있습니다.

npm 패키지로부터 확장하려면, 모듈이 npm에 배포되어 있고 사용자의 프로젝트에 devDependency로 설치되어 있어야 합니다. 그런 다음 모듈 이름을 사용해 현재 nuxt 설정을 확장할 수 있습니다:

nuxt.config.ts

export default defineNuxtConfig({
  extends: [
    // 스코프가 있는 Node 모듈
    '@scope/moduleName',
    // 또는 모듈 이름만
    'moduleName',
  ],
})

레이어 디렉터리를 npm 패키지로 배포하려면, package.json에 올바른 속성이 채워져 있는지 확인해야 합니다. 이렇게 해야 패키지가 배포될 때 파일이 포함됩니다.

package.json

{
  "name": "my-theme",
  "version": "1.0.0",
  "type": "module",
  "main": "./nuxt.config.ts",
  "dependencies": {},
  "devDependencies": {
    "nuxt": "^3.0.0"
  }
}

레이어에서 import하는 모든 의존성은 반드시 dependencies에 명시적으로 추가해야 합니다. nuxt 의존성과, 배포 전에 레이어를 테스트하는 데만 사용되는 항목은 devDependencies 필드에 남겨두어야 합니다.

이제 모듈을 npm에 공개 또는 비공개로 배포할 수 있습니다.

레이어를 비공개 npm 패키지로 배포하는 경우, 노드 모듈을 다운로드하기 위해 npm에 로그인하여 인증을 완료해야 합니다.

팁

이름이 있는 레이어 별칭

자동 스캔된 레이어(~~/layers 디렉터리의 레이어)는 자동으로 별칭을 생성합니다. 예를 들어, ~~/layers/test 레이어는 #layers/test를 통해 접근할 수 있습니다.

다른 레이어에 대해 이름이 있는 레이어 별칭을 만들고 싶다면, 레이어 설정에서 name을 지정할 수 있습니다.

nuxt.config.ts

export default defineNuxtConfig({
  $meta: {
    name: 'example',
  },
})

이렇게 하면 레이어를 가리키는 #layers/example 별칭이 생성됩니다.

상대 경로와 별칭

레이어의 컴포넌트와 composable에서 전역 별칭(~/, @/ 등)을 사용해 import할 때, 이 별칭들은 사용자 프로젝트의 경로를 기준으로 해석된다는 점에 유의하세요. 해결 방법으로, 상대 경로를 사용해 import하거나 이름이 있는 레이어 별칭을 사용할 수 있습니다.

또한 레이어의 nuxt.config 파일에서 상대 경로를 사용할 때(중첩된 extends는 예외), 이 경로들은 레이어가 아닌 사용자 프로젝트를 기준으로 해석됩니다. 해결 방법으로, nuxt.config에서 완전히 해석된 전체 경로를 사용하세요:

nuxt.config.ts

import { fileURLToPath } from 'node:url'
import { dirname, join } from 'node:path'

const currentDir = dirname(fileURLToPath(import.meta.url))

export default defineNuxtConfig({
  css: [
    join(currentDir, './app/assets/main.css'),
  ],
})

Nuxt 모듈을 위한 멀티 레이어 지원

Nuxt Kit의 getLayerDirectories 유틸리티를 사용해, 모듈에서 커스텀 멀티 레이어 처리를 지원할 수 있습니다.

modules/my-module.ts

import { defineNuxtModule, getLayerDirectories } from 'nuxt/kit'

export default defineNuxtModule({
  setup (_options, nuxt) {
    const layerDirs = getLayerDirectories()

    for (const [index, layer] of layerDirs.entries()) {
      console.log(`Layer ${index}:`)
      console.log(`  Root: ${layer.root}`)
      console.log(`  App: ${layer.app}`)
      console.log(`  Server: ${layer.server}`)
      console.log(`  Pages: ${layer.appPages}`)
      // ... 다른 디렉터리들
    }
  },
})

메모:

배열에서 앞쪽 항목일수록 우선순위가 높으며, 뒤쪽 항목을 덮어씁니다
사용자 프로젝트가 배열의 첫 번째 항목입니다

더 깊이 들어가기

설정 로딩과 extends 지원은 unjs/c12에 의해 처리되며, unjs/defu를 사용해 병합되고, 원격 git 소스는 unjs/giget을 사용해 지원됩니다. 더 알아보려면 문서와 소스 코드를 확인하세요.

GitHub에서 레이어 지원을 더 개선하기 위한 진행 중인 개발을 확인해 보세요.

Was this helpful?

Report an issue or Edit this page on GitHub

NuxtApp

Nuxt에서는 컴포저블, 컴포넌트 및 플러그인 내에서 런타임 앱 컨텍스트에 접근할 수 있습니다.

디버깅

Nuxt에서는 브라우저와 IDE에서 직접 애플리케이션 디버깅을 시작할 수 있습니다.