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.