Astro Framework

Automate and integrate Astro framework development and deployment pipelines

Category: productivity Source: delineas/astro-framework-agents

Astro Framework is a community skill for advanced Astro framework development, covering SSR configuration, API routes, middleware, deployment adapters, and integration patterns for building full-stack applications with Astro beyond static sites.

What Is This?

Overview

Astro Framework provides patterns for using Astro as a full-stack web framework beyond static site generation. It covers server-side rendering configuration with output mode settings for on-demand page rendering, API route creation in the pages directory for handling POST requests and form submissions, middleware chains for authentication, session management, and request transformation, deployment adapter configuration for Node.js, Vercel, Cloudflare, and Netlify platforms, and environment variable management for secrets and public configuration. The skill enables developers to build dynamic web applications with Astro that handle server-side logic, database access, and user authentication alongside content-driven pages.

Who Should Use This

This skill serves developers building full-stack applications with Astro SSR capabilities, teams deploying Astro to serverless platforms that require adapter configuration, and engineers integrating databases and authentication into Astro projects.

Why Use It?

Problems It Solves

Configuring Astro for server-side rendering requires understanding output modes and adapter setup for the deployment target. Building API endpoints alongside pages in Astro needs proper request handling patterns. Implementing authentication flows requires middleware that runs before page rendering. Deploying to different platforms needs adapter-specific configuration for each hosting provider.

Core Highlights

SSR mode renders pages on the server for each request with access to headers and cookies. API routes handle JSON requests and form submissions with typed request parsing. Middleware pipeline runs before routes for auth checks and response transformation. Deployment adapters target Node.js, Vercel, Cloudflare Workers, and Netlify.

How to Use It?

Basic Usage

// astro.config.mjs
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';

export default defineConfig({
  output: 'server',
  adapter: node({
    mode: 'standalone',
  }),
});

// src/pages/api/users.ts
import type { APIRoute } from 'astro';

export const GET: APIRoute = async ({
  request,
}) => {
  const url = new URL(request.url);
  const page = Number(
    url.searchParams.get('page') ?? '1'
  );
  const users = await fetchUsers(page);
  return new Response(
    JSON.stringify(users),
    {
      status: 200,
      headers: {
        'Content-Type':
          'application/json',
      },
    }
  );
};

export const POST: APIRoute = async ({
  request,
}) => {
  const body = await request.json();
  const user = await createUser(body);
  return new Response(
    JSON.stringify(user),
    { status: 201 }
  );
};

Real-World Examples

// src/middleware.ts
import { defineMiddleware } from
  'astro:middleware';

export const onRequest = defineMiddleware(
  async (context, next) => {
    const token = context.cookies
      .get('session')?.value;

    if (context.url.pathname
        .startsWith('/dashboard')) {
      if (!token) {
        return context.redirect(
          '/login');
      }
      const user = await validateToken(
        token);
      if (!user) {
        return context.redirect(
          '/login');
      }
      context.locals.user = user;
    }

    const response = await next();
    response.headers.set(
      'X-Request-Id',
      crypto.randomUUID());
    return response;
  }
);

// src/pages/dashboard.astro
---
const user = Astro.locals.user;
if (!user) {
  return Astro.redirect('/login');
}
---

<h1>Welcome, {user.name}</h1>
<p>Email: {user.email}</p>

Advanced Tips

Use hybrid output mode to pre-render most pages statically while keeping specific routes server-rendered for dynamic content. Implement session management using encrypted cookies rather than server-side session stores for serverless deployments. Use Astro DB for simple data persistence that deploys alongside the application without external database configuration.

When to Use It?

Use Cases

Build a full-stack application with authenticated pages, API routes, and database-backed content. Create a hybrid site where marketing pages are static and user dashboards are server-rendered. Implement a form processing backend that handles submissions, validates data, and stores results alongside the frontend.

Important Notes

Requirements

Node.js 18 or later with Astro and the appropriate adapter package. A deployment platform that supports SSR such as Node.js, Vercel, or Cloudflare Workers. Environment variables configured for secrets and API keys.

Usage Recommendations

Do: use hybrid mode to statically render pages that do not need per-request data, reducing server load. Validate all request input in API routes before processing. Set appropriate cache headers on server-rendered pages to improve response times.

Don't: use server mode for pages that could be statically generated, which wastes compute on every request. Store sensitive data in Astro.locals without middleware-based validation. Deploy SSR Astro sites to static hosting without configuring an adapter.

Limitations

SSR adds server costs and latency compared to static generation for pages that do not require dynamic data. Each deployment platform has different adapter capabilities and limitations. Middleware runs on every request and should avoid expensive operations that increase response latency.