Netlify Frameworks

Frameworks on Netlify

Netlify supports any framework that produces static output. For frameworks with server-side capabilities (SSR, API routes, middleware), an adapter or plugin translates the framework's server-side code into Netlify Functions and Edge Functions automatically.

How It Works

During build, the framework adapter writes files to .netlify/v1/ — functions, edge functions, redirects, and configuration. Netlify reads these to deploy the site. You do not need to write Netlify Functions manually when using a framework adapter for server-side features.

Detecting Your Framework

Check these files to determine the framework:

Framework Reference Guides

Each framework has specific adapter/plugin requirements and local dev patterns:

• Vite + React (SPA or with server routes): See references/vite.md
• Astro: See references/astro.md
• TanStack Start: See references/tanstack.md
• Next.js: See references/nextjs.md

General Patterns

Client-Side Routing (SPA)

For single-page apps with client-side routing, add a catch-all redirect:

# netlify.toml
[[redirects]]
from = "/*"
to = "/index.html"
status = 200

Custom 404 Pages

• Static sites: Create a 404.html in your publish directory. Netlify serves it automatically for unmatched routes.
• SSR frameworks: Handle 404s in the framework's routing (the adapter maps this to Netlify's function routing).

Environment Variables in Frameworks

Each framework exposes environment variables to client-side code differently:

Server-side code in all frameworks can access variables via process.env.VAR or Netlify.env.get("VAR").

Astro on Netlify

Setup

Check current versions before pinning. Knowledge cutoffs lag behind npm, and guessing a version tends to fail (npm install rejects it, or worse, installs something incompatible). Before pinning @astrojs/netlify, astro, or any other package in package.json, run npm view <pkg> version to get the current latest. Or omit explicit pins and let npm install pick them up.

Install the Netlify adapter:

npx astro add netlify

This installs @astrojs/netlify and updates astro.config.* automatically.

Manual Setup

npm install @astrojs/netlify

// astro.config.mjs
import { defineConfig } from "astro/config";
import netlify from "@astrojs/netlify";

export default defineConfig({
  output: "server",  // or "hybrid" for mixed static/SSR
  adapter: netlify(),
});

Output Modes

What the Adapter Does

• Converts Astro server routes into Netlify Functions
• Handles SSR, API routes, and middleware
• Maps Astro's routing to Netlify's function routing
• You do not write raw Netlify Functions for Astro's server routes

API Routes

Astro API routes (in src/pages/api/) are handled by the adapter:

// src/pages/api/items.ts
import type { APIRoute } from "astro";

export const GET: APIRoute = async () => {
  return new Response(JSON.stringify({ items: [] }), {
    headers: { "Content-Type": "application/json" },
  });
};

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

Forms (HTML Pattern)

Astro renders HTML server-side, so Netlify can detect forms directly:

---
// src/pages/contact.astro
---
<form name="contact" method="POST" data-netlify="true">
  <label>Name: <input type="text" name="name" /></label>
  <label>Email: <input type="email" name="email" /></label>
  <label>Message: <textarea name="message"></textarea></label>
  <button type="submit">Send</button>
</form>

For form submissions that should redirect back with feedback, handle the POST in an API route and redirect:

// src/pages/api/contact.ts
export const POST: APIRoute = async ({ request, redirect }) => {
  const formData = await request.formData();
  // Process form...
  return redirect("/contact?success=true");
};

Custom 404

Create src/pages/404.astro. Astro handles this automatically.

Local Development

Option A: Astro dev server (simpler, but no Netlify primitives):

npm run dev    # astro dev

Option B: netlify dev (full Netlify environment including functions, env vars):

netlify dev

The Astro adapter's local dev experience with netlify dev varies — for Blobs and DB access, netlify dev is recommended. If using @netlify/vite-plugin alongside Astro, local platform primitives may also be available via the standard dev server, but this integration is less mature than with pure Vite projects.

Build and Deploy

# netlify.toml
[build]
command = "astro build"
publish = "dist"

The adapter configures the publish directory and function routing automatically.

Next.js on Netlify

Setup

Check current versions before pinning. Knowledge cutoffs lag behind npm, and guessing a version tends to fail (npm install rejects it, or worse, installs something incompatible). Before pinning next or any other package in package.json, run npm view <pkg> version to get the current latest. Or omit explicit pins and let npm install pick them up.

Next.js on Netlify uses the @netlify/next runtime, which is installed automatically. No manual adapter installation is required — Netlify detects Next.js and configures the build automatically.

# netlify.toml
[build]
command = "next build"
publish = ".next"

What the Runtime Does

• Converts Next.js server-side features (SSR, API routes, middleware, ISR) into Netlify Functions and Edge Functions
• Handles image optimization via Netlify Image CDN
• Maps Next.js routing to Netlify's infrastructure
• Supports App Router and Pages Router

Key Configuration

next.config.js

/** @type {import('next').NextConfig} */
const nextConfig = {
  images: {
    remotePatterns: [
      { protocol: "https", hostname: "example.com" },
    ],
  },
};

module.exports = nextConfig;

Remote image patterns in next.config.js are automatically mapped to Netlify Image CDN's remote_images configuration.

API Routes

