git-conventions

Prerequisites

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

Installation

1. Clone the repository
2. Install dependencies:

```bash

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.

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 Server

Start a development server with hot-reload:

```bash

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](https://github.com/FiloSottile/mkcert).

>

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

Building for Production

To create a production build:

```bash

npm run build

```

Preview Production Build

To preview the production build locally:

```bash

npm run preview

```

Deployment

To build and package your extension for deployment:

```bash

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.

Template Administration

The extension includes a template administration interface accessible via the "Admin – Vorlagen" tab. This allows you to:

• Edit Templates: Use the integrated pdfme Designer to modify template layouts
• Template Synchronization: Keep template properties consistent across different formats
• Import/Export: Share template sets as ZIP files with automatic timestamping

#### Template Synchronization

The sync feature helps maintain consistency across multiple template formats (A5 portrait, A5 landscape, etc.):

1. Select Main Template: Choose which template serves as the source of truth
2. View Differences: See property differences between templates (colors, alignment, etc.)
3. Sync Properties: Apply properties from the main template to all other templates

The sync panel shows:

• Number of differences per template
• Detailed diff view showing which properties differ
• One-click sync to apply changes

Properties that can be synced include:

• fontColor - Text color
• color - Background/border color
• alignment - Text alignment
• type - Field type
• borderWidth - Border width

Important: When you sync templates, missing fields from the main template are automatically added to other templates. This ensures all templates have the same fields.

#### Template Persistence

All template changes are automatically sav