Context

The context mechanism provides a type-safe dependency injection pattern. It lets you provide required dependencies explicitly or inject them dynamically through middleware.

Initial Context

Use initial context for values that come from the environment. Declare it with .$context, then provide it when executing the procedure:

const base = os.$context<{ env: { DB_URL: string } }>()

export const getting = base
  .handler(async ({ context }) => {
    console.log(context.env)
  })

INFO

When a procedure requires initial context when calling, you must manually pass it:

const output = await call(getting, undefined, {
  context: { // <- initial context must be passed when calling
    env: { DB_URL: 'postgres://...' },
  },
})

Default Initial Context

To avoid repeating .$context declarations, you can define a default initial context type globally.

declare module '@orpc/server' {
  export interface DefaultInitialContext {
    env: { DB_URL: string }
  }
}

Injected Context

Injected context is injected at runtime through middleware:

const base = os.use(async ({ next }) => next({
  context: {
    env: { DB_URL: env.DB_URL },
  },
}))

export const getting = base.handler(async ({ context }) => {
  console.log(context.env)
})

INFO

When you use middleware context, you do not need to pass context manually when calling:

// no need to pass context manually when calling
const output = await call(getting)

Combining Initial and Injected Context

In many cases, you will use both. Use initial context for environment-specific values, such as database URLs, and injected context for runtime data, such as authenticated users.

const base = os.$context<{ headers: Headers, env: { JWT_SECRET: string } }>()

const requireAuth = base.middleware(async ({ context, next }) => {
  const user = parseJWT(
    context.headers.get('authorization')?.split(' ')[1],
    context.env.JWT_SECRET
  )

  if (!user) {
    throw new ORPCError('UNAUTHORIZED')
  }

  return next({ context: { user } })
})

const getting = base
  .use(requireAuth)
  .handler(async ({ context }) => {
    console.log(context.env)
    console.log(context.user)
  })