High-Performance API Router for Astro using Trie matching – astro-routify

astro-routify is a high-performance API router for the Astro framework. It uses a Trie-based matcher to deliver fast and efficient routing.

The library allows you to define API routes using clean, flat structures directly in your code. This approach avoids the need for complex folder hierarchies or boilerplate logic to manage endpoints.

You can use astro-routify to structure your application’s backend logic in a more organized way. It is useful for projects that require numerous API endpoints but would benefit from a centralized routing definition.

Features

Use Cases

• Creating REST API endpoints for web applications without folder structure.
• Building webhook handlers that need to process multiple callback URLs in one place.
• Developing dynamic content APIs for headless CMS implementations.
• Setting up authentication endpoints with parameter-based user routing.
• Implementing file upload APIs with dynamic path-based organization.

How to Use it

1. Install astro-routify via npm:

npm install astro-routify

2. Create API routes using the defineRoute function. Each route specifies an HTTP method, URL pattern, and handler function:

// src/pages/api/index.ts
import {defineRoute, defineRouter, HttpMethod, ok} from "astro-routify";
export const GET = defineRouter([
    defineRoute(HttpMethod.GET, "/ping", () => ok("pong")),
    defineRoute(HttpMethod.GET, "/users/:id", ({params}) => ok({id: params.id}))
]);

3. Extract URL parameters automatically using colon notation. Parameters become available in the handler’s context:

defineRoute(HttpMethod.GET, "/posts/:year/:month/:slug", ({params}) => {
    return ok({
        year: params.year,
        month: params.month,
        slug: params.slug
    });
});

4. Handle multiple HTTP methods in a single file using RouterBuilder:

import {RouterBuilder, defineRoute, HttpMethod, ok} from "astro-routify";
const builder = new RouterBuilder();
builder.register([
    defineRoute(HttpMethod.GET, "/health", () => ok({status: "healthy"})),
    defineRoute(HttpMethod.POST, "/users", async ({request}) => {
        const userData = await request.json();
        return ok({created: userData});
    })
]);
export const ALL = builder.build();

5. Use built-in response helpers to avoid boilerplate JSON response creation:

import {ok, created, notFound, internalError} from "astro-routify";
// 200 OK
return ok({data: "success"});
// 201 Created
return created({id: 123});
// 404 Not Found
return notFound("Resource not found");
// 500 Internal Server Error
return internalError(new Error("Database connection failed"));

Related Resources

• Astro Documentation – Official Astro framework documentation and guides
• Astro API Routes – Native Astro endpoint handling patterns
• Fastify – Fast Node.js web framework with similar route definition patterns

FAQs

Q: Can I use astro-routify with existing Astro API routes?
A: Yes, astro-routify works alongside existing Astro endpoints. You can migrate routes gradually or use both approaches in the same project.

Q: How does performance compare to manual URL parsing?
A: The Trie-based matcher provides consistent O(k) lookup time where k is the URL path length. Manual parsing typically becomes O(n) where n is the number of routes.

Q: Does astro-routify support middleware?
A: Yes, since it uses Astro’s native APIContext, all existing middleware, authentication, and request processing works unchanged.

Q: Can I nest route parameters like /users/:id/posts/:postId?
A: Yes, you can define multiple parameters in a single route. All parameters are extracted and made available in the params object.

Q: How does astro-routify improve performance?
A: It uses a Trie data structure for route matching. This method is very efficient for prefix-based searches, which allows the router to find the correct handler quickly, even with thousands of registered routes.