Nuxt 레이어 작성하기

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

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

export default defineNuxtConfig({})

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

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

기본 예시

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

  <template>
    <BaseComponent/>
  </template>

  export default defineNuxtConfig({
    // base nuxt.config.ts에서 확장 중!
    app: {
      head: {
        title: '설정 확장은 재미있어요!',
        meta: [
          { name: 'description', content: 'Nuxt의 extends 기능을 사용하고 있어요!' }
        ],
      }
    }
  })

  <template>
    <h1>컴포넌트 확장은 재미있어요!</h1>
  </template>

스타터 템플릿

시작하려면 nuxt/starter/layer template로 레이어를 초기화할 수 있습니다. 이 템플릿은 확장할 수 있는 기본 구조를 생성합니다. 터미널에서 다음 명령어를 실행하여 시작하세요:

npm create nuxt -- --template layer nuxt-layer

다음 단계는 README 지침을 따라 진행하세요.

레이어 배포하기

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

Git 저장소

Nuxt 레이어를 공유하기 위해 git 저장소를 사용할 수 있습니다. 몇 가지 예시는 다음과 같습니다:

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

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

npm 패키지

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

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

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

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

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

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

팁

이름이 지정된 레이어 별칭

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

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

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

이렇게 하면 #layers/example 별칭이 생성되어 해당 레이어를 가리킵니다.

상대 경로와 별칭

레이어의 컴포넌트와 컴포저블에서 글로벌 별칭(~/, @/ 등)을 사용하여 import할 때, 이 별칭들은 사용자의 프로젝트 경로를 기준으로 해석된다는 점에 유의하세요. 이를 우회하려면 상대 경로를 사용하거나, 이름이 지정된 레이어 별칭을 사용할 수 있습니다.

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

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

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

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

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

내부 배열 nuxt.options._layers를 사용하여 모듈에 대한 커스텀 멀티 레이어 처리를 지원할 수 있습니다.

export default defineNuxtModule({
  setup(_options, nuxt) {
    for (const layer of nuxt.options._layers) {
      // 각 레이어에 대해 커스텀 디렉터리 존재 여부를 확인하여 확장할 수 있습니다
      console.log('Custom extension for', layer.cwd, layer.config)
    }
  }
})

참고:

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

더 깊이 알아보기

설정 로딩 및 extends 지원은 unjs/c12에서 처리하며, unjs/defu로 병합되고, 원격 git 소스는 unjs/giget로 지원됩니다. 더 자세한 내용은 문서와 소스 코드를 참고하세요.