Next.js Documentation

Overview

Next.js is a React framework for production with server-side rendering, static site generation, and API routes. Alkimist provides full support for Next.js applications.

React Section

Next.js is built on top of React.

In practice:

• You build UI using React components.
• Next.js handles routing, rendering strategy, and production server behavior.
• Your deploy should ensure React pages/components and API routes are production-ready.

Project Structure

A typical Next.js application structure:

app/
  page.js
  api/
pages/
  api/
next.config.js
package.json

Health Check Endpoint

Next.js applications can implement a /up endpoint using API routes. Here's how:

App Router (Next.js 13+)

// app/api/up/route.js
export async function GET() {
  return new Response('ok', {
    status: 200,
    headers: {
      'Content-Type': 'text/plain',
    },
  });
}

Or using NextResponse:

// app/api/up/route.js
import { NextResponse } from 'next/server';

export async function GET() {
  return NextResponse.json({ status: 'ok' }, { status: 200 });
}

For plain text response:

// app/api/up/route.js
import { NextResponse } from 'next/server';

export async function GET() {
  return new NextResponse('ok', {
    status: 200,
    headers: { 'Content-Type': 'text/plain' },
  });
}

Pages Router (Next.js 12 and earlier)

// pages/api/up.js
export default function handler(req, res) {
  res.status(200).send('ok');
}

Or with JSON:

// pages/api/up.js
export default function handler(req, res) {
  res.status(200).json({ status: 'ok' });
}

Advanced Health Check

With database and dependency checks:

// app/api/up/route.js
import { NextResponse } from 'next/server';

export async function GET() {
  try {
    // Check database connection
    // await db.query('SELECT 1');

    // Check Redis connection
    // await redis.ping();

    return new NextResponse('ok', {
      status: 200,
      headers: { 'Content-Type': 'text/plain' },
    });
  } catch (error) {
    return new NextResponse('error', {
      status: 503,
      headers: { 'Content-Type': 'text/plain' },
    });
  }
}

Package Configuration

Your package.json should include:

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  },
  "dependencies": {
    "next": "^14.0.0",
    "react": "^18.0.0",
    "react-dom": "^18.0.0"
  }
}

Environment Variables

Common Next.js environment variables:

• DATABASE_URL (for database connections)
• REDIS_URL (if using Redis)
• NEXT_PUBLIC_API_URL (for client-side API calls)
• NODE_ENV=production

Deployment

Alkimist automatically:

1. Detects Next.js from package.json
2. Builds the application
3. Configures the production server
4. Sets up environment variables

Before you deploy, do this:

1. Commit and push your latest code to GitHub.
2. Make sure your React/Next app builds successfully (npm run build or your package manager equivalent).
3. Confirm your healthcheck endpoint is available (recommended /up).
4. Start deployment from Alkimist.

Example Project

Minimal Next.js app with health check:

// app/api/up/route.js
export async function GET() {
  return new Response('ok', { status: 200 });
}

// app/page.js
export default function Home() {
  return <h1>Hello Next.js</h1>;
}

The health check will be available at /api/up and return "ok" when the application is running.

Note: If you want the health check at /up instead of /api/up, you can use middleware or a custom server configuration.