Installation

Install Nextly in a new or existing Next.js project with step-by-step instructions.

There are two ways to install Nextly: scaffold a new project with the CLI, or add Nextly to an existing Next.js app manually. Both paths take a few minutes.

Option A: Create a New Project (Recommended)

The create-nextly-app CLI scaffolds a complete Nextly project with your choice of database, storage provider, and project template.

pnpm dlx @nextlyhq/create-nextly-app my-app

npx @nextlyhq/create-nextly-app my-app

yarn dlx @nextlyhq/create-nextly-app my-app

The CLI will prompt you to:

Choose a project template (Blog CMS or Custom)
Select a database (PostgreSQL, MySQL, or SQLite)
Enter your database connection string
Choose a storage provider (Vercel Blob or S3)

Once complete, start the dev server:

cd my-app
npm run dev

Open http://localhost:3000/admin to access the admin panel.

Option B: Add to an Existing Next.js Project

1. Install Packages

Install the core package, admin panel, and database adapter:

pnpm add @nextlyhq/nextly @nextlyhq/admin @nextlyhq/adapter-drizzle

npm install @nextlyhq/nextly @nextlyhq/admin @nextlyhq/adapter-drizzle

yarn add @nextlyhq/nextly @nextlyhq/admin @nextlyhq/adapter-drizzle

Then install your database driver and a storage adapter:

npm install pg

npm install mysql2

npm install better-sqlite3

For media uploads, install a storage adapter:

npm install @nextlyhq/storage-vercel-blob

npm install @nextlyhq/storage-s3

2. Create `nextly.config.ts`

Create a nextly.config.ts file in your project root:

nextly.config.ts

import { defineConfig } from "@nextlyhq/nextly/config";

export default defineConfig({
  collections: [],
  singles: [],

  typescript: {
    outputFile: "./src/types/nextly-types.ts",
  },
});

3. Update `next.config.ts`

Add serverExternalPackages so Next.js doesn't try to bundle server-only dependencies:

next.config.ts

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  serverExternalPackages: [
    "@nextlyhq/nextly",
    "@nextlyhq/adapter-drizzle",
    "pg",
    "better-sqlite3",
    "bcryptjs",
    "sharp",
    "esbuild",
  ],
};

export default nextConfig;

4. Set Up Admin Routes

Create the admin panel catch-all route:

src/app/admin/[[...params]]/page.tsx

"use client";

import "@nextlyhq/admin/style.css";
import { RootLayout } from "@nextlyhq/admin";

export default function AdminPage() {
  return <RootLayout />;
}

Create the admin API catch-all route:

src/app/admin/api/[[...params]]/route.ts

import { createDynamicHandlers, getNextly } from "@nextlyhq/nextly";

import nextlyConfig from "../../../../../nextly.config";

const handlers = createDynamicHandlers({ config: nextlyConfig });

export const GET = handlers.GET;
export const POST = handlers.POST;
export const PUT = handlers.PUT;
export const PATCH = handlers.PATCH;
export const DELETE = handlers.DELETE;
export const OPTIONS = handlers.OPTIONS;

5. Set Up Environment Variables

Create a .env file with your database and auth configuration:

.env

# Database
DB_DIALECT=postgresql
DATABASE_URL=postgresql://user:password@localhost:5432/nextly

# Authentication (REQUIRED)
# Generate with: openssl rand -base64 32
AUTH_SECRET=your-secret-key-at-least-32-characters

# App URLs
NEXTAUTH_URL=http://localhost:3000
NEXT_PUBLIC_APP_URL=http://localhost:3000

# Storage (choose one)
STORAGE_ADAPTER=vercel
BLOB_READ_WRITE_TOKEN=your-vercel-blob-token

6. Run Migrations and Seed

Initialize the database schema and seed default RBAC permissions:

npx @nextlyhq/nextly migrate
npx @nextlyhq/nextly dev --seed

7. Verify

Start the development server and visit the admin panel:

npm run dev

Open http://localhost:3000/admin. You should see the Nextly admin login screen.

Requirements

Requirement	Version
Node.js	>= 18
Next.js	14, 15, or 16
Database	PostgreSQL, MySQL, or SQLite

Next Steps

Quick Start -- Build a blog in 5 minutes
Project Structure -- Understand the file layout
Configuration -- Full configuration reference
Environment Variables -- All environment variables explained

Installation

On this page