Project structure

This page provides you an overview of the folder and files conventions in creating contentql themes, as well as tips for organizing your project.

Folder and file conventions

The contentql project structure is similar to what you've seen in payload cms with pre-default media, users and blogs collections.

Top level Folders

Folders	Description
`actions`	authentication using next safe actions
`app`	Next.js app folder
`components`	All the components related logic
`emails`	Resend Emails templates
`payload`	payload cms folder
`scripts`	scripts related code
`seed`	seeding process
`trpc`	typescript RPC mutation related code
`utils`	utilies folder

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.

Folder Descriptions

Folder Name	Description
`(app)/(account)`	Contains account-related logic
`(app)/(auth)`	Handles authentication functionality
`(app)/(marketing)`	Contains logic for rendering marketing blocks
`(payload)/(admin)`	payload admin code
`(payload)/(api)`	api related logic

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:

File Name
`.env.example`	Required environment variables
`next.config.ts`	Configuration file for Next.js
`package.json`	Project dependencies and scripts
`payload-types.ts`	Automatically generated types
`payload.config.ts`	Configuration file for Payload CMS
`tailwind.config.ts`	Configuration file for tailwind css
`tsconfig.json`	Configuration file for typescript

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.

package.json

next.config.mjs

Organizing your project

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 two core files:

Component.tsx
config.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.

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

Collections

By default, you'll get a few collections such as media, blogs, users, pages, tags.