ChurchTools Extension Boilerplate

This project provides a boilerplate for building your own extension for ChurchTools.

Getting Started

Prerequisites

• Node.js (version compatible with the project)
• npm or yarn

Installation

1. Clone the repository
2. Install dependencies:

   npm install

Optional: Using Dev Container

This project includes a dev container configuration. If you use VS Code with the "Dev Containers" extension, you can:

1. Clone the repository
2. Open it in VS Code
3. Click the Remote Indicator in the bottom-left corner of VS Code status bar
4. Select "Reopen in Container"

The container includes the tools mentioned in the prerequisites pre-installed and also runs npm install on startup.

Configuration

Copy .env-example to .env and fill in your data.

In the .env file, configure the necessary constants for your project. This file is included in .gitignore to prevent sensitive data from being committed to version control.

Development and Deployment

Development Server

Start a development server with hot-reload:

npm run dev

Note: For local development, make sure to configure CORS in your ChurchTools instance to allow requests from your local development server (typically http://localhost:5173). This can be done in the ChurchTools admin settings under: "System Settings" > "Integrations" > "API" > "Cross-Origin Resource Sharing"

If login works in Chrome but not in Safari, the issue is usually that Safari has stricter cookie handling:

• Safari blocks Secure; SameSite=None cookies on http://localhost (Chrome allows them in dev).
• Safari also blocks cookies if the API is on another domain (third‑party cookies).

Fix:

1. Use a Vite proxy so API calls go through your local server (/api → https://xyz.church.tools). This makes cookies look first‑party.
2. Run your dev server with HTTPS. You can generate a local trusted certificate with mkcert.

With proxy + HTTPS, Safari will accept and store cookies just like Chrome.

Building for Production

To create a production build:

npm run build

Preview Production Build

To preview the production build locally:

npm run preview

Deployment

To build and package your extension for deployment:

npm run deploy

This command will:

1. Build the project
2. Package it using the scripts/package.js script

You can find the package in the releases directory.

API

Following endpoints are available. Permissions are possible per route. Types are documented in ct-types.d.ts (CustomModuleCreate, CustomModuleDataCategoryCreate, CustomModuleDataValueCreate)

GET /custommodules get all extensions
GET /custommodules/{extensionkey} get an extensions by its key
GET /custommodules/{moduleId} get an extension by its ID

GET /custommodules/{moduleId}/customdatacategories
POST /custommodules/{moduleId}/customdatacategories
PUT /custommodules/{moduleId}/customdatacategories/{dataCategoryId}
DELETE /custommodules/{moduleId}/customdatacategories/{dataCategoryId}

GET /custommodules/{moduleId}/customdatacategories/{dataCategoryId}/customdatavalues
POST /custommodules/{moduleId}/customdatacategories/{dataCategoryId}/customdatavalues
PUT /custommodules/{moduleId}/customdatacategories/{dataCategoryId}/customdatavalues/{valueId}
DELETE /custommodules/{moduleId}/customdatacategories/{dataCategoryId}/customdatavalues/{valueId}

Support

For questions about the ChurchTools API, visit the Forum.