프로젝트 디렉토리 구성 가이드 – 캐모마일 개발자 커뮤니티

assets

Nuxt 3에서 assets 폴더는 정적 파일이 아닌 애플리케이션의 컴파일이 필요한 파일들을 담기 위한 곳입니다. 여기에는 스타일 시트(예: CSS, SCSS, SASS), 이미지, 또는 웹팩을 통해 빌드되어야 하는 기타 자산들이 포함됩니다.

assets 폴더의 주요 사용 사례는 다음과 같습니다:

스타일: CSS, SCSS, SASS, LESS 등의 스타일 파일을 포함시킬 수 있으며, 이러한 파일들은 Nuxt.js 빌드 프로세스에 의해 처리되어 적용됩니다. assets 폴더에 있는 스타일 시트는 Vue 파일의 <style> 태그 내부 또는 외부 스타일 시트로 import하여 사용할 수 있습니다.
이미지 및 폰트: assets 폴더 내의 이미지 및 폰트와 같은 파일들은 웹팩 로더를 통해 최적화되고 URL로 변환됩니다. 이렇게 변환된 URL은 캐싱이 용이하고, 필요에 따라 자동으로 인라인으로 전환되거나, 배포를 위해 별도의 파일로 추출될 수 있습니다.
자바스크립트: 클라이언트 사이드 라이브러리나 유틸리티 함수 같은 자바스크립트 파일이 이 폴더에 포함될 수 있으며, 이 또한 웹팩을 통해 빌드되고, 모듈로 import하여 사용할 수 있습니다.
프로세싱: assets 폴더에 있는 파일들은 로더와 플러그인을 사용하여 최적화될 수 있습니다. 예를 들어, 이미지는 크기가 조정되거나 압축될 수 있고, 스타일 시트는 전처리(pre-process) 될 수 있습니다.

assets 폴더 내의 파일을 사용하는 방법은 다음과 같습니다:

Vue 파일 내에서: assets 폴더 내의 파일을 Vue 컴포넌트의 템플릿에서 바로 참조할 수 있습니다. 예를 들어, <img src="~/assets/image.png">와 같이 사용할 수 있습니다. 여기서 ~는 프로젝트의 루트 디렉토리를 가리킵니다.
자바스크립트 내에서: 스크립트에서 import 구문을 사용해 assets 폴더의 파일을 가져올 수 있습니다. 예를 들어, import myStyle from '~/assets/css/style.css';와 같이 사용할 수 있습니다.
CSS 내에서: CSS 파일 내에서 url() 함수를 사용하여 assets 폴더 내의 이미지나 폰트 파일을 참조할 수 있습니다. 예를 들어, background: url('~assets/image.png');와 같이 사용할 수 있습니다.

assets 폴더에 위치한 파일은 정적 파일로 처리되지 않기 때문에, URL을 통해 직접 접근할 수는 없습니다. 이들은 Nuxt.js의 빌드 시스템을 통해 처리되고, 결과적으로 생성된 정적 파일들은 .nuxt/dist/client 폴더에 위치하게 됩니다.

정적 파일을 다루기 위해서는 static 폴더를 사용합니다. static 폴더에 있는 파일들은 웹팩 또는 기타 빌드 프로세스 없이 서버의 루트 URL에서 직접 접근할 수 있습니다.

components

Nuxt 3에서 components 폴더는 Vue 컴포넌트를 저장하는 곳입니다. 이 폴더 내의 컴포넌트들은 Nuxt 애플리케이션의 다양한 부분에서 재사용될 수 있는 Vue.js의 싱글 파일 컴포넌트(Single File Components, .vue 파일)로 구성됩니다.

다음은 components 폴더에 대한 핵심적인 특징들입니다:

