improve local development process by hot reload

.gitignore

@@ -8,3 +8,6 @@ node_modules/
 
 # misc
 .DS_Store
+
+.idea/
+.vscode/

README.md

@@ -64,6 +64,33 @@ parent=keywind
 
 ## Customization
 
+### Local development
+
+Use docker-compose to initialize Keycloak locally, making it easy to check the results when you edit Keywind.
+
+```bash
+docker compose up -d // start keycloak for testing
+```
+
+Then, select the login theme for the client in Keycloak as Keywind.
+
+Finally, let Vite do its job.
+
+```bash
+pnpm run dev // watch *.ftl changes and regenerate css
+```
+
+You can go to the client's login page to see. The key point here is that for realms with the display name `Keycloak` (by default),
+CSS and JS will use the Vite link, while for other cases, they will still use the built link.
+In `document.ftl`, this trick to enable hot reload when developing the theme and it work.
+
+```
+  <#if realm.displayName == 'Keycloak'>
+    <link href="http://localhost:5173/src/index.css" rel="stylesheet">
+    <script defer src="http://localhost:5173/src/index.ts" type="module"></script>
+  </#if>
+```
+
 ### Theme
 
 When you do need to customize a palette, you can configure your colors under the `colors` key in the `theme` section of Tailwind config file:

docker-compose.yml

@@ -0,0 +1,22 @@
+version: '3.7'
+
+services:
+  keycloak:
+    container_name: keycloak
+    image: quay.io/keycloak/keycloak:latest
+    volumes:
+      - ./theme:/opt/keycloak/themes:ro
+      - db-data:/opt/keycloak/data
+    environment:
+      KEYCLOAK_ADMIN: admin
+      KEYCLOAK_ADMIN_PASSWORD: password
+    command:
+      - start-dev
+      - --spi-theme-static-max-age=-1
+      - --spi-theme-cache-themes=false
+      - --spi-theme-cache-templates=false
+    ports:
+      - 8080:8080
+
+volumes:
+  db-data: {}

theme/keywind/login/document.ftl

@@ -16,7 +16,6 @@
       <link href="${url.resourcesPath}/${favicon?split('==')[0]}" rel="${favicon?split('==')[1]}">
     </#list>
   </#if>
-
   <#if properties.styles?has_content>
     <#list properties.styles?split(" ") as style>
       <link href="${url.resourcesPath}/${style}" rel="stylesheet">
@@ -32,4 +31,9 @@
       <script defer src="${url.resourcesPath}/${script}" type="module"></script>
     </#list>
   </#if>
+
+  <#if realm.displayName == 'Keycloak'>
+    <link href="http://localhost:5173/src/index.css" rel="stylesheet">
+    <script defer src="http://localhost:5173/src/index.ts" type="module"></script>
+  </#if>
 </#macro>