# How to Enable and Configure the Vacay Vacation Planner Addon in TREK

> Enable and configure the Vacay vacation planner addon in TREK. Admins activate Vacay from the Add-ons page, then users set entitlements, holidays, and collaboration in the UI.

- Repository: [Maurice/TREK](https://github.com/mauriceboe/TREK)
- Tags: how-to-guide
- Published: 2026-07-04

---

**Administrators activate Vacay from the Admin → Add-ons page, after which users configure yearly entitlements, public holidays, and collaboration settings through the Vacay UI.**

TREK treats Vacay as a **global add-on**—a feature not tied to any single trip but available to every user once the admin turns it on. The addon provides a yearly calendar, public-holiday lookup, company-holiday layers, carry-over handling, and the ability to fuse plans with other TREK users. Once enabled, Vacay integrates directly into the main navigation and exposes REST endpoints for programmatic access.

## Enabling the Vacay Addon (Admin Setup)

Before users can track vacation days, an administrator must activate the addon globally.

1. Navigate to **Admin → Add-ons** in the TREK dashboard.
2. Locate the *Vacay* row under *Global add-ons* (enabled by default) and toggle the switch if it is off.
3. The change applies instantly, triggering a success toast, and the *Vacay* entry appears in the main navigation for every user.

According to the repository documentation in [`wiki/Admin-Addons.md`](https://github.com/mauriceboe/TREK/blob/main/wiki/Admin-Addons.md), this single toggle makes the feature available across the entire instance without per-trip configuration.

## Accessing the Vacay Interface

Once enabled, users access the planner through the **Vacay** entry in the left-hand navigation. 

The first time a user opens the page, TREK automatically creates a **personal plan** for that account. The interface immediately displays the current year’s calendar alongside an entitlement panel showing *Entitlement days*, *Used*, *Remaining*, and *Carry-over* values. A year selector in the sidebar allows switching between calendar years.

## Configuring Core Vacation Settings

Click the **gear icon** in the Vacay UI to open the settings panel. Configuration options are stored per-user and affect how days are calculated and displayed.

### Year Plans and Entitlements

Each calendar year operates as a separate panel. The **entitlement panel** tracks your total allowance against used days, showing remaining balance and any carry-over from previous years. Use the year selector in the sidebar to switch between active plans.

### Weekend Blocking and Week Start

Set your calendar preferences to match local norms:

- **Block weekends** – Prevent logging vacation on selected weekend days.
- **Week start** – Choose Monday or Sunday as the first day of the week.

These settings affect the visual calendar grid and validation rules when toggling entries.

### Carry-Over Handling

Enable the **Carry-over** toggle to automatically roll unused days into the next calendar year. When active, TREK calculates remaining entitlements across year boundaries and updates the *Carry-over* display in the entitlement panel.

### Public and Company Holidays

Configure automatic holiday layers:

- **Public holidays** – Add country or region calendars (data fetched from the Nager.at API) to gray out non-working days automatically.
- **Company holidays** – Enable a shared company-holiday layer that appears for all users but **does not** deduct from personal allowances.

These configurations are documented in [`wiki/Vacay.md`](https://github.com/mauriceboe/TREK/blob/main/wiki/Vacay.md) under the Settings section.

## Setting Up Collaborative Plans

Vacay supports fused plans where multiple users can view and manage each other's time-off.

Use the **+** button in the *Persons* panel to invite another TREK user by email. Once the invite is accepted, both users see each other’s logged days in distinct colors and can log days on each other’s behalf. To separate plans again, use the **Dissolve** action in Settings.

This collaboration feature is implemented in the Vacay addon logic and documented in [`wiki/Vacay.md`](https://github.com/mauriceboe/TREK/blob/main/wiki/Vacay.md).

## API Endpoints and Schema Validation

The Vacay addon exposes REST-style endpoints under the `vacay` scope, allowing external tools and MCP (Model Context Protocol) integrations to interact with calendar data.

### Key Endpoints

```bash

# Full snapshot of the active vacation plan (members, years, config)

curl -H "Authorization: Bearer $TOKEN" \
     "$APP_URL/trek/api/addons/vacay/plan"

# All entries for a specific year (e.g., 2025)

curl -H "Authorization: Bearer $TOKEN" \
     "$APP_URL/trek/api/addons/vacay/entries/2025"

# Public holidays for a year/region (e.g., DE-BY, 2025)

curl -H "Authorization: Bearer $TOKEN" \
     "$APP_URL/trek/api/addons/vacay/holidays/2025?region=DE-BY"

```

These endpoints are listed in [`wiki/MCP-Addon-Tools.md`](https://github.com/mauriceboe/TREK/blob/main/wiki/MCP-Addon-Tools.md).

### Zod Schema Validation

All incoming requests are validated against Zod schemas defined in [`shared/src/vacay/vacay.schema.ts`](https://github.com/mauriceboe/TREK/blob/main/shared/src/vacay/vacay.schema.ts):

- `vacayAddHolidayCalendarRequestSchema` – Validates public holiday calendar additions.
- `vacayToggleEntryRequestSchema` – Validates create/remove day entry operations.
- `vacayInviteRequestSchema` – Validates collaboration invites.

### Programmatic Examples

Toggle a vacation day from a React component:

```tsx
import { api } from '@/utils/api';
import { formatISO } from 'date-fns';

function toggleDay(date: Date) {
  const payload = { date: formatISO(date, { representation: 'date' }) };
  api.post('/api/addons/vacay/toggle', payload).then(() => {
    // UI auto-refreshes via WebSocket (vacay:update)
  });
}

```

Invite a user to share your plan:

```tsx
function inviteUser(email: string) {
  api.post('/api/addons/vacay/invite', { user_id: email }).then(() => {
    alert('Invitation sent!');
  });
}

```

## Summary

- **Enable globally** via Admin → Add-ons in [`wiki/Admin-Addons.md`](https://github.com/mauriceboe/TREK/blob/main/wiki/Admin-Addons.md); changes apply instantly.
- **Automatic provisioning** creates personal plans on first access; no manual setup required.
- **Settings** control weekends, week start, carry-over, and holiday layers (public vs. company).
- **Collaboration** allows fused plans with shared logging and distinct color coding.
- **API access** via `/trek/api/addons/vacay/*` endpoints with Zod validation in [`shared/src/vacay/vacay.schema.ts`](https://github.com/mauriceboe/TREK/blob/main/shared/src/vacay/vacay.schema.ts).

## Frequently Asked Questions

### How do I enable the Vacay vacation planner addon in TREK?

Administrators navigate to **Admin → Add-ons**, locate *Vacay* under *Global add-ons*, and toggle the switch to on. The change is immediate, and the Vacay navigation item appears for all users instantly.

### Can unused vacation days carry over to the next year?

Yes. Enable the **Carry-over** toggle in the Vacay settings panel. When active, TREK automatically calculates remaining entitlement days and rolls them into the next calendar year’s balance.

### How do I share my vacation plan with a colleague?

Click the **+** button in the *Persons* panel and enter the colleague’s email. Once they accept the invitation, both users see each other’s logged days in different colors and can log time on behalf of one another. Use the **Dissolve** action in Settings to separate plans later.

### Where are the API schemas for Vacay defined?

All Zod validation schemas reside in [`shared/src/vacay/vacay.schema.ts`](https://github.com/mauriceboe/TREK/blob/main/shared/src/vacay/vacay.schema.ts). This file contains `vacayAddHolidayCalendarRequestSchema`, `vacayToggleEntryRequestSchema`, and `vacayInviteRequestSchema`, which validate requests to the `/trek/api/addons/vacay/*` endpoints.