Back to all articles

Using Git Submodules for Transactional Email Templates

Tags:
Email templatesgitnextauthsubmodules

Managing transactional email templates in large projects can be challenging. Using a Git submodule is a clean way to separate and version your templates, especially when multiple services or teams need to collaborate.

Why Use Git Submodules?

  • Separation: Keep templates out of your main app code.
  • Versioning: Update templates independently.
  • Reusability: Share templates across projects.

Example: NextAuth with a Template Submodule

Suppose your project structure looks like this:

my-app/
  ├─ email-templates/
  │    └─ transactionals/  # submodule with templates
  │         └─ dist/
  │              └─ passwordless-login-with-link.html
  ├─ pages/
  │    └─ api/
  │         └─ auth/
  │              └─ signinemail.ts
  └─ ...

In signinemail.ts, you can load and customize an HTML template from the submodule:

// filepath: pages/api/auth/signinemail.ts
import fs from 'fs'
import path from 'path'
// ...existing code...

function html({ url, host, theme }) {

  // Define the path to the HTML file
  const htmlFilePath = path.join(
    process.cwd(),
    'email-templates/transactionals/dist/passwordless-login-with-link.html',
  )

  // Read the HTML content from the file
  const htmlContent = fs.readFileSync(htmlFilePath, 'utf8')

  // Replace all occurrences of ${url} with the actual url value
  return htmlContent.replace(/\${url}/g, url)
}
// ...existing code...

And your HTML template in the submodule might look like:

<!-- filepath: email-templates/transactionals/dist/passwordless-login-with-link.html -->
<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <title>Sign in to your account</title>
</head>
<body>
  <div class="container">
    <h1>Welcome back!</h1>
    <p>Click the button below to sign in to your account:</p>
    <div class="button-container">
      <a href="${url}" class="button">Sign in</a>
    </div>
    <p class="footer">If you didn't request this email, you can safely ignore it.</p>
  </div>
</body>
</html>

Workflow

  1. Add the submodule:
    git submodule add <repo-url> email-templates/transactionals
  2. Update templates independently in the submodule repo.
  3. Pull updates with:
    git submodule update --remote email-templates/transactionals

This approach keeps your transactional emails organized, versioned, and easy to update across projects.