@workers-powertools/astro

Astro middleware adapters for Workers Powertools. This package adapts the existing logger, tracer, and metrics utilities to Astro middleware running on Cloudflare Workers. Supports wide events for single-log-per-request observability.

Part of Workers Powertools — a developer toolkit for observability and reliability best practices on Cloudflare Workers, inspired by Powertools for AWS Lambda.

Installation

pnpm add @workers-powertools/astro astro

You will also need the core packages you want to use:

pnpm add @workers-powertools/logger @workers-powertools/metrics
# Tracer is optional (deprecated — use wide events instead):
pnpm add @workers-powertools/tracer

Subpath exports are available if you want to import only the adapter surface you need:

import { injectLogger } from "@workers-powertools/astro/logger";
import { injectMetrics } from "@workers-powertools/astro/metrics";
import { injectTracer } from "@workers-powertools/astro/tracer";
import { injectObservability } from "@workers-powertools/astro/observability";

Usage

Create src/middleware.ts in your Astro app:

import { sequence } from "astro:middleware";
import { env } from "cloudflare:workers";
import { injectLogger } from "@workers-powertools/astro/logger";
import { injectMetrics } from "@workers-powertools/astro/metrics";
import { injectTracer } from "@workers-powertools/astro/tracer";
import { Logger } from "@workers-powertools/logger";
import { Metrics } from "@workers-powertools/metrics";
import { Tracer } from "@workers-powertools/tracer";

const logger = new Logger({ serviceName: "astro-app" });
const metrics = new Metrics({ namespace: "astro-app", serviceName: "web" });

export const onRequest = sequence(
  injectLogger({ logger, runtimeEnv: env, componentName: "astro", wideEvent: true }),
  injectMetrics({ metrics, runtimeEnv: env }),
);

This middleware will:

• create a request-scoped child logger and store it on Astro.locals
• when wideEvent: true, create a request-scoped WideEvent on Astro.locals.wideEvent that auto-emits after the handler
• record request_duration and request_count metrics and flush them via cfContext.waitUntil()

Convenience Middleware

Use injectObservability() when you want one middleware instead of composing three:

import { env } from "cloudflare:workers";
import { injectObservability } from "@workers-powertools/astro/observability";

export const onRequest = injectObservability({
  logger,
  metrics,
  wideEvent: true,
  runtimeEnv: env,
  componentName: "astro",
  // tracer is optional (deprecated)
});

Accessing Locals

The middleware stores observability utilities on Astro.locals / context.locals.

Recommended src/env.d.ts augmentation:

/// <reference types="astro/client" />

import type { AstroObservabilityLocals } from "@workers-powertools/astro";
import type { Runtime } from "@astrojs/cloudflare";

declare global {
  namespace App {
    interface Locals extends Runtime, AstroObservabilityLocals {}
  }
}

Then use it inside pages or endpoints:

export const GET = async (context) => {
  context.locals.logger?.info("Handling Astro endpoint");
  context.locals.wideEvent?.set({ route: "/api/data" });
  return new Response("ok");
};

Metrics Backend Helper

By default, injectMetrics() looks for env.METRICS_PIPELINE and creates a PipelinesBackend automatically.

You can also resolve it directly:

import { getMetricsBackendFromEnv } from "@workers-powertools/astro/metrics";

const backend = getMetricsBackendFromEnv(env);

Use bindingName to customize:

const backend = getMetricsBackendFromEnv(env, { bindingName: "MY_PIPELINE" });

Scope

This package is for Astro middleware. If your Cloudflare Worker uses Hono in front of Astro, use:

• @workers-powertools/hono for the Hono layer
• @workers-powertools/astro for Astro middleware
• @workers-powertools/agents for agent RPC / Durable Object helpers