자동 등록: Nuxt는 기본적으로 components 폴더 내의 Vue 컴포넌트들을 자동으로 등록합니다. 이는 개발자가 매번 import 구문을 사용하여 컴포넌트를 가져오지 않아도 되며, 어떠한 페이지 또는 레이아웃에서도 직접 컴포넌트 태그를 사용할 수 있다는 것을 의미합니다.
디렉토리 구조: 컴포넌트들을 components 폴더 내에서 다양한 하위 폴더로 정리할 수 있습니다. 이 구조는 컴포넌트의 이름으로 반영되며, 디렉토리 구조를 활용하여 관련 컴포넌트를 쉽게 찾고 관리할 수 있도록 도와줍니다.
동적 임포트: 큰 크기의 컴포넌트나 자주 사용되지 않는 컴포넌트의 경우, Nuxt는 이들을 동적으로 불러와서 초기 로드 시간을 줄이는 코드 스플리팅을 자동으로 수행합니다.
Props 검증 및 IntelliSense: .vue 파일 내에서 props를 정의할 때, 타입 검증 등의 기능을 사용할 수 있습니다. 이는 컴포넌트의 사용성을 높이고, 개발 중 발생할 수 있는 오류를 줄이는 데 도움을 줍니다. 또한, IDE에서는 이러한 props 정의를 통해 자동 완성 및 IntelliSense 기능을 제공합니다.
전역과 지역 컴포넌트: 기본적으로 components 폴더에 있는 컴포넌트들은 전역으로 등록됩니다. 그러나 특정 페이지에서만 사용되는 컴포넌트의 경우, 해당 페이지의 디렉토리 내에 컴포넌트를 위치시켜 지역 컴포넌트로 관리할 수 있습니다.
컴포넌트 접두어: 큰 애플리케이션에서는 컴포넌트의 접두어를 사용하여 컴포넌트의 범주를 명확히 할 수 있습니다. 예를 들어, BaseButton.vue, TheHeader.vue와 같이 범용적인 컴포넌트나 레이아웃에 관련된 컴포넌트에 접두어를 사용할 수 있습니다.

이러한 기능들은 개발자가 애플리케이션의 UI를 구성할 때 보다 효율적이고 조직적으로 작업할 수 있도록 도와줍니다. Nuxt 3에서는 이러한 컴포넌트 시스템을 사용함으로써 개발 프로세스를 간소화하고, 코드 재사용성을 높이며, 애플리케이션의 유지보수성을 개선할 수 있습니다.

composables

Nuxt 3에서 composables 폴더는 Vue 3의 Composition API를 활용한 로직을 재사용하기 위한 함수들을 저장하는 곳입니다. 이 폴더는 Nuxt 애플리케이션 내에서 공통적으로 사용될 수 있는 "composable" 함수들을 포함합니다. Composable 함수들은 상태 관리, API 호출, 반응형 참조(refs), 반응성 있는 사이드 이펙트(watchers), 그리고 기타 컴포지션 API 로직을 캡슐화하는데 사용됩니다.

composables 폴더의 주요 사용 사례는 다음과 같습니다:

재사용 가능한 로직: 공통적으로 사용되는 반응형 데이터, 메서드 등을 정의하고 여러 컴포넌트에서 재사용할 수 있습니다.
상태 관리: Vuex를 사용하지 않고도, 간단한 상태 관리 로직을 composable 함수로 작성하여 사용할 수 있습니다.
API 호출: 데이터를 가져오거나 보내는 API 호출 로직을 composable로 작성하여, 여러 곳에서 재사용할 수 있습니다.
사이드 이펙트 관리: watch나 watchEffect를 사용하는 로직을 composable로 만들어서 관리할 수 있습니다.
컴포넌트 간의 데이터 공유: 컴포넌트 간에 데이터를 공유하거나, 전역 상태를 만드는데 사용할 수 있습니다.

예를 들어, useUser composable 함수는 사용자의 로그인 상태를 관리하고, 사용자 정보를 불러오는 로직을 포함할 수 있습니다. 그리고 이 composable을 사용하여 여러 컴포넌트에서 사용자 관련 로직을 쉽게 재사용할 수 있습니다.

// composables/useUser.js

import { ref } from 'vue'

const user = ref(null)

export const useUser = () => {
  const fetchUser = async () => {
    const response = await fetch('/api/user')
    user.value = await response.json()
  }

  const logout = () => {
    user.value = null
  }

  return { user, fetchUser, logout }
}

위의 composable 함수는 사용자 데이터를 불러오는 fetchUser 메서드와 로그아웃하는 logout 메서드를 제공합니다. 이 함수를 여러 컴포넌트에서 사용할 수 있어, 중복 코드를 줄이고, 테스트가 용이하며, 코드의 가독성을 높일 수 있습니다.

이처럼 composables 폴더를 사용하면, Nuxt 애플리케이션을 더욱 모듈화하고, 코드 재사용성을 높이며, 관심사의 분리를 통해 유지보수를 용이하게 할 수 있습니다.

