Pages CMS Documentation

To run Pages CMS locally, you need PostgreSQL, a GitHub App, a local .env.local file, and the repository checked out. Follow these steps:

1. Clone the repository:

   git clone https://github.com/pagescms/pagescms.git
   cd pagescms

2. Start PostgreSQL locally using Docker:

   docker run --name pagescms-db -e POSTGRES_USER=pagescms -e POSTGRES_PASSWORD=pagescms -e POSTGRES_DB=pagescms -p 5432:5432 -d postgres:16

3. Install dependencies:

   npm install

4. Configure environment variables by creating a .env.local file.

5. Create a GitHub App using the setup helper:

   npm run setup:github-app -- --base-url http://localhost:3000

6. Run database migrations:

   npm run db:migrate

7. Start the application:

   npm run dev

You can extend Pages CMS by adding custom fields within the fields/custom/ directory. Each custom field must reside in its own folder and must include an index.ts or index.tsx file.

Important: Custom field names must be unique. If you use a name that matches a core field, you will override the core field implementation.

The project uses drizzle-kit for database schema management and migrations. The configuration is defined using defineConfig and requires a PostgreSQL dialect. The configuration relies on the DATABASE_URL environment variable for connection credentials.

import { defineConfig } from "drizzle-kit";

export default defineConfig({
  dialect: "postgresql",
  schema: "./db/schema.ts",
  out: "./db/migrations",
  strict: true,
  verbose: true,
  dbCredentials: {
    url: process.env.DATABASE_URL!,
  },
});

The Date field allows users to select dates or date-times. It supports two modes based on the time option and allows for custom storage formats and validation constraints.

Configuration Options

• time (boolean): If set to true, the field uses datetime-local input and the format yyyy-MM-dd'T'HH:mm. If false or omitted, it uses date input and the format yyyy-MM-dd.
• format (string): The format string used when saving the date value (e.g., using date-fns tokens). If not provided, it defaults to the input format.
• min (string): A minimum date constraint. The value must be a valid date string matching the input format.
• max (string): A maximum date constraint. The value must be a valid date string matching the input format.
• required (boolean): If true, the field cannot be empty.

To create a fully functional custom field, your index.ts or index.tsx file should export the following properties:

• schema: A Zod schema used for validation and format coercion when saving the field.
• read: A function to transform the field value when reading it from a file (e.g., converting a specific file format into a standard format).
• write: A function to transform the field value when writing it to a file (e.g., converting a standard format into the specific format required by the file).
• EditComponent: A React component used for editing the field in the CMS interface.
• ViewComponent: A React component used to display the field within a collection view.
• defaultValue: The initial value assigned to the field.

Use the following commands to manage the database state:

• Run migrations: Apply database schema changes.

  npm run db:migrate

- **Clear cache**: Use this if the cache state is known to be stale or corrupted.
  ```bash
npm run db:clear-cache

Use the setup:github-app script to automate the creation of your GitHub App.

Command:

npm run setup:github-app -- [options]

Options:

• --base-url <url>: The base URL of your application (e.g., http://localhost:3000).
• --owner-type <personal|org>: Specify if the owner is a personal account or an organization.
• --org <slug>: The slug of the organization (required if --owner-type is org).
• --app-name <string>: The name of the GitHub App.
• --env <path>: Path to the environment file (e.g., .env.local).
• --no-open: Prevents the script from automatically opening a browser window.