Nitro App Hook trong NuxtJS: Hướng Dẫn Toàn Tập

Nếu bạn đã từng tự hỏi làm thế nào để “chen vào” giữa các bước xử lý của server NuxtJS 3 mà không cần chỉnh sửa core framework, thì Nitro App Hooks chính là câu trả lời bạn đang tìm kiếm. Đây là một trong những tính năng mạnh mẽ nhất nhưng lại ít được khai thác triệt để nhất trong hệ sinh thái NuxtJS 3 — một công cụ cho phép bạn kiểm soát toàn bộ vòng đời server application một cách có cấu trúc, linh hoạt và dễ bảo trì.

Bài viết này sẽ đưa bạn đi từ định nghĩa cơ bản đến các use case thực tế, kèm theo code examples cụ thể để bạn có thể áp dụng ngay vào dự án của mình.

Nitro App Hook là gì?

Nitro là server engine được phát triển bởi UnJS team, đóng vai trò là trái tim của server-side trong NuxtJS 3. Mọi request đến ứng dụng NuxtJS của bạn đều đi qua Nitro — từ việc xử lý API routes, render SSR, cho đến phục vụ static assets. Điều làm Nitro trở nên đặc biệt là khả năng compile và deploy lên hơn 20 nền tảng khác nhau, từ Node.js truyền thống đến Cloudflare Workers hay AWS Lambda, mà không cần thay đổi code.

Trong bối cảnh đó, hooks (hay còn gọi là “móc nối”) là các điểm can thiệp được định nghĩa sẵn trong vòng đời của Nitro. Hãy hình dung chúng như những “trạm dừng” mà bạn có thể đặt code của mình vào để thực thi tại đúng thời điểm mong muốn — khi server khởi động, khi có request mới, khi chuẩn bị gửi response, hay khi có lỗi xảy ra.

Cần phân biệt rõ hai loại hooks trong hệ sinh thái Nitro/NuxtJS:

• Build-time hooks: Được kích hoạt trong quá trình build ứng dụng. Ví dụ: nitro:init, nitro:build:before. Loại này thường được khai báo trong nuxt.config.ts.
• Runtime hooks (App hooks): Được kích hoạt khi server đang chạy và xử lý requests thực tế. Đây là loại hooks chúng ta sẽ tập trung vào trong bài viết này.

Lợi ích cốt lõi của hệ thống hooks này bao gồm: kiến trúc plugin-based giúp mở rộng server mà không cần sửa core, type safety nhờ TypeScript, và khả năng composability — tức là bạn có thể kết hợp nhiều hooks lại để tạo ra các behavior phức tạp mà vẫn giữ được sự rõ ràng trong code.

Danh sách các Nitro App Hooks quan trọng

Nitro cung cấp một tập hợp hooks được tổ chức theo nhóm chức năng. Dưới đây là các hooks quan trọng nhất mà bạn sẽ thường xuyên làm việc cùng:

Lifecycle Hooks (Build-time)

• nitro:init — Kích hoạt khi Nitro được khởi tạo trong quá trình build. Dùng để can thiệp vào Nitro instance ở mức cấu hình.
• nitro:build:before — Chạy ngay trước khi quá trình build bắt đầu. Hữu ích để chuẩn bị tài nguyên hoặc validate cấu hình.
• nitro:close — Kích hoạt khi Nitro instance đóng lại trong quá trình build.

Runtime Hooks (App hooks)

• request — Kích hoạt với mỗi incoming request. Đây là hook phổ biến nhất, dùng cho logging, authentication, rate limiting.
• beforeResponse — Chạy trước khi response được gửi về client. Dùng để transform headers hoặc body.
• afterResponse — Chạy sau khi response đã được gửi. Dùng cho analytics, cleanup tasks.
• error — Kích hoạt khi có lỗi xảy ra trong quá trình xử lý request. Hook quan trọng nhất cho error handling tập trung.
• close — Kích hoạt khi server đóng lại (graceful shutdown). Dùng để giải phóng tài nguyên như database connections.

Render Hooks (SSR)

• render:response — Kích hoạt khi Nitro chuẩn bị render response trong SSR. Cho phép can thiệp vào response object trước khi gửi đi.
• render:html — Kích hoạt khi HTML được render. Dùng để inject thêm nội dung vào HTML output (ví dụ: thêm tracking scripts).

Cách đăng ký và sử dụng Hooks trong NuxtJS

Có hai cách chính để đăng ký hooks trong NuxtJS, mỗi cách phù hợp với một loại hooks khác nhau.

Cách 1: Sử dụng Nitro Plugin (Khuyến nghị cho Runtime Hooks)

Đây là phương pháp được khuyến nghị nhất cho runtime hooks. Bạn tạo file trong thư mục server/plugins/ và NuxtJS sẽ tự động load chúng khi server khởi động.