layouts

Nuxt 3에서 layouts 폴더는 애플리케이션의 레이아웃을 정의하는 파일들을 저장하는 곳입니다. 레이아웃은 웹 페이지의 구조를 결정하는 Vue 컴포넌트로, 여러 페이지에 걸쳐 공통적으로 사용되는 헤더, 푸터, 사이드바와 같은 UI 요소를 포함할 수 있습니다.

레이아웃을 사용함으로써, 페이지의 내용이 변경되더라도 레이아웃의 구조는 유지되기 때문에, 코드의 재사용성을 높이고 애플리케이션의 일관성을 유지할 수 있습니다. Nuxt.js는 기본 레이아웃을 제공하며, 사용자가 직접 추가로 정의할 수도 있습니다.

레이아웃 폴더의 사용 방법:

기본 레이아웃: layouts/default.vue 파일은 애플리케이션의 기본 레이아웃을 정의합니다. 페이지에서 다른 레이아웃을 명시적으로 지정하지 않는 한, 모든 페이지는 이 레이아웃을 사용합니다.
커스텀 레이아웃: 사용자는 여러 개의 레이아웃을 생성할 수 있습니다. 예를 들어, layouts/blog.vue는 블로그 페이지에 대한 특별한 레이아웃을 정의할 때 사용될 수 있습니다.
레이아웃 사용: 페이지 컴포넌트에서 layout 속성을 통해 사용할 레이아웃을 지정할 수 있습니다. 예를 들어, pages/blog.vue 내부에서 <script setup> 블록 안에 definePageMeta({ layout: 'blog' })를 추가함으로써 blog 레이아웃을 해당 페이지에 적용할 수 있습니다.
슬롯: 레이아웃 컴포넌트에서 <slot/> 요소를 사용하여 페이지의 실제 내용이 들어갈 위치를 지정합니다. 페이지 컴포넌트의 템플릿 내용은 레이아웃의 <slot/> 위치에 삽입되어 최종적으로 사용자에게 보여집니다.

레이아웃 폴더의 예제 구조는 다음과 같습니다:

layouts/
-- default.vue     # 모든 페이지에서 기본적으로 사용될 레이아웃
-- blog.vue        # 블로그 페이지에 사용할 커스텀 레이아웃
-- admin.vue       # 관리자 페이지에 사용할 커스텀 레이아웃

예제 default.vue 파일:

<template>
  <div>
    <header>
      <!-- 헤더 내용 -->
    </header>

    <main>
      <slot/>
      <!-- 페이지 컴포넌트의 내용이 여기에 삽입됩니다. -->
    </main>

    <footer>
      <!-- 푸터 내용 -->
    </footer>
  </div>
</template>

<script setup>
// 여기에 스크립트 로직을 추가할 수 있습니다.
</script>

<style>
/* 여기에 스타일을 추가할 수 있습니다. */
</style>

이런 식으로 layouts 폴더를 활용하면, 개발자는 Nuxt 애플리케이션의 다양한 페이지에 공통적인 레이아웃을 쉽고 효율적으로 적용할 수 있습니다.

middleware

Nuxt 3에서 middleware 폴더는 애플리케이션의 라우팅 프로세스 중간에 특정 로직을 실행하기 위한 파일들을 저장하는 곳입니다. 미들웨어는 사용자가 페이지를 요청할 때마다 실행되는 함수로, 이 함수들은 주로 사용자 인증 확인, 페이지 접근 권한 검사, 리다이렉션 설정, 로깅, 데이터 사전 처리 등의 작업을 수행합니다.

Nuxt.js의 미들웨어는 서버 측(SSR), 클라이언트 측(SPA), 또는 정적 생성(SSG)에 사용될 때 실행될 수 있으며, 개별 페이지 또는 애플리케이션 전체에 적용할 수 있습니다.

미들웨어 사용 방법:

전역 미들웨어: nuxt.config.js 파일에서 router.middleware 속성을 사용하여 전역 미들웨어를 설정할 수 있습니다. 이렇게 설정된 미들웨어는 모든 라우트 변경 시에 실행됩니다.
레이아웃 미들웨어: 특정 레이아웃에 미들웨어를 적용하여, 해당 레이아웃을 사용하는 모든 페이지에 미들웨어를 실행시킬 수 있습니다.
페이지 미들웨어: 개별 페이지 컴포넌트 내에서 middleware 속성을 사용하여 미들웨어를 지정할 수 있습니다. 이 미들웨어는 해당 페이지가 로드될 때만 실행됩니다.

