Should Astro officially support injecting custom instances (e.g., Axios) into APIContext / ActionAPIContext?

[oamm]

Summary

Proposal: Provide an official, documented pattern or direct support in Astro for injecting custom object instances (e.g., an Axios client) into APIContext / ActionAPIContext.

---

Background & Motivation

Users often need to share dependencies—like HTTP clients, database connections, logging utilities, etc.—between middleware, actions, and API routes. Right now, the general recommendation is to attach these instances to ctx.locals. While this works, it can feel awkward and may lack clarity or best-practice guidance:

• Type definitions are not always straightforward when using locals.
• There's no official Astro pattern explaining how to inject and type services for universal consumption.
• Developers may resort to custom casts or extended types, which can lead to duplication or confusion.

By providing a documented way (or built-in mechanism) to attach shared instances, Astro could simplify this common use case and encourage consistent patterns.

---

Goals

• Clarify & Document: Offer an official best-practice (or pattern) for injecting custom instances (like HTTP clients) into APIContext / ActionAPIContext.
• Encourage Consistency: Reduce confusion by providing a standard approach that teams can follow.
• Improve Type Safety: Ensure that if we attach instances to context, we can do so with clear typing, without resorting to manual casting or ad-hoc solutions.

---

Example

Here’s one potential usage concept:

// A standardized approach to attach an Axios client
export async function middleware(ctx: APIContext, next: Function) {
  ctx.services = {
    axios: axios.create({ baseURL: 'https://example.com' })
  };
  return next();
}

// Then in an action or API route:
export async function POST(ctx: ActionAPIContext) {
  // Officially recognized property, e.g. `ctx.services`
  const { data } = await ctx.services.axios.get('/some-endpoint');
  return new Response(JSON.stringify(data));
}

This example highlights a more direct, typed pattern for shared services, as opposed to just dropping objects onto ctx.locals. The goal is not to force a specific naming convention (services vs. locals), but rather to have a clear, consistent, and documented approach that Astro users can adopt.

[ematipico]

I'm not sure I understand the proposal...

For example, you can already type locals: https://docs.astro.build/en/guides/middleware/#middleware-types

[oamm]

Thank you for the response!

I understand that locals is the recommended way to pass values through the context, and I’ve been using that approach (with custom typing) for injecting things like an Axios client or a database connection.

I just want to clarify that I’m not suggesting adding a new services property or changing Astro’s internal structure. The idea I’m exploring is more about where and how we inject service instances.

Using context.locals.axios or context.locals.db works, but sometimes it feels a bit awkward—locals gives the impression of being meant for simple or request-scoped data, rather than complex objects or shared services. That’s why I’m wondering if it would be considered acceptable to inject these instances directly into the context, like ctx.axios or ctx.db, especially when they are commonly accessed throughout the handler.

Thanks again for the clarification and the great work behind the framework.

[florian-lefebvre]

Locals are really the right tool for this job, it's the way to do dependency injection in Astro