DEV Community: mrtoxas

Type-Safe Astro Endpoints

mrtoxas — Tue, 20 Jan 2026 16:04:31 +0000

We all love Astro for its simplicity and developer experience. But sometimes, its API endpoints feel like a rough edge. Every time I start a new project, I find myself rewriting the same boilerplate: parsing requests manually, writing validation logic by hand, handling errors in a custom way. It gets old fast.

After yet another round of writing endpoints, their methods, and validation from scratch, while trying to recall the best solutions from previous projects, I realized there had to be a better way to structure Astro’s API endpoints in a way that felt closer to familiar development patterns, without repeating this pain every time.

I remembered my good experience with OpenAPI on previous projects. Automatic documentation, type safety, and validation all in one place sounded like exactly what I needed. That is when I discovered Chanfana. A library that brings these benefits to modern routers, handling docs and validation automatically using Zod schemas.

While reading Chanfana’s documentation to figure out how to use it with Astro, I came across Hono, which I’d used before and liked for its simplicity and convenience. I ended up using it as a bridge between Astro’s catch-all endpoints and Chanfana’s OpenAPI features.

The solution turned out to be surprisingly elegant. Instead of creating dozens of separate endpoint files in pages/api/, I now have a single entry point: pages/api/[...path].ts. This catch-all route delegates all API requests to Hono, which then routes them to the appropriate handlers powered by Chanfana.

// src/pages/api/[...path].ts

import { Hono } from 'hono';
import { fromHono } from 'chanfana';
import type { APIRoute } from 'astro';
import { ExampleGetEndpoint } from 'src/api/endpoints/exampleGet';
import { ExamplePostEndpoint } from 'src/api/endpoints/examplePost';

const app = new Hono<{ Bindings: Env }>();

const openapi = fromHono(app, {
  docs_url: "/api/docs",
  openapi_url: "/api/openapi.json",
});

openapi.get('/api/example', ExampleGetEndpoint);
openapi.post('/api/example', ExamplePostEndpoint);

export const ALL: APIRoute = async ({ request, locals }) => {
  const response = await app.fetch(request, locals.runtime.env);
  if (!response) {
    return new Response("Hono returned nothing", { status: 500 });
  }
  return response;
};

That's it. This single file:

Creates a Hono app instance
Wraps it with Chanfana's OpenAPI layer
Registers your endpoints
Exports an ALL handler that Astro calls for any HTTP method
Forwards requests to Hono, which handles routing and validation

Your actual endpoint logic lives in separate files (like ExampleGetEndpoint), keeping everything organized.

Here’s what a single endpoint looks like with Chanfana:

// src/api/endpoints/exampleGet.ts

import { OpenAPIRoute, Str } from "chanfana";
import { z } from "zod";

export class ExampleGetEndpoint extends OpenAPIRoute {
  schema = {
    tags: ["Example Endpoints"],
    summary: "Get simple data",
    description: "A simple GET endpoint for testing API functionality.",
    request: {
      query: z.object({
        name: Str({default: "Guest" }),
      }),
    },
    responses: {
      "200": {
        description: "Success",
        content: {
          "application/json": {
            schema: z.object({
              success: z.boolean(),
              message: z.string(),
              greeting: z.string(),
            }),
          },
        },
      },
    },
  };

  async handle(c: any) {
    const data = await this.getValidatedData<typeof this.schema>();

    console.log({ "Example Variable": c.env.EXAMPLE_VARIABLE });

    return {
      success: true,
      message: "API is reachable",
      greeting: `Hello, ${data.query.name}!`,
    };
  }
}

Notice how the schema defines everything: query parameters, their types, default values, and the response structure. Chanfana takes care of validation automatically, so TypeScript knows exactly what data.query.name is. No manual type guards, no custom validation logic.

The handle method only receives validated data. If a request doesn’t match the schema, Chanfana returns a 400 error automatically. Your job is just to write the business logic.

All of this also generates interactive API documentation out of the box.
Visit /api/docs and you'll see a full Swagger UI:

Every endpoint, parameter, and response type is automatically documented based on your schemas.

What’s next?

You can also generate TypeScript types for your frontend directly from the OpenAPI schema. This ensures your client code knows exactly what each endpoint expects and returns, with full autocomplete support.

Use openapi-typescript to generate types directly from the OpenAPI schema created from your endpoints. Combine it with openapi-fetch for fully type-safe API calls.

When Does This Make Sense?

This setup works well when you want type safety, automatic validation, and interactive documentation for your API. It’s especially useful for teams or projects where multiple endpoints need to stay consistent and maintainable.

Even if your project is small, having types and validation enforced by the same schema can save time and reduce mistakes. Once you’re managing several routes, this approach quickly pays off.

Try It Yourself

Check out the full working example on GitHub.

Wrangler “write EOF” on Windows: The Actual Fix

mrtoxas — Wed, 17 Dec 2025 09:40:48 +0000

This article is for developers using Cloudflare Wrangler or Astro with Cloudflare adapter on Windows who encounter the write EOF error.

