Getting Started

This guide will get you from an empty directory to a fully functional Payload CMS v3 and Next.js environment in under five minutes.

Prerequisites

Before starting, ensure your local environment meets these requirements:

• Node.js: v20.x or later
• Package Manager: npm, pnpm, or yarn
• Database: A MongoDB or PostgreSQL connection string (local or cloud-hosted)

1. Create Your Project

There are two ways to initialize a Blok0 project. For most users, we recommend the CLI.

Option A: Use the CLI (Recommended)

The Blok0 CLI handles the heavy lifting, including folder creation and dependency installation. Run the following command in your terminal:

Option B: Manual Clone

If you prefer to manage the git history manually or the CLI is restricted in your environment, clone the repository directly:

2. Environment Configuration

Blok0 uses an .env file to manage your database and secrets. We provide an .env.example to get you started.

Rename .env.example to .env.

Code snippet

3. Launch the Project

With your dependencies installed and environment configured, start the development server:

Your First Win

Once the server starts, navigate to:

http://localhost:3000/admin

You will be prompted to create your first Admin User. Once logged in, you’ll see the Payload Dashboard ready to manage your content.

Troubleshooting

If you run into issues during setup, check these common points:

• Node Version: Ensure you aren't on an older LTS version. Run node -v to check (v20+ is required).
• Port Conflicts: If port 3000 is in use, Next.js may shift to 3001. Check your terminal output for the correct URL.
• Database Connection: Ensure your database service (Docker, local, or Atlas/Neon) is actually running and accessible from your network.
• Missing Dependencies: If the build fails, try deleting node_modules and running npm install again.