[DEV-3700][DEV-3701] Refactor cognito-functions email templating to use build-time precompiled templates

[Sebastiano-Bertolin]

This pull request introduces a build-time MJML email template compilation pipeline for the Cognito Lambda functions package, replacing runtime MJML and HTML minification. The new approach generates precompiled HTML templates during build, reducing Lambda dependencies and improving performance. It also updates scripts, configuration, and handler code to support the new pipeline and cleans up unused dependencies.

List of Changes

Build pipeline and template precompilation:

• Added scripts/generate-email-templates.js to compile MJML templates to minified HTML at build time, writing them to src/templates/generated/precompiled-email-templates.ts.
• Updated handler code to use renderPrecompiledTemplate for email generation, replacing runtime MJML rendering and minification. (src/templates/confirmation-message.ts, src/templates/confirmation-forgot-password.ts) [1] [2]
• Updated package.json scripts to include template generation in build/test flows, and added a clean step for generated templates.
• Added .gitignore and ESLint ignore rules for generated templates directory. [1] [2]

Dependency and configuration cleanup:

• Removed runtime dependencies on mjml, html-minifier, and their type definitions; switched to html-minifier-next and mjml only for build-time use. [1] [2]
• Simplified esbuild.config.mjs by removing the workaround for MJML's runtime dependency issues, since MJML is no longer bundled into Lambda.

Handler code improvements:

• Refactored OTP and post-confirmation email handlers to use precompiled templates and simplified email body generation. (src/create-auth-challenge-handler.ts, src/post-confirmation-handler.ts) [1] [2] [3] [4]

Documentation updates:

• Added a comprehensive README.md describing the new build pipeline, handler exports, scripts, and workflow.

Motivation and Context

How Has This Been Tested?

Screenshots (if appropriate):

Types of changes

• Chore (nothing changes by a user perspective)
• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)

Checklist:

• My change requires a change to the documentation.
• I have updated the documentation accordingly.

[changeset-bot]

🦋 Changeset detected

Latest commit: adfda0f

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
cognito-functions	Major

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[Copilot]

Pull request overview

This PR refactors the apps/cognito-functions package to precompile MJML email templates at build time, removing runtime MJML/HTML minification from the Lambda bundle and updating handlers to render emails from generated, localized HTML templates.

Changes:

• Added a build-time template generation script that compiles MJML to minified HTML and writes a generated PRECOMPILED_EMAIL_TEMPLATES module.
• Refactored Cognito trigger handlers and template helpers to use renderPrecompiledTemplate with placeholder replacement (instead of runtime MJML + minification).
• Updated scripts/config (tsconfig for scripts, ESLint ignore, .gitignore, esbuild config) and dependency layout (move MJML/minifier tooling to dev deps, introduce DEFAULT_LOCALE).

Reviewed changes

Copilot reviewed 20 out of 21 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
package-lock.json	Updates dependency graph to drop runtime html-minifier/MJML usage and add build-time tooling (incl. html-minifier-next).
apps/cognito-functions/tsconfig.scripts.json	Adds a TS config for running build-time scripts with Node typings.
apps/cognito-functions/src/templates/template-sources.ts	Centralizes MJML source templates and placeholder IDs for build-time compilation.
apps/cognito-functions/src/templates/render-precompiled-template.ts	Adds runtime renderer that selects localized precompiled HTML and replaces placeholders with sanitized values.
apps/cognito-functions/src/templates/post-confirmation-confirm-sign-up-message.ts	Switches welcome email generation to the precompiled template renderer.
apps/cognito-functions/src/templates/otp-message.ts	Switches OTP email generation to the precompiled template renderer (keeping translation-based code duration text).
apps/cognito-functions/src/templates/mjmlParser.ts	Removes runtime MJML → HTML conversion + minification helper.
apps/cognito-functions/src/templates/confirmation-update-email-address.ts	Switches email-change confirmation email to precompiled template rendering.
apps/cognito-functions/src/templates/confirmation-message.ts	Switches sign-up confirmation email to precompiled template rendering.
apps/cognito-functions/src/templates/confirmation-forgot-password.ts	Switches forgot-password email to precompiled template rendering.
apps/cognito-functions/src/post-confirmation-handler.ts	Uses centralized DEFAULT_LOCALE and simplifies body generation for SES welcome email.
apps/cognito-functions/src/i18n/locales.ts	Introduces DEFAULT_LOCALE constant and keeps supported locales list.
apps/cognito-functions/src/custom-message-handler.ts	Uses centralized DEFAULT_LOCALE for locale fallback when generating Cognito custom messages.
apps/cognito-functions/src/create-auth-challenge-handler.ts	Uses centralized DEFAULT_LOCALE and refactors OTP email body creation before SES send.
apps/cognito-functions/scripts/generate-email-templates.ts	Adds build-time compilation + minification pipeline that writes generated TS module.
apps/cognito-functions/package.json	Adds template generation scripts/hooks, cleans generated outputs, and shifts MJML/minifier tooling to dev deps.
apps/cognito-functions/eslint.config.mjs	Ignores generated templates directory in ESLint.
apps/cognito-functions/esbuild.config.mjs	Removes MJML/uglify workaround plugin since MJML is no longer bundled at runtime.
apps/cognito-functions/README.md	Documents the new build-time template pipeline, scripts, and handler responsibilities.
apps/cognito-functions/.gitignore	Ignores generated templates directory.
.changeset/short-peaches-take.md	Declares a major bump and documents the breaking change.

Comments suppressed due to low confidence (1)

apps/cognito-functions/src/create-auth-challenge-handler.ts:85

• subjectTemplate falls back to EMAIL_TRANSLATIONS.otp.it.subject even though the handler now centralizes the default locale in DEFAULT_LOCALE. To keep the fallback behavior consistent (and avoid future drift if DEFAULT_LOCALE changes), use EMAIL_TRANSLATIONS.otp[DEFAULT_LOCALE].subject for the fallback instead of hardcoding it.

      const subjectTemplate =
        EMAIL_TRANSLATIONS.otp[locale as keyof typeof EMAIL_TRANSLATIONS.otp]
          ?.subject || EMAIL_TRANSLATIONS.otp.it.subject;
      const subject = subjectTemplate.replace('{{code}}', verificationCode);

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[github-actions]

This PR exceeds the recommended size of 800 lines. Please make sure you are NOT addressing multiple issues with one PR. Note this PR might be rejected due to its size.

[marcobottaro]

Isn't there a dedicated workflow?

[github-actions]

Jira Pull Request Link

This Pull Request refers to the following Jira issue DEV-3700

[github-actions]

Branch is not up to date with base branch

@Sebastiano-Bertolin it seems this Pull Request is not updated with base branch.
Please proceed with a merge or rebase to solve this.