Next.js Configuration Guide

After learning NextDevKit's code structure, this section will teach you the core Next.js project configuration files and quickly get started with NextDevKit's existing configurations.

Next.js Configuration Files

Next.js configuration involves several key files that control how your application builds, runs, and deploys. Understanding each configuration file ensures optimal development and production performance.

package.json

package.json is the core configuration file for any Next.js project, defining project metadata, dependencies, and executable scripts.

Basic Project Information

You can first modify the project name and description, for example:

{
  "name": "nextdevkit",
  "version": "1.0.0",
  "description": "next.js template with authentication, payment, and more",
  "packageManager": "pnpm@10.10.0"
}

Core Script Commands

NextDevKit provides a complete set of development and build scripts. You can modify these scripts according to your needs:

{
  "scripts": {
    // Development related
    "dev": "next dev --turbopack",
    "build": "next build",
    "start": "next start",
    
    // Code quality
    "lint": "biome check --write .",
    "lint:fix": "biome check --fix --unsafe .",
    "format": "biome format --write .",
    
    // Database operations
    "db:generate": "drizzle-kit generate",
    "db:migrate": "drizzle-kit migrate",
    "db:studio": "drizzle-kit studio",
    
    // Special commands for cloudflare workers and AWS platforms, available in specific templates
    "build:prod": "pnpm run opennext:build && wrangler deploy --dry-run --outdir=dist",
    "deploy": "pnpm run opennext:build && opennextjs-cloudflare deploy",
  }
}

next.config.ts

Besides modifying the package.json file, you can also modify the next.config.ts file to configure Next.js build and runtime behavior.

NextDevKit includes optimized settings for modern web applications by default. You can modify these configurations according to your needs.

Basic Configuration Structure

import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  // Configuration options
};

export default nextConfig;

Basic Configuration Options

Current NextDevKit Configuration:

import { createMDX } from "fumadocs-mdx/next";
import type { NextConfig } from "next";
import createNextIntlPlugin from "next-intl/plugin";

const withMDX = createMDX();

const nextConfig: NextConfig = {
	// output: "standalone",
	images: {
		remotePatterns: [
			{
				hostname: "**",
			},
		],
	},
};

const withNextIntl = createNextIntlPlugin();

export default withMDX(withNextIntl(nextConfig));

Containerization Configuration:

If you need to deploy your Next.js project to containerized environments, such as AWS ECS, Railway, Fly.io, etc., you can use the output: "standalone" configuration.

const nextConfig: NextConfig = {
  output: "standalone",
};

export default nextConfig;

Image Configuration:

If you need to modify the authorized domain names for images, you can modify the images.remotePatterns configuration. The current template is configured as **, which means all domain names. This is only for everyone's Vibe Coding convenience, so there are no restrictions. If you have security-related needs, please modify it to your domain name.

For more configuration information, please visit Next.js Image Configuration Documentation.

const nextConfig: NextConfig = {
  images: {
    // External image domains
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'images.unsplash.com'
      },
      {
        protocol: 'https',
        hostname: 'avatars.githubusercontent.com'
      }
    ],
  }
};

Important Configuration Notes:

Next.js image optimization in the Vercel platform may cause expensive Image Optimization costs, so if you're worried about cost issues, you can disable image optimization.

const nextConfig: NextConfig = {
  // Turn off automatic optimization of Image Optimization
  images: {
    unoptimized: true,
  },
};

TypeScript Configuration

Finally, you can modify TypeScript configuration according to your needs to ensure type safety and optimal development experience.

NextDevKit TypeScript Configuration

Below is NextDevKit's TypeScript configuration. You can modify these configurations according to your needs.

{
	"compilerOptions": {
		"target": "ES2017",
		"lib": ["dom", "dom.iterable", "esnext"],
		"allowJs": true,
		"skipLibCheck": true,
		"strict": false,
		"noEmit": true,
		"incremental": true,
		"module": "esnext",
		"esModuleInterop": true,
		"moduleResolution": "bundler",
		"resolveJsonModule": true,
		"isolatedModules": true,
		"jsx": "preserve",
		"plugins": [
			{
				"name": "next"
			}
		],
		"paths": {
			"@/*": ["./src/*"],
			"@/public/*": ["./public/*"],
			"@/source": ["./.source"]
		}
	},
	"include": ["next-env.d.ts", ".next/types/**/*.ts", "**/*.ts", "**/*.tsx"],
	"exclude": ["node_modules"]
}

In most cases, you only need to change the paths configuration in compilerOptions to configure your project path mapping.

Path Mapping Benefits

// Before (relative imports)
import Button from '../../../components/ui/button';
import { auth } from '../../../../lib/auth/client';

// After (absolute imports with path mapping)
import Button from '@/components/ui/button';
import { auth } from '@/lib/auth/client';

Environment Variables

After learning all the Next.js configurations, finally we'll learn about environment variable configuration.

If you need to configure environment variables for different environments locally, you can use the following naming conventions to configure application behavior in different deployment environments.

Note that all environment variable files are not recommended to be committed to the git repository.

Environment File Structure

.env                # Local development
.env.production     # Production environment
.env.example        # Template file (committed to repo)

When you run different deployment or startup commands locally, the corresponding environment variable files will be automatically read.

For example, for local development, when you run pnpm dev, it will automatically read the environment variables in the .env file.

If you need to deploy to cloud environments locally via command line, such as cloudflare and AWS, when you run pnpm run deploy locally, it will automatically read the environment variables in the .env.production file.

Local Development

To start a minimal NextDevKit project, you need to configure the following environment variables in your .env file:

BETTER_AUTH_SECRET is a random string used for encryption and hash generation. You can generate a secure 32-character key using the following command:

# Generate a secure 32-character key
openssl rand -base64 32

If you're using the Cloudflare Workers template, you can skip setting DATABASE_URL since it can use the built-in SQLite database.

If you're using the Next.js template, you need to configure DATABASE_URL to connect to your database. You can choose database services like Neon or Supabase. Refer to the PostgreSQL Database Configuration for setup details.

After configuring the minimal environment variables, you can start your NextDevKit project locally:

pnpm dev

Visit http://localhost:3000 in your browser, and you should see the default landing page.