← Cloudflare Workers / workers / framework-guides / web-apps

Next.js

Pomocí vinext můžete vytvořit nebo migrovat aplikaci Next.js a nasadit ji do Cloudflare Workers.

Cloudflare doporučuje vinext ↗ jako výchozí způsob spouštění aplikací Next.js na Cloudflare Workers. vinext nabízí dva výchozí body: vytvořte novou aplikaci připravenou pro Workers pomocí create-vinext-app, nebo přidejte vinext do stávající aplikace Next.js 16 jediným nedestruktivním vinext init (vaše stávající next dev nadále funguje). V obou případech nepotřebujete šablonu specifickou pro Cloudflare.

Už používáte OpenNext? Podívejte se na další cesty nasazení Next.js.

Co je Next.js?

Next.js ↗ je React ↗ framework pro tvorbu full-stack aplikací.

Next.js podporuje server-side rendering, client-side rendering, statické generování, React Server Components, Server Actions, route handlery a middleware.

Co je vinext?

vinext ↗ je plugin pro Vite, který znovu implementuje rozhraní API Next.js. Můžete si ponechat svůj stávající app/, pages/, next.config.js, a public/ adresáře při použití nástrojového řetězce Vite.

vinext je v beta verzi. Před jeho nasazením pro existující produkční aplikaci spusťte kontrolu kompatibility ve složce projektu a projděte si dashboard kompatibility vinext ↗.

npx vinext check

Podporované funkce

vinext podporuje nejběžněji používané funkce Next.js na Cloudflare Workers:

Funkce	podpora vinext	Poznámky
App Router	Podporováno	Zahrnuje layouty, route handlery, metadata, loading, error a not-found routy.
Pages Router	Podporováno	Zahrnuje `getStaticProps`, `getStaticPaths`, a `getServerSideProps`.
React Server Components	Podporováno	Používá podporu React Server Components ve Vite.
Server Actions	Podporováno	Funguje s formuláři a mutacemi na serveru.
Vykreslování na straně serveru	Podporováno	Zahrnuje streamované vykreslování.
Statické generování a statický export	Podporováno	Použijte `output: "export"` pro statické exporty.
Incremental Static Regeneration (ISR)	Podporováno	Používá model cachování stale-while-revalidate, díky kterému Workers mohou obsluhovat obsah z cache a zároveň jej na pozadí obnovovat. Více informací najdete v asynchronní revalidace.
Middleware a proxy trasy	Podporováno	Zahrnuje `middleware.ts` a `proxy.ts`.
`next/*` importy	Většinou podporováno	Prohlédněte si dashboard kompatibility s podrobnostmi na úrovni modulů.
Cloudflare bindings	Podporováno	Použijte `cloudflare:workers` v server components, route handlerech a server actions.
Optimalizace obrázků	Částečně podporováno	Optimalizace obrázků Cloudflare je k dispozici v okamžiku požadavku.

Podrobné výsledky kompatibility najdete v kompatibilita vinext ↗.

Zvolte způsob nastavení

Většina projektů Next.js může začít stejným postupem: otevřete aplikaci Next.js, ověřte kompatibilitu, přidejte vinext a poté nasaďte na Workers.

Použijte Přidat vinext pomocí agenta pokud chcete, aby agent projekt prozkoumal a aplikoval migraci.
Použijte Přidat vinext pomocí CLI pokud chcete přímé a opakovatelné nastavení přes příkazovou řádku.
Použijte Vytvořte projekt připravený pro Cloudflare pokud chcete vytvořit kostru nového projektu, který je již nakonfigurovaný pro Workers.

Přidat vinext pomocí agenta

vinext Agent Skill použijte, pokud chcete, aby kódovací agent zkontroloval váš projekt Next.js, provedl kontroly kompatibility, upravil konfiguraci a spustil vývojový server vinext.

Otevřete svůj projekt Next.js.

