Project Structure

This guide outlines the folder and file naming conventions within a ContentQL project. We are build on the latest tech stack Next.js 15, React 19 and Paylaod CMS 3.0 beta. We use tailwind CSS for styling.

Next.js Folder Structure

Below is an overview of the folder structure to help you understand how Next.js is organized within ContentQL. The (app) folder contains the UI-related code.

layout.tsx

globals.css

error.tsx

not-found.tsx

theme.scss

Folder Descriptions

Folder Name	Description
`(account)`	Contains account-related logic
`(auth)`	Handles authentication functionality
`(marketing)`	Contains logic for rendering marketing blocks

To learn more about folder naming conventions, refer to the official Next.js documentation:

Top-Level Files

Here are the key configuration files located at the root of the project:

.env

next.config.mjs

package.json

payload-types.ts

payload.config.ts

tailwind.config.ts

tsconfig.json

Payload CMS Folder Structure

The Payload CMS folder structure is integrated into the src/payload directory. This directory contains two important subfolders: blocks and style, with the blocks folder housing the components used throughout the application.

component.tsx

config.ts

index.ts

RenderBlocks.tsx

types.ts

package.json

next.config.mjs

Note

Right now you'll not be able to modify the existing collections, but you'll be able to create new collections.

Blocks Folder Structure

The blocks folder is a key component in theme development. Within this folder, you can organize your blocks based on the specific theme you are building. For example, when developing a blog theme, you might create folders such as Hero, FeaturedPosts, and LatestPosts to structure your blocks accordingly.

Each block is represented as a folder, which contains three core files:

component.tsx
config.ts
index.ts

Naming Conventions for Block Files

Each block folder in the blocks directory follows a standardized naming convention for the files it contains:

File Name	Description
`component.tsx`	Contains the UI logic and presentation for the block.
`config.ts`	Defines the block’s configuration, including its slug and other necessary settings.
`index.ts`	Serves as an entry point that exports both `component.tsx` and `config.ts`.

For more information on defining slugs in config.ts, refer to the Payload CMS Fields documentation.