Cấu trúc thư mục chuẩn:

server/
  plugins/
    logger.ts
    errorHandler.ts
    auth.ts
    database.ts

Ví dụ một Nitro plugin cơ bản:

// server/plugins/logger.ts
export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook('request', (event) => {
    console.log(`[${new Date().toISOString()}] ${event.method} ${event.path}`)
  })

  nitroApp.hooks.hook('afterResponse', (event, { body }) => {
    console.log(`Response sent for: ${event.path}`)
  })
})

Lưu ý về quy tắc đặt tên: NuxtJS sẽ load tất cả các file .ts hoặc .js trong thư mục server/plugins/ theo thứ tự alphabet. Nếu bạn muốn kiểm soát thứ tự load, hãy đặt tên file với số prefix như 01.database.ts, 02.auth.ts.

Cách 2: Khai báo trong nuxt.config.ts (Build-time Hooks)

Đối với build-time hooks, bạn khai báo trực tiếp trong nuxt.config.ts:

// nuxt.config.ts
export default defineNuxtConfig({
  hooks: {
    'nitro:init': (nitro) => {
      console.log('Nitro đã được khởi tạo!')
      // Can thiệp vào Nitro config tại đây
    },
    'nitro:build:before': (nitro) => {
      console.log('Chuẩn bị build...')
    }
  }
})

Quan trọng là không nhầm lẫn giữa hai cách này: runtime hooks phải được đăng ký qua Nitro Plugin, còn build-time hooks thì khai báo trong nuxt.config.ts. Nếu bạn cố gắng đăng ký hook request trong nuxt.config.ts, nó sẽ không hoạt động như mong đợi.

Các Use Case thực tế phổ biến

1. Logging và Monitoring

Một trong những use case phổ biến nhất là ghi log request và đo thời gian xử lý:

// server/plugins/01.logger.ts
export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook('request', (event) => {
    const start = Date.now()
    event.context._startTime = start
    console.log(`→ ${event.method} ${event.path}`)

    event.node.res.on('finish', () => {
      const duration = Date.now() - start
      console.log(`← ${event.path} [${event.node.res.statusCode}] ${duration}ms`)
    })
  })
})

2. Centralized Error Handling với Sentry

Thay vì xử lý lỗi rải rác ở nhiều nơi, bạn có thể tập trung toàn bộ vào một plugin:

// server/plugins/02.errorHandler.ts
export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook('error', (error, { event }) => {
    // Bỏ qua các lỗi 404 thông thường
    if (error.statusCode === 404) return

    // Gửi lỗi nghiêm trọng đến Sentry
    console.error({
      url: event?.path,
      method: event?.method,
      message: error.message,
      stack: error.stack,
      timestamp: new Date().toISOString()
    })

    // Trong thực tế: Sentry.captureException(error)
  })
})

3. Authentication Middleware

Kiểm tra JWT token cho các protected API routes một cách tập trung:

// server/plugins/03.auth.ts
import { getHeader, createError } from 'h3'

export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook('request', async (event) => {
    // Chỉ áp dụng cho các route cần bảo vệ
    if (!event.path.startsWith('/api/protected')) return

    const authHeader = getHeader(event, 'Authorization')
    if (!authHeader?.startsWith('Bearer ')) {
      throw createError({
        statusCode: 401,
        message: 'Missing or invalid Authorization header'
      })
    }

    const token = authHeader.slice(7)
    // Validate token ở đây (verify JWT, check expiry, etc.)
    // event.context.user = await verifyToken(token)
  })
})

4. Database Connection Management

Quản lý vòng đời của database connection một cách sạch sẽ:

// server/plugins/00.database.ts
export default defineNitroPlugin(async (nitroApp) => {
  // Kết nối database khi server khởi động
  const db = await connectToDatabase({
    url: process.env.DATABASE_URL
  })

  console.log('✓ Database connected')

  // Lưu instance vào context để dùng ở các nơi khác
  nitroApp.hooks.hook('request', (event) => {
    event.context.db = db
  })

  // Cleanup khi server đóng (graceful shutdown)
  nitroApp.hooks.hook('close', async () => {
    await db.disconnect()
    console.log('Database connection closed')
  })
})

5. Response Transformation

Thêm security headers hoặc transform response trước khi gửi về client:

// server/plugins/04.responseTransformer.ts
export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook('beforeResponse', (event, response) => {
    // Thêm security headers
    event.node.res.setHeader('X-Content-Type-Options', 'nosniff')
    event.node.res.setHeader('X-Frame-Options', 'DENY')
    event.node.res.setHeader('X-Request-Id', crypto.randomUUID())
  })
})