Next.js API routes work automatically — they are deployed as Netlify Functions:

// app/api/items/route.ts (App Router)
export async function GET() {
  return Response.json({ items: [] });
}

export async function POST(request: Request) {
  const data = await request.json();
  return Response.json({ created: data }, { status: 201 });
}

Middleware

Next.js middleware is deployed as a Netlify Edge Function:

// middleware.ts
import { NextResponse } from "next/server";
import type { NextRequest } from "next/server";

export function middleware(request: NextRequest) {
  // Runs at the edge on Netlify
  return NextResponse.next();
}

ISR (Incremental Static Regeneration)

ISR works on Netlify. Pages with revalidate are cached and revalidated using Netlify's CDN cache with stale-while-revalidate. On-demand revalidation via revalidatePath and revalidateTag triggers Netlify cache purge.

Local Development

npm run dev    # next dev — standard Next.js dev server

For Netlify-specific features (environment variables, edge middleware testing), use:

netlify dev

Known Patterns

• Static export (output: "export"): Works without the runtime — produces a fully static site
• Standalone mode is not required; the Netlify runtime handles deployment automatically
• Environment variables use the NEXT_PUBLIC_ prefix for client-side access

TanStack Start on Netlify

Setup

Check current versions before pinning. Knowledge cutoffs lag behind npm, and guessing a version tends to fail (npm install rejects it, or worse, installs something incompatible). Before pinning @netlify/vite-plugin, @tanstack/react-start, vite, or any other package in package.json, run npm view <pkg> version to get the current latest. Or omit explicit pins and let npm install pick them up.

TanStack Start uses the Netlify Vite plugin for deployment.

npm install @netlify/vite-plugin

// app.config.ts
import { defineConfig } from "@tanstack/react-start/config";
import netlify from "@netlify/vite-plugin";

export default defineConfig({
  vite: {
    plugins: [netlify()],
  },
});

What the Plugin Does

• Handles SSR output for Netlify Functions
• Enables Netlify platform primitives (Blobs, DB, env vars) in local dev
• Maps TanStack Start's file-based routing to Netlify's infrastructure

Server Functions

TanStack Start uses createServerFn for server-side logic. These are automatically handled by the Netlify Vite plugin — no raw Netlify Functions needed:

import { createServerFn } from "@tanstack/react-start";

const getItems = createServerFn({ method: "GET" }).handler(async () => {
  // Server-side code — runs as Netlify Function in production
  const items = await db.select().from(itemsTable);
  return items;
});

Local Development

npm run dev    # Uses Vite plugin — Netlify primitives available

The Vite plugin provides Functions, Blobs, DB, and environment variables during local dev without needing netlify dev.

Build and Deploy

# netlify.toml
[build]
command = "npm run build"
publish = ".output/public"

The Vite plugin configures the output structure for Netlify automatically.

Vite + React on Netlify

Setup

Check current versions before pinning. Knowledge cutoffs lag behind npm, and guessing a version tends to fail (npm install rejects it, or worse, installs something incompatible). Before pinning @netlify/vite-plugin, vite, @vitejs/plugin-react, or any other package in package.json, run npm view <pkg> version to get the current latest. Or omit explicit pins and let npm install pick them up.

Install the Netlify Vite plugin:

npm install @netlify/vite-plugin

// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import netlify from "@netlify/vite-plugin";

export default defineConfig({
  plugins: [react(), netlify()],
});

What the Plugin Does

• Enables Netlify Functions, Blobs, DB, and environment variables in local dev
• Handles build output for Netlify deployment
• No need for netlify dev — run npm run dev directly

SPA Routing

For client-side routing (React Router, etc.), add the catch-all redirect:

# netlify.toml
[[redirects]]
from = "/*"
to = "/index.html"
status = 200

Netlify Functions

Write functions in netlify/functions/ as usual. The Vite plugin makes them available during local dev at their configured paths.

// netlify/functions/api.ts
import type { Config, Context } from "@netlify/functions";

export default async (req: Request, context: Context) => {
  return Response.json({ message: "Hello from API" });
};

export const config: Config = { path: "/api/hello" };

Forms (AJAX Pattern)

Since Vite + React renders forms client-side, include a hidden HTML form for Netlify to detect, and submit via AJAX:

// In your React component
function ContactForm() {
  const handleSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    const formData = new FormData(e.currentTarget);
    await fetch("/", {
      method: "POST",
      headers: { "Content-Type": "application/x-www-form-urlencoded" },
      body: new URLSearchParams(formData as any).toString(),
    });
  };

  return (
    <form name="contact" method="POST" data-netlify="true" onSubmit={handleSubmit}>
      <input type="hidden" name="form-name" value="contact" />
      {/* fields */}
    </form>
  );
}

Also add a hidden form in index.html:

<form name="contact" netlify hidden>
  <input type="text" name="name" />
  <input type="email" name="email" />
  <textarea name="message"></textarea>
</form>

Local Dev

npm run dev   # Uses Vite plugin — Netlify primitives available

No netlify dev wrapper needed. Functions, Blobs, DB, and environment variables all work.

Build and Deploy

# netlify.toml
[build]
command = "npm run build"
publish = "dist"