The Problem

After reinstalling Windows, I ran into an EOF error while trying to start my project with Cloudflare Wrangler.

The Wrong Solution

After struggling to fix the issue on my own, I found a popular GitHub comment suggesting to run install_tools.bat from Node.js. This did fix the EOF error, but it installed a lot of unnecessary software, including Python, Visual Studio components, and various files scattered across the system.

To figure out what install_tools.bat was actually installing, I investigated its components and decided to try a more minimal approach. Among all the Microsoft Visual Studio components, Microsoft.VisualStudio.2022.BuildTools seemed like the most logical solution to the problem, so I installed it directly using winget:

winget install Microsoft.VisualStudio.2022.BuildTools --override "--wait --quiet --add Microsoft.VisualStudio.Workload.VCTools"

This also resolved the EOF error, but once again it installed a lot of unnecessary components, including Visual Studio Core, VS Core Editor Fonts, and parts of the Windows SDK.

The Actual Cause

While cleaning up the system, I noticed the installed Microsoft Visual C++ 2015–2022 Redistributable (x64 and x86) packages. I decided to test removing everything else except these packages, but the EOF error still didn’t appear.

When I uninstalled the Redistributables, the error returned immediately. Reinstalling them fixed the issue again.

I also confirmed this on a fresh Windows VM: installing only the VC++ Redistributable was enough to resolve the EOF error, without any Visual Studio Build Tools, SDKs, or Python.

Why This Works

Wrangler relies on native Node.js modules that require the Visual C++ runtime on Windows.

The cryptic "write EOF" error appears because the failure happens at a low level during process communication, resulting in a generic stream error rather than a clear "missing dependency" message.

Installing the Visual C++ Redistributable provides the required runtime and allows Wrangler to start normally.

Conclusion

To fix the "write EOF" error in Cloudflare Wrangler on Windows, you only need to install the Microsoft Visual C++ 2015–2022 Redistributable (x64 and x86).

The solutions offered online, including running install_tools.bat, are redundant and only clutter the system.

This minimal approach solves the problem cleanly and keeps your environment lean.

You can find a concise summary of the problem and the steps I took to fix it in my GitHub gist.

Access Cloudflare Runtime Env in Nested Functions with Astro SSR

mrtoxas — Thu, 11 Dec 2025 19:18:30 +0000

Astro SSR on Cloudflare Pages is a convenient way to render pages on the server, but there’s a catch. Environment variables via the usual import.meta.env aren’t directly accessible at runtime and they can only be obtained from locals.runtime.env at the request handler level. To use them in nested functions, you’d have to pass them through props, which is inconvenient, considered an anti-pattern, and will eventually give you a headache.

In this article, we’ll explore two ways to solve this: using middleware (recommended) and a custom context wrapper.

Approach 1: Middleware

Concept

We create a middleware that wraps each incoming request.
Inside the middleware, we extract the runtime environment variables from locals.runtime.env.
We store these variables in an AsyncLocalStorage instance, which provides a request-scoped context.
Anywhere in the code, including deeply nested functions or service modules, you can access the environment variables using getRuntimeEnv().

Minimal example

src/app/runtimeContext.ts – Holds AsyncLocalStorage for request-scoped environment variables.

import { AsyncLocalStorage } from 'node:async_hooks';

// ENV type is defined in env.d.ts
export const asyncLocalStorage = new AsyncLocalStorage<ENV>();

export function getRuntimeEnv<K extends keyof ENV>(key: K): ENV[K] {
  const env = asyncLocalStorage.getStore();
  if (!env?.[key]) {
    throw new Error(`Env "${String(key)}" is missing`);
  }
  return env[key];
};

src/middleware.ts – Middleware that sets up the runtime environment context per request.

import { defineMiddleware } from "astro:middleware";
import { asyncLocalStorage } from "src/app/runtimeContext";

export const onRequest = defineMiddleware((context, next) => {
  const runtimeEnv = context.locals.runtime.env;

  if (!runtimeEnv) {
    return next();
  }

  return asyncLocalStorage.run(runtimeEnv, () => {
    return next();
  });
});

src/pages/api/test.ts – Example API endpoint.

import { nestedFuncExample } from "src/app/nestedFuncExample";
import { getRuntimeEnv } from "src/app/runtimeContext";

export async function GET() {
  const testVariable = getRuntimeEnv("TEST_VARIABLE");

  nestedFuncExample();

  return new Response(testVariable);
};

And we can access our variables at any level of nesting:

import { getRuntimeEnv } from "src/app/runtimeContext";

export const nestedFuncExample = () => {
  const testVariable = getRuntimeEnv("TEST_VARIABLE");
  console.log('testVariable: ', testVariable);
};

Approach 2: Custom Context Wrapper

Concept

We create a custom wrapper for API handlers (withServerContext).
Inside the wrapper, we build a context object from locals.runtime.env.
The handler is then executed via serverStore.run(contextData, handler).
Anywhere in the code, you can access this context using getServerContext().

