Quick Start Guide

TL;DR (Fastest Way)

1. bun install 2) cp .env.example .env.local 3) bun run init 4) bun run dev

bun install && cp .env.example .env.local && bun run init && bun run dev

📋 Overview

• Environment: Node.js 20.9+, PostgreSQL 16+ (or cloud service), recommended package manager: bun.
• Goal: Complete "Install → Initialize → Start" in 10 minutes.

This guide will help you complete the project's environment setup and startup in 10 minutes.

Prerequisites

🍴 Get Project

Method 1: Fork Project (Recommended)

Recommended: This allows you to keep your own modifications while easily receiving upstream updates.

1. Visit NextJS Base GitHub Repository
2. Click the Fork button in the top right corner
3. Select your GitHub account as the target
4. After Forking, clone your own repository:

# Replace your-username with your GitHub username
git clone https://github.com/your-username/nextjs-base.git my-project
cd my-project

5. (Optional) Add upstream repository for syncing updates:

git remote add upstream https://github.com/huglemon/nextjs-base.git

# Later sync upstream updates
git fetch upstream
git merge upstream/develop

Method 2: Use Template

If you want to be completely independent without maintaining a connection to the original repository:

1. Visit NextJS Base GitHub Repository
2. Click Use this template → Create a new repository
3. Fill in your repository name and click create
4. Clone the newly created repository:

git clone https://github.com/your-username/your-repo-name.git
cd your-repo-name

Method 3: Direct Clone (For Experience Only)

⚠️ Note: Direct cloning cannot push modifications to the original repository, only suitable for quick experience.

git clone https://github.com/huglemon/nextjs-base.git
cd nextjs-base

🔧 Environment Setup

1. Install Dependencies (Recommended: bun)

2. Configure Environment Variables

Copy the environment variable template:

cp .env.example .env.local

Edit the .env.local file:

# Database Connection (Required)
DATABASE_URL="postgresql://username:password@localhost:5432/your_database?schema=public"

# Better Auth Configuration (Required)
BETTER_AUTH_SECRET="your-secret-key-at-least-32-characters"
BETTER_AUTH_URL="http://localhost:3000"

# Cloud Storage (Optional, for asset management)
# Supports: r2, s3, aliyun, qiniu - switch via CDN_MODE
CDN_MODE="r2"
R2_ACCOUNT_ID="your-account-id"
R2_ACCESS_KEY_ID="your-access-key"
R2_SECRET_ACCESS_KEY="your-secret-key"
R2_BUCKET_NAME="your-bucket"
R2_PUBLIC_URL="https://your-bucket.r2.cloudflarestorage.com"
# For more storage service configurations, see /docs/admin/guides/STORAGE

3. Prepare Database

Local PostgreSQL

# Login to PostgreSQL
psql -U postgres

# Create database
CREATE DATABASE your_database;

# Exit
\q

Use Cloud Database (Recommended)

Recommended cloud database services, no local installation required:

After creating the database, fill in the connection string in .env.local's DATABASE_URL.

🚀 One-Click Initialization

Execute Initialization

Just run one command to complete all initialization work:

This command will automatically complete:

1. ✅ Load .env.local environment variables
2. ✅ Generate Prisma Client
3. ✅ Create database table structure
4. ✅ Import seed data (RBAC permissions, menus, example data)
5. ✅ Create super admin account (interactive email and password input)

╔═══════════════════════════════════════════════════════════╗
║           NextJS Base Admin - Initialization              ║
╚═══════════════════════════════════════════════════════════╝

[1/4] Checking environment...
   ✓ Loaded environment from .env.local
   ✓ DATABASE_URL found

[2/4] Setting up database schema...
   ✓ Prisma Client generated
   ✓ Database schema created

[3/4] Importing seed data...
   ✓ 43 permissions created
   ✓ 17 menus created
   ✓ 8 roles created
   ✓ 3 example records created

[4/4] Creating super admin account...
   Admin Email: [email protected]
   Admin Password: ********
   ✓ Super admin created

╔═══════════════════════════════════════════════════════════╗
║           ✅ Initialization Completed!                    ║
╚═══════════════════════════════════════════════════════════╝

Non-Interactive Initialization (CI/CD)

If you want to skip interactive input, you can preset admin information via environment variables:

Step-by-Step Execution

If you want more granular control over the initialization process:

🎉 Start Project

Development Mode

Access Application

Use the admin account you created during initialization to log in to the admin panel.

⚠️ Security Tip: Please use a strong password and change it regularly in production!

👤 Super Admin Explanation

What is a Super Admin?

Super admin is the highest-privilege user in the system:

Important: role: 'admin' has all permissions and does not need RBAC role assignment.

User Type Comparison

📦 Seed Data Explanation

The initialization script imports the following preset data (using fixed IDs, all installation system data is consistent):

RBAC Data

Preset Roles

Example Data

✅ Verify Installation

Checklist

• Project starts successfully without errors
• Can access frontend home page
• Can access admin login page
• Can log in with admin account
• Admin menu displays normally (Dashboard, Example, User & Permission, System, Links)
• Can access Example > Data Table > Basic page

Common Issues

DATABASE_URL="postgresql://username:password@host:port/database_name?schema=public"

# Check if file exists
ls -la .env.local

# Check content
cat .env.local

# Reset database (will delete all data)
bunx prisma migrate reset

# Re-run initialization
bun run init

🎯 Next Steps

Congratulations on completing project initialization! Next you can:

📜 Available Commands