/netlify-frameworks

name: netlify-frameworks
description: Deploy and configure web frameworks on Netlify — build settings and SSR/edge adapters plus local platform emulation and env vars. Use when setting up or fixing a framework deploy (Next.js / Astro / Nuxt / SvelteKit / Remix / React Router / TanStack Start / SolidStart / Gatsby / Angular / Vite / Express / Hydrogen / Hugo / Eleventy / Vue / React), adding SSR or edge functions or middleware wired to Netlify context, fixing SPA redirect and catch-all rules, setting a build command or publish directory, or debugging "why isn't my env var updating" and framework build failures.

Route framework-specific deep work to the guides in this skill: `references/astro.md`, `references/nextjs.md`, `references/nuxt.md`, `references/sveltekit.md`, `references/tanstack.md`, `references/vite.md`.

Env vars: modern rules (read first)

Env values are injected **at build time**. Any change (client- or server-side) requires a **redeploy** — editing a var in the UI/CLI does NOT reach the live site or already-deployed functions until a new build runs.

**Never use a client prefix for secrets.** Client-prefixed vars are inlined into the browser bundle: `VITE_`, `NEXT_PUBLIC_`, `PUBLIC_`, `NUXT_PUBLIC_`, `REACT_APP_`, `GATSBY_`, `VUE_APP_`.

Client-embed prefixes by framework: CRA `REACT_APP_`, Gatsby `GATSBY_`, Next `NEXT_PUBLIC_`, Nuxt `NUXT_ENV_`, Vue CLI `VUE_APP_`.

**Scopes:** build-time access needs **Builds** scope; SSR/DSG runtime access needs **both Functions and Builds**. `netlify.toml` is read only during build — functions cannot read it at runtime; set runtime vars in UI/CLI/API.

Netlify build variables can't be used as values in the UI or `netlify.toml` env sections. Set them inline before the build command:

[build]
  command = "REACT_APP_CONTEXT=$CONTEXT npm run build"

SPA redirects and the SSR catch-all footgun

SPAs (React, Vue CLI, Vite, Nuxt in SPA mode) need a rewrite to serve `index.html` for `pushState`:

/* /index.html 200

**Remove any SPA catch-all when adopting an SSR adapter.** A leftover `/* → /index.html 200` silently serves static `index.html` for SSR pages and API routes — user redirects beat adapter-generated routes.

Local dev with platform emulation (no Netlify CLI)

Vite-based frameworks emulate Netlify primitives (functions, edge functions, blobs, Netlify Database, Cache API, Image CDN, redirects/rewrites, headers, env vars, AI Gateway) in the dev server:

| Framework | Plugin/module | Run | |-----------|---------------|-----| | Astro (5.12+) | built-in (Netlify Vite plugin auto-loaded) | `astro dev` | | Nuxt | `@netlify/nuxt` | `nuxt dev` | | React Router | `@netlify/vite-plugin` | `react-router dev` | | SolidStart 2 | `@netlify/vite-plugin` | `vite dev` | | TanStack Start | `@netlify/vite-plugin-tanstack-start` | (vite) | | Vite | `@netlify/vite-plugin` | `npx vite` |

Still need `netlify dev` (Netlify CLI) for: Gatsby generated functions (run `netlify build` first), Angular SSR local test (`netlify serve`), and frameworks without a Vite plugin.

**`netlify dev` gotcha:** with both a custom `command` and a `targetPort` in `[dev]`, you must set `framework = "#custom"` — otherwise the detector runs and your custom command is silently ignored.

Build settings by framework

| Framework | Build command | Publish | |-----------|---------------|---------| | Angular (standard) | `ng build --prod` | `dist/YOUR_PROJECT_NAME` | | Astro | `astro build` | `dist` | | Create React App | `react-scripts build` | `build` | | Eleventy | `eleventy` | `_site` | | Gatsby | `gatsby build` | `public` | | Hugo | `hugo` | `public` | | Hydrogen | `remix vite:build` | `dist/client` | | Next.js (SSR/hybrid) | `next build` | `.next` | | Next.js (static export) | `next build && next export` | `out` (`NETLIFY_NEXT_PLUGIN_SKIP=true`) | | Nuxt 3 | `nuxt build` | `dist` | | Nuxt 2 | `nuxt generate` | `dist` | | React Router | `react-router build` | `build/client` | | Remix (Vite) | `remix vite:build` | `build/client` | | SolidStart 2 (Vite plugin) | `vite build` | `dist/client` | | SolidStart 2 (Nitro) | `vite build` | `dist` | | SolidStart 1.x | `vinxi build` | `dist` | | SvelteKit | `vite build` | `build` | | TanStack Start (1.132.0+) | `vite build` | `dist/client` | | Vite | `vite build` | `dist` | | Vue CLI | `vue-cli-service build` | `dist` |

Detection suggests these; override in `netlify.toml` or UI (project configuration > Build & deploy > Continuous deployment > Build settings).

SSR / adapter setup

Astro

`npx astro add netlify` installs the adapter and edits `astro.config.mjs`. Adapter needed for SSR and out-of-the-box Image CDN for `<Image />`. SSR → Netlify Functions; middleware → Edge Functions. Adapter-less deploy only if no server features and no Image CDN need. Skew protection from 5.15.0.

Next.js (13.5+ only)

Zero-config via the OpenNext adapter (`@netlify/plugin-nextjs`). Do NOT pin the version — Netlify auto-updates each build. Treat the legacy adapter as read-only history, never a recommendation. Adapter provisions: serverless function for SSR/ISR/PPR/route handlers/Server Actions; Edge Function for Middleware; Full Route + Data Cache; Image CDN with `next/image`. Skew protection is opt-in: set `NETLIFY_NEXT_SKEW_PROTECTION=true`, redeploy. No automatic support for client `fetch` — direct calls with `x-deployment-id: process.env.NEXT_DEPLOYMENT_ID`. Details in `references/nextjs.md`.

SvelteKit

npm install -D @sveltejs/adapter-netlify

import adapter from '@sveltejs/adapter-netlify';
export default { kit: { adapter: adapter() } };

Replace `@sveltejs/adapter-auto` with the specific import. SSR routes → a `render` function.

• `split: true` → one function per route. **Incompatible with Edge Functions** (`edge: false` or omit).
• `edge: true` → SSR in a Deno edge function; can't combine with `split`.
• **Redirects NOT supported in `netlify.toml`** — use `_redirects`.
• Edge functi