Minimal example

src/app/serverContext.ts – Wraps API handlers and provides a request-scoped context using AsyncLocalStorage.

import type { APIContext } from "astro";
import { serverStore } from "src/app/serverStore";

export function withServerContext(handler: () => Promise<Response>) {
  return async (context: APIContext) => {
    // Extract environment variables for the current request
    const { TEST_VARIABLE } = context.locals.runtime.env;

    const contextData = {
      testVariable: TEST_VARIABLE
    };

    // Run the handler inside AsyncLocalStorage context
    return serverStore.run(contextData, handler);
  };
};

src/app/serverStore.ts – Holds the AsyncLocalStorage instance and provides access to the current request context.

import { AsyncLocalStorage } from 'node:async_hooks';

type ContextData = {
  testVariable: string;
};

// Get the current request context from AsyncLocalStorage
export function getServerContext(): ContextData {
  const store = serverStore.getStore();
  if (!store) {
    throw new Error("Server context not initialized");
  }
  return store;
};

// AsyncLocalStorage instance to hold request context
export const serverStore = new AsyncLocalStorage<ContextData>();

src/pages/api/test.ts – Example API endpoint.

import { withServerContext } from "src/app/serverContext";
import { nestedFuncExample } from "src/app/nestedFuncExample";
import { getServerContext } from "src/app/serverStore";

export const GET = withServerContext(async () => {
  const { testVariable } = getServerContext();

  nestedFuncExample();

  return new Response(testVariable);
});

And we can access our variables at any level of nesting:

export const nestedFuncExample = () => {
  const { testVariable } = getServerContext();
  console.log('testVariable: ', testVariable);
};

Deployment notes

Important: Both approaches require the disable_nodejs_process_v2 flag
in wrangler.json:

{
  "compatibility_flags": [
    "nodejs_compat",
    "disable_nodejs_process_v2"
  ]
}

At the time of writing, this flag ensures that AsyncLocalStorage works correctly on Cloudflare Pages until full support is stabilized.

Summary

So, we explored two approaches to make Cloudflare runtime environment variables accessible deep in your Astro SSR code: using middleware and a custom context wrapper, both leveraging AsyncLocalStorage. I recommend using the first approach (middleware), as it’s simpler and integrates naturally with Astro. The second approach is provided mainly to demonstrate an alternative method and could be useful if you ever face limitations with middleware.

At first glance, creating a request-scoped context for every request might seem excessive. However, in a serverless environment like Cloudflare Pages, this is a safe and practical way to make runtime environment variables accessible anywhere in your code.

With some adjustments, this approach can also be adapted to other serverless providers that support AsyncLocalStorage.

Check out the full working examples on GitHub:

Cassette tape in CSS 🎵

mrtoxas — Wed, 28 Apr 2021 13:39:33 +0000

Good afternoon dear community Dev!
I decided to share with you my craft item - this is a audio-cassette made in CSS.

Demonstration:
https://mrtoxas.github.io/cassette-tape-css/

Code:
https://github.com/mrtoxas/cassette-tape-css

I hope this will make you feel a pleasant nostalgic and in a good mood :)

Easy SCSS color-function

mrtoxas — Tue, 14 Jul 2020 19:17:45 +0000

I decided to share with you a function that makes my life easier. Function organizes convenient work with colors on the page, uses css-variables.

// Creating a map with our colors:
$colors: (
  primary:#f37021,
  secondary:#b4341d,  
);

// Declaring colors as global variables of page
:root {
  @each $name, $color in $colors {
    --color-#{$name}: #{$color};
  }
}

/* Creating a function that returns our color, 
in accordance with the syntax of css-variables */
@function color($color-name) {
  @return var(--color-#{$color-name});
}

// Usage
body{
  color: color(primary);
  background-color: color(secondary);
}

At the output we get the result:

:root {
  --color-primary: #f37021;
  --color-primary-dark: #CE5A14;
}

body {
  color: var(--color-primary);
  background-color: var(--color-secondary);
}

Automatic switching Dark/Light Mode

mrtoxas — Tue, 07 Jul 2020 10:01:31 +0000

Much has been said about switching the dark/light mode of a web page, but let's try switching themes automatically, depending on the selected theme in the operating system.

Let's start by defining the basic styles:

:root {
  --text-color: black;
  --body-bg: white;
}

body {
  background-color: var(--body-bg);
  color: var(--text-color);
}

Now we are adding the preferences-color-scheme media function to define the system theme. And according to the chosen theme we will change the root-variables:

@media (prefers-color-scheme: dark) {
  :root {
    --text-color: white;
    --body-bg: black;
  }
}

Now when the user changes the system theme to black, we get white text on a black background.

We can also define values for a light theme using the "light" value.

Support for this method is not yet 100%, some browsers are still lagging behind progress. Therefore, do not rush to remove the button to switch themes. But nothing prevents you from using this magic right now.

Happy coding!

Sources for reading:
Using CSS custom properties
prefers-color-scheme