erfa3ly
LoginGet started

Deploy Next.js

Deploy Next.js applications with server-side rendering or static export.

Understanding your setup

erfa3ly automatically detects whether your Next.js app uses:

  • Server-side rendering (SSR)
  • Static export
  • API routes
  • Middleware

You don't need to configure this manually. The platform inspects your next.config.js and package.json to determine the correct runtime.

When to use SSR

Use server-side rendering when you need:

  • API routes (/pages/api/ or /app/api/)
  • Dynamic data fetching at request time
  • getServerSideProps or getStaticProps
  • Server components (App Router)
  • Middleware for authentication or routing
SSR detection: If erfa3ly detects API routes or middleware, it automatically configures SSR mode.

When to use static export

Use static export when:

  • All pages can be pre-rendered at build time
  • No server-side logic is required
  • Maximum performance is critical
  • You want CDN-ready static files

Static export is faster and more cost-effective, but less flexible. If your app uses getServerSideProps, API routes, or middleware, static export won't work.

Configuration

Automatic configuration

erfa3ly automatically configures:

  • Build command: npm run build
  • Start command (SSR): npm run start
  • Output directory (static): out/
  • Node version: Detected from package.json engines field

Static export configuration

For static export, add this to your next.config.js:

next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export',
  images: {
    unoptimized: true, // Required for static export
  },
};


module.exports = nextConfig;
Image optimization: Static export requires images.unoptimized: true because Next.js Image Optimization requires a server.

Environment variables

Next.js supports both build-time and runtime environment variables:

  • NEXT_PUBLIC_* variables are embedded at build time and exposed to the browser
  • Other variables are only available server-side (SSR only)

Add environment variables in the erfa3ly dashboard under your project’s “Environment Variables” section.

bash
# Build-time (exposed to browser)
NEXT_PUBLIC_API_URL=https://api.example.com


# Server-side only (SSR only)
DATABASE_URL=postgres://user:pass@host:5432/db
API_SECRET=secret_key_here

Database connectivity

If you're using a database with Next.js API routes:

  • Provision a managed database (MySQL, PostgreSQL, or MongoDB) from the dashboard when needed.
  • Use the connection string provided by erfa3ly
  • Add the connection string as an environment variable
Managed databases are only accessible from your deployment containers for security.

Troubleshooting

Build fails with “Module not found”

Ensure all dependencies are listed in package.json:

package.json
{
  "dependencies": {
    "next": "^15.5.2",
    "react": "^18.2.0",
    "react-dom": "^18.2.0"
  }
}

SSR not working

If your app should use SSR but is being deployed as static:

  • Check if next.config.js has output: export (remove it for SSR)
  • Verify API routes exist in pages/api/ or app/api/
  • Check deployment logs for detection results

Images not loading (static export)

For static export, Next.js Image Optimization doesn't work. Use unoptimized: true or regular img tags.

Next steps