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.

Supabase Authentication Setup

This extension uses ChurchTools OAuth with Supabase as the authentication backend.

1. ChurchTools OAuth Configuration

In ChurchTools, configure the OAuth application with:

• Redirect URI: http://localhost:5173 (for development)
• API Basis URL: https://<your-churchtools-instance>.church.tools/
• Authorization URL: https://<your-churchtools-instance>.church.tools/oauth/authorize
• Access Token URL: https://<your-churchtools-instance>.church.tools/oauth/access_token
• Profile URL: https://<your-churchtools-instance>.church.tools/oauth/userinfo

2. Supabase Edge Function Secrets

Deploy the Edge Function and set these secrets in your Supabase project:

# Set the required environment variables for the Edge Function
supabase secrets set CHURCHTOOLS_URL=https://<your-churchtools-instance>.church.tools
supabase secrets set CHURCHTOOLS_CLIENT_ID=<your-churchtools-client-id>

Note: SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY are automatically available in Supabase Edge Functions.

3. Deploy the Edge Function

supabase functions deploy churchtools-callback

4. Environment Variables

Configure these in your .env file:

Variable	Description
VITE_SUPABASE_URL	Your Supabase project URL
VITE_SUPABASE_ANON_KEY	Your Supabase anonymous key
VITE_CHURCHTOOLS_URL	ChurchTools instance URL
VITE_CHURCHTOOLS_CLIENT_ID	ChurchTools OAuth client ID
VITE_OAUTH_CALLBACK_URL	OAuth redirect URI (matches ChurchTools config)

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.