自動引入 (Auto-imports)

Nuxt 的核心魔法之一。只要將檔案放入指定目錄 (components, composables, utils)，就能在全專案直接使用，完全不需要手動 import。

自動引入機制

在傳統 Vue 專案中，你必須手動引入每個用到的元件和函式。 Nuxt 自動化了這個過程，掃描 components/、composables/ 與 utils/ 目錄，並生成型別定義 (Type Definitions)。

Standard Vue

<script setup>
import { ref, computed } from 'vue'
import { useRoute } from 'vue-router'
import AppHeader from './components/AppHeader.vue'

const count = ref(0)
const route = useRoute()
</script>

Nuxt Way

<script setup>
// Vue API, Vue Router 與 Components
// 全部自動引入！

const count = ref(0)
const route = useRoute()
</script>

這不是魔法，是 TypeScript： Nuxt 會在 .nuxt/imports.d.ts 中生成全域型別宣告。所以當你輸入 ref 時，VS Code 能知道它是什麼並提供自動補全。

元件 (Components)

Nuxt 會根據目錄層級自動組合元件名稱，使用 PascalCase (大駝峰) 格式。這有助於避免命名衝突，並讓元件來源一目瞭然。

Directory to Component Name

components/
- Header.vue<Header />
- base/
  - Button.vue<BaseButton />
- blog/post/
  - Card.vue<BlogPostCard />

重複名稱優化： 如果檔名與目錄名相同 (e.g., components/Base/Base.vue)， Nuxt 會自動簡化為 <Base /> 而不是 <BaseBase />。

組合式函數 (Composables)

Nuxt 自動引入 composables/ 目錄下的所有 Top-level 匯出。這是放置商業邏輯與狀態邏輯的最佳場所。

File Structure

composables/
- useUser.tsuseUser()
- cart.tsuseCart()
- auth/
  - login.tsuseLogin()

composables/useUser.ts

// composables/useUser.ts
export const useUser = () => {
    const user = useState('user', () => null)
    return { user }
}

app.vue

// app.vue
// 直接使用，免 import
const { user } = useUser()

注意掃描行為：Nuxt 預設只掃描 composables/ 的第一層檔案。若要支援巢狀目錄 (如 composables/auth/login.ts)，該檔案必須是 index.ts 或在 nuxt.config.ts 中額外設定。

工具函式 (Utils)

utils/ 目錄運作方式與 composables/ 相似，但用途不同。這裡適合放置純函數 (Pure Functions)，也就是不依賴 Vue 實例或狀態的輔助函式。

Composables

依賴 Vue Context (ref, computed)
涉及狀態管理 (useState, Pinia)
命名通常以 use 開頭

Utils

純 JavaScript/TypeScript 邏輯
格式化 (Date, Currency)
驗證邏輯 (Regex)

// utils/format.ts
export const formatPrice = (price: number) => {
  return '$' + price.toFixed(2)
}

// app.vue
// 自動引入
const price = formatPrice(100)

動態載入 (Lazy)

只要在元件名稱前加上 Lazy 前綴，Nuxt 就會自動將該元件打包成獨立的 chunk，並在需要顯示時才透過網路下載。這對於彈窗 (Modal)、側邊欄或捲動後才看到的內容非常有用。

<template>
  <!-- 只有當 show 為 true 時 -->
  <!-- 瀏覽器才會下載 Modal 的程式碼 -->
  <LazyModal v-if="show" />
  
  <button @click="show = true">
    Open Modal
  </button>
</template>

Standard Component

Included in main bundle

Lazy Component

Fetched on demand

顯式引入

雖然自動引入很方便，但在某些情況下（例如 JSX/TSX 或動態元件），你可能需要手動引入。你可以從 #components 虛擬模組中引入。

<script setup lang="ts">
// 顯式引入 (通常不需要，除非是為了取得元件型別或在非 Vue 檔使用)
import { AppHeader, LazyModal } from '#components'

const MyComponent = resolveComponent('AppHeader')
</script>