# Préparer un thème de connexion

> Structurer le dossier keycloak-theme/ dans un dépôt GitHub de votre application, ou empaqueter un .jar, en respectant les contraintes de Wakastart.

Un thème de connexion est un thème Keycloak standard. Wakastart lui impose seulement un emplacement, une structure et quelques limites, pour pouvoir le nommer et le déployer sans intervention manuelle.

## Avant de commencer

- Le dépôt qui portera le thème est rattaché à une définition de service de votre application et hébergé sur **GitHub**. Les autres hébergeurs ne sont pas pris en charge pour l'import : utilisez alors un fichier `.jar`.
- Vous connaissez le format des thèmes Keycloak : gabarits FreeMarker (`.ftl`), fichier `theme.properties`, ressources CSS et images. Voir la documentation Keycloak, chapitre « Themes ».

## Créer le dossier du thème

Créez un dossier `keycloak-theme/` à la racine du dépôt. Si le dépôt est un monorepo, placez-le dans le répertoire racine du service (le **root directory** de sa définition de service).

```text
keycloak-theme/
├── login/
│   ├── theme.properties
│   ├── login.ftl                (facultatif : seulement les gabarits que vous modifiez)
│   └── resources/
│       ├── css/marque.css
│       └── img/logo.png
└── email/                       (facultatif)
    ├── theme.properties
    └── messages/messages_fr.properties
```

Chaque sous-dossier porte un type reconnu : `login`, `email`, `account`, `admin` ou `welcome`. Il en faut au moins un.

## Écrire le fichier theme.properties

Héritez d'un thème fourni par Keycloak et ajoutez votre feuille de style :

```properties
parent=keycloak.v2
# Recopiez la valeur « styles » du thème parent, puis ajoutez votre fichier à la fin
styles=<styles du thème parent> css/marque.css
```

:::warning
La propriété `styles` **remplace** la liste du thème parent, elle ne s'y ajoute pas. Si vous déclarez seulement `styles=css/marque.css`, la page de connexion perd tous les styles de Keycloak et s'affiche nue. Recopiez la liste `styles` du `theme.properties` du thème parent dans votre version de Keycloak, puis ajoutez votre fichier **en dernier** : l'ordre fixe la priorité.
:::

Ne faites jamais référence à votre propre thème dans `parent=` ou `import=` : Wakastart renomme le thème à l'empaquetage, et la référence serait rompue. Utilisez un thème de base comme `base`, `keycloak` ou `keycloak.v2`.

## Ajouter un repère visuel pour vos tests

Pendant la mise au point, un bandeau qui ne dépend d'aucun sélecteur interne à Keycloak vous dit, d'un coup d'œil, quelle version est affichée :

```css
body::before {
  content: "Thème marque — v3";
  position: fixed; top: 0; left: 0; right: 0; z-index: 9999;
  padding: 6px 12px; text-align: center;
  font: 700 14px/1.4 ui-monospace, monospace;
  background: #111; color: #f5c400;
}
```

Retirez-le avant de publier en production.

## Empaqueter un .jar (alternative)

Si vous ne passez pas par GitHub, construisez une archive `.jar` dont la racine contient un dossier `theme/` avec **un seul** thème :

```text
mon-theme.jar
└── theme/
    └── marque/
        └── login/
            ├── theme.properties
            └── resources/css/marque.css
```

```bash
mkdir -p build/theme/marque
cp -R keycloak-theme/* build/theme/marque/
(cd build && zip -r ../mon-theme.jar theme)
```

Le nom du dossier (`marque`) est libre : Wakastart le remplace par le nom de version.

## Respecter les limites

| Contrainte | Valeur |
|---|---|
| Taille de l'archive | 50 Mo au plus |
| Taille une fois décompressée | 50 Mo au plus |
| Nombre de fichiers | 5 000 au plus |
| Thèmes par archive | un seul, sous `theme/` |
| Compression | « stored » ou « deflate » ; pas d'entrée chiffrée |

## Vérifier le résultat

- Le dossier `keycloak-theme/` est poussé sur la branche que vous voulez faire importer.
- Le fichier `theme.properties` de chaque type hérite d'un thème de base et ne cite pas votre propre thème.
- Votre feuille de style est la dernière de la liste `styles`.

## Voir aussi

- [Publier un thème de connexion](/v1.0/page-de-connexion/publier-un-theme)
- [Référence du thème de connexion](/v1.0/page-de-connexion/reference)
- [Résoudre les problèmes de page de connexion](/v1.0/page-de-connexion/depannage)
