跳到主内容
智客 ZICQ

技能库 智客分类:运维与云 netlify-frameworks

Netlify Frameworks

在Netlify上部署和配置网络框架——建立设置和SSR/edge适配器加上本地平台模拟和env vars. 设置或固定框架部署时使用(Next.js / Astro / Nuxt / SvelteKit / Remix / React Router / TanStack Start / SolidStart / Gatsby / Angular / Vite / Express / Hydrgen / Hugo / 11ty / Vue / React),将 SSR或边缘功能或中相接器添加到Netlify上下文,确定SPA重定向和call-all规则,设置构建命令或发布目录,或调试"为什么不是我的env var更新",框架构建失败.

2490 安装量

官方网址:skills.sh

技能介绍

先看中文介绍;官方 description 原文单独保留,不改写 SKILL.md。

做什么

在Netlify上部署和配置网络框架——建立设置和SSR/edge适配器加本地平台模拟和env vars

何时用

设置或固定框架部署(Next.js / Astro / Nuxt / Svelte) Kit / Remix / React Router / TanStack Start / SolidStart / Gatsby / Angular / Vite / Express / Hydrogen / Hugo / 11ty / Vue / React),在Netlify上下文中加入SSF或边缘功能或中件, f

代理如何加载

按 Agent Skills 渐进披露:启动时只加载 name 与 description(约 100 token);任务匹配后才读入整份 SKILL.md 正文;scripts/、references/、assets/ 仅在需要时再读。 本文件正文结构:Env vars: modern rules (read first)、SPA redirects and the SSR catch-all footgun、Local dev with platform emulation (no Netlify CLI)、Build settings by framework、SSR / adapter setup、Astro。

文件分析

文件分析:除 SKILL.md 外,正文引用了 references/astro.md、references/nextjs.md、references/nuxt.md、references/sveltekit.md、references/tanstack.md、references/vite.md,属于带资源的技能包,这些文件按需再读。

官方 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.

Env vars: modern rules (read first)SPA redirects and the SSR catch-all footgunLocal dev with platform emulation (no Netlify CLI)Build settings by frameworkSSR / adapter setupAstroNext.js (13.5+ only)SvelteKitReact Router (7+)RemixNuxtSolidStart

来源分类:skills.sh agent-skill

SKILL.md 与 Agent 调用

官方规范 ↗
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.
  1. 发现技能客户端向 Agent 提供名称与描述目录。
  2. 匹配与调用用户指定或任务匹配后,载入 SKILL.md 指令。
  3. 按需加载按步骤读取参考文档、使用脚本与素材。
指令中引用的文件 · 6
  • references/astro.md
  • references/nextjs.md
  • references/nuxt.md
  • references/sveltekit.md
  • references/tanstack.md
  • references/vite.md

以下路径提取自原文;文件是否齐全请以来源仓库中的完整目录为准。

具体调用语法与可用工具以目标 Agent 客户端为准。 查看调用机制说明 ↗

安装这个技能

Skills CLI ↗

先选择目标 Agent 和安装范围,保留技能包的附属文件,安装后检查客户端能否发现该技能。

该技能引用了附属文件,请从来源获取完整目录;仅复制 SKILL.md 可能缺少依赖。

交给 Agent 安装

复制安装指令给支持 Agent Skills 的代理,确认其中的目标目录与客户端匹配。

把 Agent Skill「netlify-frameworks」安装到我的项目:SKILL.md 原文与官方 description 见 https://zicq.com/zh/skills/skl-c2b4f4a31f90e573-%E4%BA%92%E6%8D%A2%E6%A1%86%E6%9E%B6.html
请存为 .cursor/skills/netlify-frameworks/SKILL.md 或 .claude/skills/netlify-frameworks/SKILL.md,frontmatter 的 name 与 description 保持原样,不要改写。
该技能还带 scripts/、references/、assets/ 等文件,请从 https://github.com/netlify/context-and-tools 取完整目录,不要只建一个 SKILL.md。

GitHub 完整包 ↗

终端安装 · Skills CLI

需要 Node.js 与 npx。先查看仓库技能列表,确认实际名称。

npx skills add 'https://github.com/netlify/context-and-tools' --list

npx skills add 'https://github.com/netlify/context-and-tools' --skill 'netlify-frameworks'

CLI 会交互选择目标 Agent,默认安装到项目;用户级安装使用 -g。先通过查看命令核对仓库内容,再用 npx skills list 检查已安装技能。

