Run actions before server starts

[ezeheinke]

Hi! I am trying to find a way to run some actions before our app starts. For context, we have a blitzjs app that has the standard blitz-client.ts blitz-server.ts files.
And we run it with blitz start blitz dev. So far, like in the tutorial and docs.

But, we have the need now of running some initialisations when the server starts, what is the best way to achieve this? Custom server? Would I miss the plugins functionality that setupBlitzServer gives if I go down this route?

[manimovassagh]

You can use Next.js instrumentation for this. Blitz is built on Next.js, so the instrumentation.ts hook works perfectly for running code once when the server starts.

Create src/instrumentation.ts (or instrumentation.ts at your project root if using app router):

export async function register() {
  // This runs once when the server starts (both dev and production)
  if (process.env.NEXT_RUNTIME === "nodejs") {
    console.log("Server starting - running initialization...")
    
    // Example: seed cache, connect to external services, etc.
    await initializeExternalService()
    await warmUpCache()
  }
}

Make sure it's enabled in next.config.js:

module.exports = {
  experimental: {
    instrumentationHook: true, // Not needed in Next 15+, it's on by default
  },
}

You won't lose any Blitz plugin functionality. The setupBlitzServer and all your RPC resolvers work exactly the same - instrumentation.ts just runs before the server starts accepting requests.

If you need access to your database (Prisma) during init:

export async function register() {
  if (process.env.NEXT_RUNTIME === "nodejs") {
    const { default: db } = await import("db")
    
    // Run migrations, seed data, etc.
    const count = await db.user.count()
    console.log(`Server ready. ${count} users in database.`)
  }
}

Note the dynamic import() - this is important because instrumentation runs very early, so static imports of heavy modules can cause issues.

Alternative: Custom server (if you need more control)

If you need to do something more complex like start a WebSocket server alongside Blitz, then a custom server is the way to go. But for simple initialization tasks, instrumentation.ts is cleaner and doesn't sacrifice any Blitz features.