Best Practices khi làm việc với Nitro Hooks

Sau khi đã hiểu cách sử dụng, đây là những nguyên tắc quan trọng để đảm bảo code của bạn chất lượng và bền vững:

• Single Responsibility: Mỗi plugin chỉ nên đảm nhận một trách nhiệm duy nhất. Đừng nhồi nhét logging, authentication và error handling vào cùng một file. Sự tách biệt này giúp code dễ test, dễ debug và dễ thay thế.
• Xử lý async đúng cách: Luôn dùng async/await và bắt lỗi trong các async hooks để tránh unhandled promise rejections làm crash server. Nitro sẽ đợi các async hooks hoàn thành trước khi tiếp tục, nhưng nếu bạn không xử lý lỗi, toàn bộ request có thể bị treo.
• Tận dụng TypeScript: Nitro được viết hoàn toàn bằng TypeScript và cung cấp đầy đủ type definitions. Hãy tận dụng điều này để đảm bảo type safety cho event, error và các objects khác.
• Tránh logic nặng trong hook request: Hook này chạy với mọi request, kể cả static assets. Nếu bạn đặt logic phức tạp ở đây mà không filter cẩn thận, performance sẽ bị ảnh hưởng nghiêm trọng. Luôn kiểm tra event.path trước khi thực thi logic nặng.
• Sử dụng hook close để cleanup: Database connections, file handles, timers, subscriptions — tất cả đều cần được giải phóng đúng cách khi server shutdown. Hook close là nơi lý tưởng để làm điều này.

Nitro Hooks và hệ sinh thái UnJS

Để hiểu sâu hơn về Nitro Hooks, bạn cần biết rằng nó không đứng một mình. Nitro là một phần của hệ sinh thái UnJS — một tập hợp các thư viện JavaScript/TypeScript được thiết kế để hoạt động tốt cùng nhau.

Cụ thể, hệ thống hooks của Nitro được xây dựng trên thư viện hookable của UnJS, một thư viện hooks đa năng và nhẹ. Các requests được xử lý thông qua H3 — một HTTP framework event-based cực kỳ nhẹ và nhanh. Khi bạn nhận được event trong hook request, đó chính là H3 event object với đầy đủ utilities như getHeader(), readBody(), setResponseHeader().

Điểm mạnh đặc biệt của Nitro là hỗ trợ đa nền tảng. Với hơn 20 deployment targets — bao gồm Vercel, Netlify, Cloudflare Workers, AWS Lambda, Deno Deploy, Bun và nhiều hơn nữa — hooks của bạn sẽ hoạt động nhất quán trên tất cả các nền tảng đó mà không cần thay đổi code.

Nhìn về tương lai, Nitro v2.x đang mang đến nhiều tính năng hấp dẫn như hỗ trợ WebSocket thông qua hooks, task scheduling cho background jobs, và tích hợp SQL database trực tiếp. Xu hướng edge computing đang ngày càng phổ biến, và Nitro đang định vị mình là server engine lý tưởng cho thời đại này — nơi code của bạn chạy gần với người dùng nhất có thể, và hooks giúp bạn kiểm soát behavior đó một cách nhất quán dù deploy ở đâu.

Kết luận

Nitro App Hooks không chỉ là một tính năng kỹ thuật — đây là một triết lý thiết kế. Thay vì viết server logic theo kiểu monolithic và khó bảo trì, hooks khuyến khích bạn tư duy theo hướng plugin-based: mỗi concern được tách biệt, mỗi plugin có trách nhiệm rõ ràng, và toàn bộ hệ thống trở nên dễ test, dễ mở rộng và dễ debug hơn rất nhiều.

Qua bài viết này, bạn đã nắm được toàn bộ bức tranh: từ khái niệm hooks là gì, phân biệt build-time và runtime hooks, cách đăng ký qua Nitro Plugin hoặc nuxt.config.ts, các use case thực tế từ logging đến database management, cho đến best practices và vị trí của Nitro trong hệ sinh thái UnJS rộng lớn hơn.

Nếu bạn đang bắt đầu, hãy thử ngay với hai use case đơn giản nhất: logging và error handling tập trung. Tạo hai file server/plugins/01.logger.ts và server/plugins/02.errorHandler.ts, chạy thử và quan sát cách chúng hoạt động. Khi đã quen với flow cơ bản, bạn có thể tiến đến các pattern phức tạp hơn như authentication middleware, database connection pooling hay response transformation.

Hệ thống Nitro App Hooks chính là chìa khóa để bạn xây dựng server-side logic trong NuxtJS 3 một cách chuyên nghiệp — có cấu trúc, có khả năng mở rộng, và quan trọng nhất là bạn hoàn toàn kiểm soát được những gì xảy ra trên server của mình.