미들웨어 함수는 라우트가 최종적으로 확정되기 전에 호출되며, 라우트를 변경하거나 중단할 수 있는 권한을 가집니다.

middleware 폴더의 예제 구조는 다음과 같습니다:

middleware/
-- auth.js          # 사용자 인증을 확인하는 미들웨어
-- log.js           # 로깅을 수행하는 미들웨어
-- stats.js         # 통계와 관련된 데이터를 처리하는 미들웨어

예제 auth.js 미들웨어:

export default defineNuxtMiddleware((context) => {
  const { store, redirect } = context;

  // 사용자가 로그인하지 않은 경우 로그인 페이지로 리다이렉트
  if (!store.state.auth.loggedIn) {
    return redirect('/login');
  }
});

위의 예제에서 defineNuxtMiddleware 함수는 Nuxt 3에서 미들웨어를 정의할 때 사용합니다. 이 함수는 컨텍스트 객체를 매개변수로 받아, 그 안에는 store, redirect, route 등 미들웨어가 실행될 때 활용할 수 있는 여러 속성들이 포함되어 있습니다.

미들웨어는 매우 유연하게 설정할 수 있기 때문에, 개발자는 애플리케이션의 요구 사항에 맞게 사용자 요청을 효과적으로 제어할 수 있습니다.

pages

Nuxt 3의 pages 폴더는 애플리케이션의 페이지를 정의하는 Vue 컴포넌트를 저장하는 중요한 부분입니다. 이 폴더의 구조와 파일 이름은 Nuxt의 라우팅 시스템에 직접적인 영향을 미칩니다. Nuxt는 pages 폴더 내의 파일 구조를 기반으로 자동으로 애플리케이션의 라우트를 생성합니다.

여기 pages 폴더에 관한 몇 가지 핵심 사항입니다:

파일 기반 라우팅: 각 .vue 파일은 URL 경로에 해당하는 라우트를 자동으로 생성합니다. 예를 들어, pages/about.vue 파일은 /about URL에 대응하는 라우트를 만듭니다.
동적 라우트: 동적 세그먼트를 다루기 위해 파일 또는 폴더 이름에 대괄호를 사용합니다. 예를 들어, pages/users/[id].vue는 /users/1, /users/2 등의 경로로 매핑되며, 각각의 경로는 다른 id 파라미터를 가질 수 있습니다.
중첩 라우트: 폴더 구조를 사용하여 중첩된 URL 구조를 생성할 수 있습니다. pages/users/_id/index.vue 파일은 /users/1/, /users/2/ 등의 경로로 매핑되며, 중첩 라우트를 생성합니다.
에러 페이지: pages 폴더 내에 error.vue 파일을 추가함으로써 커스텀 에러 페이지를 정의할 수 있습니다. 이 파일은 라우팅 오류가 발생했을 때 표시되는 페이지입니다.
레이아웃: 페이지 컴포넌트는 layouts 폴더에 정의된 레이아웃을 사용할 수 있습니다. 페이지 컴포넌트에서 레이아웃을 지정하지 않으면, 기본적으로 layouts/default.vue 레이아웃이 적용됩니다.
비동기 데이터: asyncData 또는 fetch 함수를 사용하여, 서버 사이드에서 페이지에 필요한 데이터를 비동기적으로 가져올 수 있습니다. 이 데이터는 라우트가 변경되기 전에 불러와지며, 컴포넌트의 데이터로 설정됩니다.

pages 폴더의 예제 구조는 다음과 같습니다:

pages/
--| users/
-----| _id.vue
-----| index.vue
--| about.vue
--| index.vue

이 구조는 다음과 같은 URL 패턴을 생성합니다:

/ → pages/index.vue
/about → pages/about.vue
/users → pages/users/index.vue
/users/:id → pages/users/_id.vue (:id는 동적 파라미터입니다)

pages 폴더를 통해 Nuxt 3는 라우트 설정 파일 없이도 복잡한 라우팅 시스템을 쉽게 구축할 수 있도록 돕습니다. 개발자는 단순히 파일을 추가하고 이름을 지정함으로써 라우트를 확장할 수 있고, 이는 개발 과정을 더욱 빠르고 효율적으로 만듭니다.