create-starter-next-app-custom

A command-line tool that scaffolds a Next.js (App Router) template pre-configured with Supabase, secure authentication, and a clean dark-purple glassmorphic design system.

Quick Start

To generate a new project and initialize its dependencies, run:

npx create-starter-next-app-custom my-app

Once the CLI completes, navigate to the folder, set up your environment variables, and start the development server:

cd my-app
npm run dev

Template Features

The scaffolded project includes a fully configured authentication and user management system with the following details:

Design and UI

• Custom Theme: Jet Black background (#030014) with glowing radial purple ambient accents and deep purple (#9333ea) action elements.
• Glassmorphism: Borderless glassmorphic input fields, clean custom checkboxes, and smooth hover micro-animations.
• Notifications: Integrated with sonner for displaying sleek, stackable success and error toast messages.

Security

• Brute-Force Prevention: Accounts are locked automatically for 10 minutes after 5 consecutive failed login attempts (tracked securely in the database).
• Email Verification: Sends activation links containing a 10-minute expiration token via SMTP using nodemailer.
• Terminal Logs: In local development, if SMTP variables are left blank, verification links print directly to the terminal for easy testing.
• JWT Cookie Sessions: Custom stateless JWT sessions signed using the jose library. Selecting "Remember Me" on login extends the session cookie lifespan from 24 hours to 30 days.

Architecture

• Server Actions: All authentication states (sign-up, login, verification, and recovery) are driven securely via Next.js Server Actions in src/actions/auth.ts.
• Database Driver: Connects to your PostgreSQL / Supabase instance using postgres.js for fast query performance.
• Route Groups: Authentication pages are grouped under (client)/ to isolate public auth views from the protected application layout.

Tech Stack

| Component | Technology | Version | Description | | :--- | :--- | :--- | :--- | | Framework | Next.js | 16+ (App Router) | Server-side rendering, layout groups, and Server Actions | | Core UI | React | 19 | UI rendering engine | | Styling | Tailwind CSS | v4 | Modern CSS utility compilation | | Database | Supabase (Postgres) | ^2.105.4 | Relational storage and SSR helper integrations | | DB Client | Postgres.js | ^3.4.9 | Fast PostgreSQL query driver | | Sessions | Jose | ^6.2.3 | Lightweight JWT signature handling | | Hashing | BcryptJS | ^3.0.3 | Salted password hashing | | Mails | Nodemailer | ^8.0.7 | SMTP mail courier with a console-fallback utility | | Alerts | Sonner | ^2.0.7 | Toast notifications |

Project Structure

The scaffolded project is organized as follows:

my-app/
├── public/                  # Static assets (logos, icons)
├── src/
│   ├── actions/
│   │   └── auth.ts          # Server actions for authentication
│   ├── app/
│   │   ├── (client)/        # Pages for login, signup, password reset, and recovery
│   │   ├── verify-pending/  # Pending email verification status page
│   │   ├── verify/          # Verification token processing handler
│   │   ├── globals.css      # Custom Tailwind styling rules and themes
│   │   ├── layout.tsx       # Root layout with the Sonner toast provider
│   │   └── page.tsx         # Root dashboard page (protected)
│   ├── components/
│   │   └── Navbar.tsx       # Responsive navigation bar
│   └── lib/
│       ├── db.ts            # PostgreSQL/Supabase database driver configuration
│       ├── email.ts         # Nodemailer setup and mail templates
│       └── session.ts       # Jose JWT session cookie creation and validations
├── DOC.md                   # SQL database migration script
├── AGENTS.md                # Agent instruction rules for Next.js 16/React 19 compatibility
├── package.json             # Root package file containing scripts & dependencies
└── tsconfig.json            # TypeScript configuration

Configuration

Once the project is scaffolded, run the following steps to configure the database and local variables:

1. Database Table

The database runs on Supabase or any standard PostgreSQL instance.

1. Open the SQL editor in your Supabase or Postgres database console.
2. Copy and execute the SQL query located in DOC.md:

   CREATE TABLE public.users (
     id UUID PRIMARY KEY,
     name VARCHAR(100),
     email VARCHAR(255) UNIQUE NOT NULL,
     password_hash TEXT NOT NULL,
     email_verified_at TIMESTAMP NULL,
     status VARCHAR(20) DEFAULT 'ACTIVE',
     last_login_at TIMESTAMP NULL,
     failed_login_attempts INT DEFAULT 0,
     locked_until TIMESTAMP NULL,
     created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
     updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
   );

2. Environment Variables

Create a local environment file by copying the test template:

cp test.env.example .env.local

Open .env.local and fill in your keys:

• DATABASE_URL: PostgreSQL connection string.
• SESSION_SECRET: A long, random string used for signing JWT cookies.
• NEXT_PUBLIC_APP_URL: The origin URL of your application (e.g., http://localhost:3000).
• Email Settings (SMTP):
  • Configure SMTP_HOST, SMTP_PORT, EMAIL_USER, and EMAIL_PASSWORD to send real emails.
  • Leave SMTP_HOST blank to log verification links to the command line during local testing.

Contributing

Contributions, issues, and feature requests are welcome. Feel free to open a pull request or file an issue on GitHub.

License

This project is open-source software licensed under the MIT License. See LICENSE for details.