Move handlebars template and partial compilation to the server

[philayres]

Requirements

Assume that we've already run npm install --global handlebars

In the page code where we currently render the Handlebars templates (possibly ApplicationHelper#handlebars_template_tag), we should :

• generate a filename prefix using a cache key common to all users relying on the:
  • Application.server_cache_version
  • @item_updates (refactor by extracting this from partial_cache_key method)

For each Handlebars template requested in handlebars_template_tag:

• generate a filename for the Handlebars files
  • input file is rendered markup
  • output file is Handlebars compiled Javascript
• render a javascript_include_tag to tell the browser to load the output file from public/handlebars
• check if the output file already exists in public/handlebars
• if it exists, just return!
• otherwise, have the Handlebars templates render to the input file (not the action response) by:
  • calling the handlebars command line with the tmp/handlebars/<input filename> and "public/handlebars/" we generated above

We need to have good logging for errors that occur in this process.

In an initializer, we should:

• check that the handlebars command is available and produce a configuration error if not
• create the public/handlebars subdirectory if needed
• create the tmp/handlebars subdirectory if needed
• delete any files from tmp/handlebars
• delete any files from the handlebars subdirectory older than 24 hours

NOTE: we should check the Rails partials that generate the Handlebars templates, to ensure they don't contain any other markup. If there is anything else (I know of one place where there is an inline <script> tag) then we should move that markup outside the partial into the calling page.

Resources

See https://handlebarsjs.com/installation/precompilation.html#getting-started

Deployment

As as starting point, npm is available on AWS Elastic Beanstalk servers. Within the initial platform setup files, we can do a simple:

npm install --global handlebars

This will ensure that handlebars is available to the webapp user that Rails runs under.

[philayres]

Implementation Plan Summary

Overview

Move Handlebars template compilation from client-side JavaScript to server-side precompilation using the handlebars CLI. Templates will be precompiled to JS files in public/handlebars/ and served as static assets.

Key Design Decisions

• Two loading paths: Inline templates (page load) and AJAX-loaded templates both use precompiled JS
• Cleanup on startup: Delete ALL files from public/handlebars/ (no stale file retention)
• No fallback: Always require precompilation - fail if CLI unavailable
• Registry aliasing: _fpa.templates = Handlebars.templates and _fpa.partials = Handlebars.partials
• Partial registration: CLI --partial flag auto-registers to Handlebars.partials
• Minification: Use -m flag in production only
• Source maps: Generate in development only
• Full Handlebars library: Keep for now (due to {{template}}, {{compile_template}} runtime helpers)

Files to Create/Modify

File	Action
config/initializers/handlebars_precompiler.rb	Create - setup directories, cleanup, validate CLI
app/helpers/handlebars_precompiler_helper.rb	Create - cache key, preprocessing, compilation
app/helpers/application_helper.rb	Modify - update handlebars_template_tag to emit <script src>
app/assets/javascripts/app/_fpa.js	Modify - simplify compile_templates(), alias registries
app/views/layouts/_setup_app.html.erb	Modify - handle <script src> loading for AJAX templates
.gitignore	Add /public/handlebars/ and /tmp/handlebars/

CLI Command Pattern

# Templates
handlebars -i "{{content}}" -f public/handlebars/id-hash.js -N "template-id" [-m]

# Partials  
handlebars -i "{{content}}" -f public/handlebars/id-hash.js -N "partial-id" --partial [-m]

Cache Key

Based on Application.server_cache_version + latest updated_at from dynamic definitions (MessageTemplate, DynamicModel, ActivityLog, ExternalIdentifier, ConfigLibrary, PageLayout, AppConfiguration).

Deployment Requirement

npm install --global handlebars

Future Optimization

If {{template}}, {{compile_template}}, {{run_template}} helpers can be eliminated, switch to handlebars.runtime.min.js (28KB vs 88KB).

[philayres]

Implementation Complete: Handlebars CLI Precompilation

Summary

Implemented server-side Handlebars template precompilation using the Handlebars CLI (npx handlebars), with batched template loading to reduce HTTP requests.

Key Changes

New Files:

• app/helpers/handlebars_precompiler_helper.rb - Server-side template precompilation helper
• config/initializers/handlebars_precompiler.rb - CLI setup, directory management, and cleanup on startup

Modified Files:

• app/helpers/application_helper.rb - handlebars_template_tag now queues templates for batched retrieval
• app/assets/javascripts/app/_fpa.js - Added retrieve_requested_handlebars_templates() for AJAX loading of combined template files
• Layout files updated to call retrieve_requested_handlebars_templates at end of body

How It Works

1. Template Queueing: Each handlebars_template_tag call writes the template to a tmp file and queues it for batched retrieval
2. CLI Compilation: Templates are compiled using npx handlebars with proper --partial flags
3. Batched Loading: Multiple templates from the same partial file are combined into a single .js file
4. AJAX Retrieval: Client loads combined template file via $.ajax({ dataType: 'script', cache: true })
5. Completion Tracking: Body gets loaded-templates--{file_id} class when templates are ready

Test Coverage

• 35 helper specs for HandlebarsPrecompilerHelper
• 8 initializer specs for HandlebarsPrecompiler
• 4 system specs verifying end-to-end template loading
• Jasmine specs for _fpa.compile_templates()

Benefits

• Reduced HTML payload size (no inline <script type="text/x-handlebars-template"> blocks)
• Improved caching (compiled .js files can be cached by browser)
• Fewer HTTP requests (templates batched per partial file)
• Test isolation (environment-specific directories prevent parallel test conflicts)

Branch: handlebars-precompilation-873