Search by

craftsmith / holidays

alexanderloewe

Public holidays of 18 Western European countries, national and regional, with the legal source for every day: half days, substitute days, public, bank and observance types. Same data and results as the npm package @craftsmith/holidays.

Package info

github.com/craftsmithDev/holidays

Language:JavaScript

pkg:composer/craftsmith/holidays

Statistics

Installs: 33

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

1.0.0 2026-11-15 01:19 UTC

This package is auto-updated.

Last update: 2026-11-15 18:10:35 UTC


README

Public holidays for 18 Western European countries, national and regional, with the legal source for every day. One set of rule files, a PHP package and a JS package that compute the same results, and precomputed JSON files for use without code.

Why another holiday library:

  • Sourced. Every holiday cites the law or official page it comes from, with URL and the date it was read. Each country has a sources.md that explains the sources, how the data was checked, and every difference with two external datasets (OpenHolidays API, date-holidays).
  • Language-independent. The rules are YAML files, validated by JSON Schema. PHP and JS read the same compiled rules, and a test checks that both produce byte-identical JSON for every country, region and year from 2000 to 2050.
  • Typed. Each day says whether it is a statutory day off (public), a bank holiday (bank) or a custom (observance). Half days carry a start time, substitute days point to the day they replace.

Dates are plain calendar dates (YYYY-MM-DD), without time zones.

Countries

Country Regions Notes
Switzerland (CH) 26 cantons public = equal to Sunday under the Labour Act (ArG Art. 20a); see sources
Liechtenstein (LI) 11 municipalities public = Labour Act Art. 18; see sources
Germany (DE) 16 Länder public = gesetzlicher Feiertag in the whole Land under its Feiertagsgesetz; see sources
Austria (AT) 9 Bundesländer public = Feiertag under the Arbeitsruhegesetz (ARG § 7); see sources
France (FR) Alsace-Moselle departments and the overseas territories with their own days (10) public = jour férié under the Code du travail; see sources
Monaco (MC) none public = Loi n° 798; Sunday rule as substitute days; see sources
Italy (IT) 19 regions + the autonomous provinces Bolzano and Trento public = Legge 260/1949 as amended (4 October from 2026); Whit Monday in South Tyrol as observance; no patron-saint days; see sources
San Marino (SM) 9 castelli public = Legge 152/1990; see sources
Vatican City (VA) none public = days off under the personnel regulations of the Holy See and the Governatorato; see sources
Spain (ES) 17 communities, Ceuta, Melilla public = fiesta laboral in the yearly BOE resolution, 2000–2027; see sources
Andorra (AD) 7 parishes public = yearly labour calendar decree, 2024–2027; see sources
Malta (MT) none public = National Holidays and public holidays of Cap. 252; no substitute days; see sources
Portugal (PT) 18 districts, Azores, Madeira public = Labour Code Art. 234 and regional decrees; Carnival is an observance; see sources
United Kingdom (GB) England, Northern Ireland, Scotland, Wales public = bank holiday (1971 Act, Royal Proclamations), with substitute days; see sources
Ireland (IE) none public = Organisation of Working Time Act 1997, Sch. 2; no substitute days; see sources
Belgium (BE) 3 regions public = the ten days of the Holidays Act 1974; see sources
Netherlands (NL) 12 provinces, 3 Caribbean special municipalities public = Algemene termijnenwet Art. 3 day that is a general day off, Arbeidswet 2000 BES in the Caribbean Netherlands; see sources
Luxembourg (LU) none public = Code du travail Art. L. 232-2; see sources

Regions are ISO 3166-2 codes. The sources.md of each country lists the laws, the checks and the open points.

PHP

composer require craftsmith/holidays

PHP 8.2 or later, no dependencies.

use craftsmith\holidays\Holidays;

$holidays = new Holidays();

$holidays->isHoliday('2026-08-01', 'CH');                 // true (nationwide)
$holidays->isHoliday('2026-01-02', 'CH', 'ZH');           // false: a custom in Zurich, not a statutory day off
$holidays->isHoliday('2026-01-02', 'CH', 'ZH', ['public', 'observance']); // true

foreach ($holidays->holidays('CH', 2026, 'SO') as $day) {
    echo $day['date'], ' ', $day['name']['de'], $day['startTime'] ? ' ab ' . $day['startTime'] : '', "\n";
}
// 2026-01-01 Neujahr
// 2026-04-03 Karfreitag
// 2026-05-01 Tag der Arbeit ab 12:00 …

$holidays->next('2026-12-24', 'CH', 'CH-BE');             // ['date' => '2026-12-25', 'id' => 'ch.christmas', …]
$holidays->regions('DE');                                  // [['code' => 'DE-BB', 'names' => […]], …]
$holidays->year('GB', 2027);                               // the full year document, same as json/gb/2027.json

