Skip to content
  • 7 min read

Next.js Runtime

Amplify supports building and previewing Next.js applications in WebContainers. The NextJS Shadcn starter template provides a fullstack project with shadcn/ui integration.

Next.js in WebContainers

When you select the Next.js template, Amplify injects the xKevIsDev/amplify-nextjs-shadcn-template repo which includes:

  • Next.js App Router : Modern routing with layouts, pages, and server components
  • shadcn/ui integration : Pre-configured component library with Tailwind CSS
  • TypeScript : Full TypeScript support with strict checking
  • Fullstack setup : Both client and server components ready

The project runs inside the WebContainer sandbox with npm install auto-setup and npm run dev backgrounded as the dev server.

Framework detection

Amplify's detectFramework() function (used in /api/vercel-deploy) identifies Next.js projects by checking for:

  • next dependency in package.json
  • next.config.js or next.config.ts file presence

App Router support

The Next.js template uses the App Router (not Pages Router) with these features:

FeatureSupport
Layouts (_layout.tsx)✅ Full support
Pages (page.tsx)✅ Full support
Loading states (loading.tsx)✅ Full support
Error boundaries (error.tsx)✅ Full support
Server Components⚠️ Partial (limited SSR in WebContainer)
Client Components✅ Full support
Route Groups✅ Full support
Parallel Routes⚠️ Partial
API Route Handlers✅ Full support
Middleware⚠️ Limited
Image Optimization⚠️ Limited (no sharp binary)
  • API Route Handlers example

    Next.js API Route Handlers work in WebContainers:

    typescript
    // app/api/hello/route.ts
import { NextResponse } from 'next/server';

export async function GET(request: Request) {
  const data = { message: 'Hello from Amplify!' };
  return NextResponse.json(data);
}

    API routes are accessible in the preview iframe at the /api/hello path.

Live preview

Next.js projects get a live preview in the iframe with:

  • Fast Refresh : Changes reflect in the preview within seconds
  • Error overlay : Next.js dev errors show the familiar red overlay
  • Console capture : Browser console messages forwarded to parent via preview-message events
  • Server-ready detection : webcontainer.on('server-ready', (port, url)) triggers preview rendering

The preview system uses a dedicated port detection mechanism that waits for the Next.js dev server to report ready before showing the iframe.

WebContainer preview

The iframe uses sandbox attributes for security while allowing JavaScript execution.

NextJS Shadcn template

Pre-configured with shadcn/ui components, Tailwind CSS, and TypeScript.

SSR vs CSR in WebContainers

Next.js in WebContainers has important differences from production Next.js:

Server-Side Rendering (SSR):

  • Works for basic cases but is constrained by WebContainer's Node.js runtime
  • Server Components render in the WebContainer's Node.js process
  • Performance is slower than production (WASM-based runtime)

Client-Side Rendering (CSR):

  • Works perfectly — standard browser React rendering
  • Client Components have full browser API access
  • Fast Refresh works reliably
Recommended approach

For the best experience in Amplify, use Client Components primarily. Server Components work for simple data fetching, but complex SSR (streaming, suspense boundaries) may encounter WebContainer limitations.

Limitations

Next.js in WebContainers has these specific limitations:

LimitationDetail
ISR not availableIncremental Static Regeneration requires persistent cache
Middleware limitedEdge runtime not fully available in WebContainer
Image optimization limitednext/image optimization requires sharp (native binary)
SSR constrainedWebAssembly Node.js is slower than native Node.js
No persistent build cacheIn-memory filesystem; rebuild clears cache
No production build testingnext build may fail with heavy dependencies

Learn about LLM providers

Was this page helpful?