Enable Thymeleaf Template Caching for Production Without Breaking Local Development

The problem and the takeaway

Thymeleaf parses templates on every request unless template caching is enabled. In a production Spring Boot application, that repeated parsing adds latency to page rendering and increases CPU usage on the application server. The practical takeaway is to enable Thymeleaf’s template cache only for production profiles, keep it disabled for local development, and verify that template changes require a redeploy or restart before they appear.

What Thymeleaf template caching means

Thymeleaf’s TemplateResolver reads HTML templates from the classpath or file system, parses them into an object model, and caches the result when spring.thymeleaf.cache is set to true. Subsequent requests reuse the parsed template instead of reading and parsing the file again. This reduces view-resolution time, but it also means edits to template files are invisible until the application restarts or the cache is cleared.

Prerequisites

• A Spring Boot application with spring-boot-starter-thymeleaf on the classpath.
• Access to application.properties or application.yml in the source repository or deployment configuration.
• Permission to rebuild, redeploy, or restart the application service.
• A non-production environment where you can test with caching disabled first.

Enable caching per profile

Do not set spring.thymeleaf.cache=true globally. If you do, local template edits will not appear during development. Use Spring Boot profiles so caching is enabled only in production.

Example application.yml:

spring:
  thymeleaf:
    cache: false
    check-template-location: true

---
spring:
  config:
    activate:
      on-profile: prod
  thymeleaf:
    cache: true

Edit this file from your project root or deployment repository. You need read and write access to the file; no special operating-system permissions are required unless the file is owned by a deployment user. The check-template-location: true setting makes Spring Boot fail fast at startup if the templates folder is missing, which is useful before you enable caching.

Apply the change

1. Open application.yml (or application.properties) in the service you want to change.
2. Add the production-profile block shown above, or set spring.thymeleaf.cache=true inside your existing prod profile.
3. Commit and build the artifact. Example build command, run in the project root with read access to the repository and execute permission on the build tool:

./mvnw clean package -Pprod

Expected check: the build completes and packages the updated configuration. Risk: if the prod profile is not defined in your build, the command may fail or use the default profile instead.

1. Deploy to production and restart the application service.
2. Confirm the active profile is prod in the startup logs.

Expected checks

1. Start the application with the prod profile active.
2. Request a Thymeleaf-rendered page, for example https://app.example.com/orders.
3. Confirm the page renders without template-related errors.
4. Enable debug logging for Thymeleaf temporarily to verify parsing happens once per template:

logging:
  level:
    org.thymeleaf: DEBUG

In the logs, expect to see template parsing messages during startup or first request, not on every subsequent page load. If you see parsing on every request, caching is not active.

A second practical check is response timing: measure page-render time before and after enabling caching under a representative load. Caching should not change the rendered HTML, only the server-side work required to produce it.

Limitations and risks

• Stale templates: With caching enabled, changes to .html files do not take effect until the application restarts. This is intentional in production but can confuse teams that expect live template edits.
• Memory usage: Parsed templates remain in memory. Applications with very large numbers of unique templates should monitor heap usage after enabling the cache.
• Fragment and layout changes: If a page uses th:replace or layout fragments, editing a fragment file also requires a restart before the change appears.
• Profile leakage: Accidentally activating the prod profile locally disables live template reloading and slows frontend iteration.

Rollback

Enabling the cache changes application behavior, so a rollback path is necessary. To roll back, set spring.thymeleaf.cache to false in the production profile, rebuild, redeploy, and restart the service. The application returns to parsing templates on each request immediately after restart.

Practical verification after rollback or change

1. Edit a visible text string in a Thymeleaf template, such as a page title.
2. Restart the application.
3. Reload the page and confirm the new text appears.
4. If the text does not appear, confirm the active profile and the value of spring.thymeleaf.cache in the running environment, not just in the source file.

When not to enable caching

Keep caching disabled for local development, feature branches, and any environment where designers or developers edit templates frequently. For short-lived preview environments, the performance gain is usually not worth the redeploy requirement.