Použijte existující projekt, nebo vytvořte projekt pomocí preferovaného postupu nastavení Next.js.
Nainstalujte vinext Agent Skill.
npx skills add cloudflare/vinext
Zadejte prompt svému agentovi.

V nástroji coding agent spusťte následující prompt:
```
migrate this project to vinext
```
Skill spouští kontroly kompatibility vinext, provádí migraci a označuje problémy, které vyžadují ruční zásah.
Vývoj s vinext.

Spusťte vývojový server vinext.
npm run dev:vinext
Sestavujte s vinext.

Sestavte produkční výstup pomocí vinext.
npm run build:vinext
Nasaďte na Workers.

Nasaďte pomocí příkazu vinext Cloudflare deploy.
npx @vinext/cloudflare deploy

Přidat vinext pomocí CLI

Použijte vinext init když chcete přímé nastavení z příkazové řádky. Migrace není destruktivní: vaše stávající nastavení Next.js funguje dál souběžně s vinext, zatímco testujete nasazení do Cloudflare Workers.

Otevřete svůj projekt Next.js.

Použijte existující projekt, nebo vytvořte projekt pomocí preferovaného postupu nastavení Next.js.
Zkontrolujte kompatibilitu.

Z adresáře svého projektu Next.js spusťte kontrolu kompatibility vinext.
npx vinext check
Před pokračováním zkontrolujte všechny nahlášené problémy s kompatibilitou.
Inicializujte vinext.

Spusťte inicializátor vinext a po vyzvání zvolte jako cíl nasazení Cloudflare Workers.
npx vinext init
vinext init nainstaluje závislosti vinext a Vite, přidá skripty vinext, vygeneruje konfiguraci Vite a vytvoří konfiguraci Cloudflare Workers.
Vývoj s vinext.

Spusťte vývojový server vinext.
npm run dev:vinext
Sestavujte s vinext.

Sestavte produkční výstup pomocí vinext.
npm run build:vinext
Nasaďte na Workers.

Nasaďte pomocí příkazu vinext Cloudflare deploy.
npx @vinext/cloudflare deploy

Vytvořte projekt připravený pro Cloudflare

CLI create-cloudflare (C3) použijte, pokud chcete vytvořit nový projekt Next.js již nakonfigurovaný pro Cloudflare Workers.

Vytvořte nový projekt pomocí C3.
npm create cloudflare@latest -- my-next-app --framework=next
Chování příkazu

C3 vytvoří nový projekt Next.js, nakonfiguruje vinext pro Cloudflare Workers, nainstaluje potřebné závislosti a nabídne nasazení aplikace.
Vývoj s vinext.

Přejděte do adresáře projektu a spusťte lokální vývojový server.
npm run dev
Sestavte svou aplikaci.

Před nasazením nebo testováním produkční verze spusťte vygenerovaný build skript.
npm run build
Nasaďte svůj projekt.

Nasaďte svůj projekt na *.workers.dev subdoména nebo vlastní doména.
npm run deploy

Přístup k Cloudflare bindings

V aplikacích vinext nasazených na Workers použijte cloudflare:workers pro přístup k bindings ze serverových komponent, route handlerů a server actions. Definujte bindings v konfiguraci Wrangler a poté vygenerujte typy pomocí wrangler types.

Můžete například importovat env z cloudflare:workers v kódu serverové aplikace pro přístup k D1, R2, KV, Durable Objects, Workers AI, Queues, Vectorize a dalším bindings.

Použijte jinou cestu nasazení Next.js

vinext je doporučenou cestou pro aplikace Next.js na Cloudflare Workers, ale zdokumentované zůstávají i další způsoby nasazení:

Cesta	Kdy použít
adaptér OpenNext	Spravujete existující aplikaci OpenNext, kterou zatím kvůli nekompatibilitě nelze migrovat na vinext.
Statický Next.js na Pages	Vaše aplikace je statický export a vy ji chcete nasadit konkrétně do Cloudflare Pages.