JavaScript and TypeScript

npm install @craftsmith/holidays

ESM, no dependencies, Node 18+ and browsers. Types included.

import { isHoliday, holidays, next, countries, Holidays } from '@craftsmith/holidays';

isHoliday('2026-10-31', 'DE', 'BB');                        // true: Reformation Day in Brandenburg
holidays('LI', 2026);                                       // the 13 statutory days of Liechtenstein
holidays('GB', 2027, 'SCT').filter((h) => h.substituteFor); // 4 Jan for 2 Jan, 27 Dec for 25 Dec, 28 Dec for 26 Dec
next('2026-12-24', 'CH', 'BE');                             // { date: '2026-12-25', id: 'ch.christmas', … }
new Holidays().year('ES', 2026);                            // the full year document

Both packages contain the compiled rules and compute any year from 1583 to 9999. Where the days are set by a yearly decree, the coverage follows the published decrees: Spain 2000–2027 in full (from 2028 only the national days the communities cannot replace), Andorra 2024–2027.

API

Both runtimes have the same methods, arguments and results. A region is ZH or CH-ZH; types defaults to ['public'].

Method Returns
countries() countries with names, languages and regions
regions(country) regions of a country
year(country, year) the full year document (all regions, all types, sources)
holidays(country, year, region?, types?) the holidays of a year; without a region only the nationwide ones
isHoliday(date, country, region?, types?) true or false
next(date, country, region?, types?) the first holiday after the date, or null
previous(date, country, region?, types?) the last holiday before the date, or null

A holiday:

{
  "date": "2026-05-01",
  "id": "ch.labour-day",
  "name": {"en": "Labour Day", "de": "Tag der Arbeit", "fr": "Fête du travail", "it": "Festa del lavoro"},
  "type": "public",
  "startTime": "12:00",
  "substituteFor": null,
  "nationwide": false,
  "regions": ["CH-SO"],
  "sources": ["seco-art20a"]
}

id is stable across years and releases, so you can map it to your own data. Names are given in English and in every local language of the country.

How holidays are typed

Type Meaning
public A statutory day off for employees (in Switzerland: equal to Sunday under the Labour Act). What counts as public is written at the top of each country's rules.yaml and in its row above.
bank Banks close, but it is not a general day off.
observance Customary, optional, or a day off only for some employees or in part of a region. The note in the rules says for whom.
  • Half days keep their type and add startTime, the local time the day off starts (Labour Day in Solothurn from 12:00).
  • Substitute days are extra entries with the same id and substituteFor set to the original date. The original stays in the list.
  • Regional days have nationwide: false, and regions lists where they apply. holidays() without a region returns only the nationwide days.
  • Sunday holidays such as Easter Sunday and Whit Sunday are not listed, unless a Sunday has a legal effect in that country.

Modelling choices are explained in docs/decisions.md; the full format is in docs/format.md.

Without code

The precomputed files cover 2025–2036, the previous year to ten years ahead. For other years, use one of the packages.

json/index.json              countries, regions, year range
json/<cc>/<year>.json        all holidays of a country in a year

jsDelivr serves them from GitHub:

https://cdn.jsdelivr.net/gh/craftsmithDev/holidays@1.0.0/json/index.json
https://cdn.jsdelivr.net/gh/craftsmithDev/holidays@1.0.0/json/ch/2026.json

To get one region from a year file, keep the entries where nationwide is true or regions contains the region. The schema is in schema/year.schema.json.

Scope

  • Country and region level (ISO 3166-1 and 3166-2). No municipal holidays: a day that only some municipalities keep is left out, or listed at region level as an observance with a note.
  • Public holidays only. No school holidays yet.
  • External datasets are a cross-check, not a source. Laws change: check the cited source before you rely on a date for legal or payroll purposes.

Repository

countries/<cc>/rules.yaml    the rules of one country: regions, sources, holidays
countries/<cc>/sources.md    the sources explained, the verification, the comparison with external data
countries/_template/         start here for a new country
src/                         PHP runtime (src/data: compiled rules)
js/                          JS runtime (js/data: compiled rules)
json/                        precomputed year files 2025–2036
schema/                      JSON Schemas for the rules and the output
scripts/                     build, comparison, cross-runtime dump
docs/                        format reference and decisions

Contributing

To add a country, fix a date or add a source, see CONTRIBUTING.md. Every holiday needs an official source; the build rejects rules without one.

Contributors

  • craftsmith (wedot)
  • Claude (Anthropic)

Licence

MIT, © craftsmith. See LICENSE.