阅读排版
--- 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: ```toml [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 ``. 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 ```bash npm install -D @sveltejs/adapter-netlify ``` ```js 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 functions don't work locally with `netlify dev` for SvelteKit. ### React Router (7+) New: `npx create-react-router@latest --template netlify/react-router-template`. Existing: ```bash npm install @netlify/vite-plugin-react-router ``` Add `netlifyReactRouter()` to Vite plugins. Default target = Serverless Functions. **Edge (Deno):** needs plugin v2.1.1+, set `edge: true`, and you **must** create `app/entry.server.tsx`: ```typescript export { default } from 'virtual:netlify-server-entry' ``` Exclude your own function paths: `netlifyReactRouter({ edge: true, excludedPaths: ['/api/*'] })`. **Moving back to Serverless:** remove `edge: true` AND delete `app/entry.server.tsx`. Middleware (React Router v7.9.0+, plugin v2.0.0+): opt in via `future.v8_middleware`; import `netlifyRouterContext` from `@netlify/vite-plugin-react-router/serverless` (or `/edge` when `edge: true`); access `context.get(netlifyRouterContext)`. ### Remix New: `npx create-remix@latest --template netlify/remix-template` (CLI prompts functions vs Edge Functions). Manual (Remix Vite required): ```bash npm install --save-dev @netlify/remix-adapter ``` Add `netlifyPlugin()` from `@netlify/remix-adapter/plugin` to Vite plugins. ### Nuxt SSR via Nitro, automatic on Nuxt 3. Local parity via `@netlify/nuxt` (`npx nuxi module add @netlify/nuxt`). - SSR on Edge Functions requires a different Nitro deployment preset (not auto-detected). - pnpm + Nuxt 3: set `PNPM_FLAGS=--shamefully-hoist`. - `nuxt/image` auto-uses Netlify Image CDN; set remote domains in `nuxt.config.ts`. ### SolidStart SolidStart 2 builds on Vite — **no SolidStart-specific adapter**. Install `@netlify/vite-plugin`: ```ts import netlify from "@netlify/vite-plugin"; import { solidStart } from "@solidjs/start/config"; import { defineConfig } from "vite"; export default defineConfig({ plugins: [solidStart(), netlify({ build: { enabled: true } })], }); ``` Publish `dist/client`. SSR routes, server functions, middleware → Netlify Functions, zero extra config. **Nitro alternative:** add `nitro()`, use plain `netlify()` (no `build.enabled`), publish `dist`. SolidStart 1: Nitro auto-configures; optionally set `preset: "netlify"` in `app.config.ts`; `vinxi build` / `dist`. ### TanStack Start React (and Solid.js) full-stack; SSR/Server Routes/Server Functions/middleware → serverless functions. ```bash npm install -D @netlify/vite-plugin-tanstack-start ``` Add `netlify()` to Vite plugins alongside `tanstackStart()`; `vite build` / `dist/client` (1.132.0+). Netlify CLI deploys require netlify-cli 17.31+. Older versions: see `references/tanstack.md`. ### Gatsby - **5.12.0+ (adapter):** auto-detects and installs `gatsby-adapter-netlify` (zero-config). Generates functions `SSR`, `DSG`. No Essential Gatsby plugin needed. - **5.11.0 or earlier (Essential Gatsby plugin):** auto-installs `@netlify/plugin-gatsby`; also manually install `gatsby-plugin-netlify` (required for SSR, Gatsby redirects, asset caching). Generates `__api`, `__ssr`, `__dsg`, `__ipx`. Skip via `NETLIFY_SKIP_GATSBY_FUNCTIONS` (all) / `NETLIFY_SKIP_API_FUNCTION` / `NETLIFY_SKIP_SSR_FUNCTION` / `NETLIFY_SKIP_DSG_FUNCTION`. - Gatsby 5 requires Node 18. - Large sites: set `GATSBY_EXCLUDE_DATASTORE_FROM_BUNDLE` to load datastore from CDN (avoids max function deploy size; slower first SSR/DSG load). - Image CDN: set `NETLIFY_IMAGE_CDN=true` (Contentful/Drupal/WordPress source plugins). **Not supported on 5.12.x with adapter — upgrade to 5.13.0+.** - `StaticImage` and `gatsby-transformer-sharp` don't work for SSR/DSG — host images on a CDN. ### Angular SSR auto-configured via an Edge Function. Suggested dev: `ng serve` / `4200`. - **SSR pages are NOT subject to `_redirects` or `netlify.toml` redirects** — SSR uses Edge Functions that run before redirects. Use Angular's built-in redirects. - Access `Request`/`Context` in SSR via `netlify.request` / `netlify.context` providers (from `@netlify/edge-functions`); unavailable client-side or during prerendering. Test locally with `netlify serve`. - `NgOptimizedImage` auto-uses Image CDN; set `remote_images` (array of regex) under `[images]` in `netlify.toml`. ### Express Node 18.14.0+. Deploy as a Netlify Function via `serverless-http`: ```bash npm i express serverless-http @netlify/functions @types/express ``` ```ts // netlify/functions/api.ts import express, { Router } from "express"; import serverless from "serverless-http"; const api = express(); const router = Router(); router.get("/hello", (req, res) => res.send("Hello World!")); api.use("/api/", router); export const handler = serverless(api); ``` ```toml [functions] external_node_modules = ["express"] node_bundler = "esbuild" [[redirects]] force = true from = "/api/*" status = 200 to = "/.netlify/functions/api/:splat" ``` No frontend: set a placeholder build command (e.g. `echo Building Functions`). All Function limits apply; not recommended as background/scheduled functions. ### Hydrogen Shopify stack on React Router 7. **SSR only on Netlify Edge Functions — Netlify Functions NOT officially supported.** Node 24+. Use the starter: ```bash npm create @shopify/hydrogen@latest -- --template https://github.com/netlify/hydrogen-template cp .env.example .env && npm run dev ``` ## Static-site gotchas ### Hugo Set `HUGO_VERSION` (any release after 0.19) in `[build.environment]` — a missing/mismatched version causes `exit code: 255`. Install themes as **git submodules** (`git submodule add ...`), not `git clone`. ### Eleventy `eleventy` / `_site`. **Build plugins require editing `.gitignore`: change `node_modules` to `**/node_modules/**`** — otherwise Netlify plugins and Eleventy collide on `.netlify/plugins/node_modules/` and the build errors. ## Vite meta-framework support matrix Astro (auto on 5.12+), Nuxt (via `@netlify/nuxt`), TanStack Start (via `@netlify/vite-plugin-tanstack-start`), React Router, SolidStart — all **full**. SvelteKit — **experimental**. ## Deploy via CLI (Express, Nuxt, React, Vite) ```sh npm install netlify-cli -g netlify init ``` Follow prompts to create/link the site and set build settings. # Netlify house rules (frameworks) These are org conventions, not docs facts — merged into the rendered skill by ctx-gen and never generated. Owned by the skills maintainer. 1. Per-framework deep guides live in this skill: `references/astro.md`, `references/nextjs.md`, `references/nuxt.md`, `references/sveltekit.md`, `references/tanstack.md`, `references/vite.md` — route framework-specific work there before improvising. 2. Next.js: modern runtime (v5, Next ≥13.5) only — treat the legacy adapter as read-only history, never a recommendation. 3. Remove any SPA catch-all (`/* → /index.html 200`) when adopting an SSR adapter — user redirects beat adapter-generated routes, so a leftover catch-all silently serves static `index.html` for SSR pages and API routes. 4. Any env var change — client- or server-side — requires a redeploy. Values are injected at build time; editing one in the UI/CLI does not reach the live site or already-deployed functions until a new build runs. 5. `netlify dev` with both a custom `command` and a `targetPort` requires `framework = "#custom"` in the `[dev]` block — otherwise the detector runs and the custom command is silently ignored. 6. Never use a client prefix (`VITE_`, `NEXT_PUBLIC_`, `PUBLIC_`, `NUXT_PUBLIC_`, `REACT_APP_`, `GATSBY_`, `VUE_APP_`) for secrets — client-prefixed vars are inlined into the browser bundle. 7. Next.js skew protection is version-conditional: below Next 14.1.4 the `NETLIFY_NEXT_SKEW_PROTECTION` env var is not sufficient on its own — `experimental.useDeploymentId` (plus `useDeploymentIdServerActions` when server actions are used) must also go in `next.config.js`. Always ask for or state the version condition; never present the env var as the whole setup.

相关技能

运维与云

Docker Essentials

用于容器管理,图像操作,调试的基本道克命令和工作流程.

运维与云

Find Skills

从开放的代理技能生态系统中发现并安装技能. 使用时:(1)用户问"我如何做X",X可能拥有现有技能,(2)用户说"为X找到技能"或"是否为X有技能",(3)用户问"你能否做X",X是专门能力,(4)用户想扩展代理能力,(5)用户想搜索工具,模板,或工作流程,(6)用户提到他们希望…

运维与云

Microsoft Foundry

构建,部署,评价,优化,微调,管理微软创始代理,模型,资源最终结束. 用法:铸造、azd ai代理、azd 提供/部署、托管代理脚手架/开发/运行/部署/拖放、即时代理创建、创建代理、更新代理、添加代理工具、援引代理、代理.yaml、评估代理、批量活化、连续活化、持续监测、代理C…

运维与云

Azure Deploy

执行已有.azure/部署计划.md和基础设施文件的ALREADY-PREPARED应用程序的Azure部署。 当用户向 CREATE 请求新应用程序时, 请不要使用此技能 。 这种技能运行了 azd上行, azd 部署, trarraform 应用, 和 az 部署命令带有内置…