A Practical Way to Manage Reusable Templates in Serverless Apps
When you first start using Handlebars in AWS Lambda, everything feels simple.
You write a template, pass in some data, compile it, and generate the final HTML. It works well for emails, PDFs, reports, and other dynamic content. But as the project grows, the setup often starts to feel less clean.
One Lambda needs an email template. Another needs the same header and footer. A third uses the same helper functions. Soon, you end up copying .hbs files and shared logic across multiple functions. It works, but it is hard to maintain.
That is where AWS Lambda Layers can help.
A layer gives you a way to keep shared templates and helper logic in one reusable place instead of duplicating them inside every function. This becomes especially useful with Handlebars, because template files do not always behave like normal TypeScript or JavaScript code during the build process.
In this article, we will look at what Handlebars is, what Lambda Layers are, why .hbs files often need special handling, and what benefits and challenges you should think about before using this pattern in production.
Handlebars is a templating engine used to generate dynamic content from a fixed layout and a data object.
You create a template with placeholders like this:
<h1>Hello, {{name}}</h1><p>Role: {{role}}</p>
Then you pass data into it:
{ "name": "Nimal", "role": "Frontend Developer"}
The output becomes:
<h1>Hello, Nimal</h1><p>Role: Frontend Developer</p>
That simple idea is what makes Handlebars useful. It separates the template structure from the data, which makes the code easier to read and reuse.
Developers often use Handlebars for:
It is especially helpful when the same structure needs to be used with different data many times.
An AWS Lambda Layer is a way to package shared files, libraries, or dependencies separately from your Lambda function code.
Instead of including the same files inside every function deployment package, you can place those shared resources in a layer and attach that layer to one or more Lambda functions.
This is useful when multiple functions need the same things, such as:
In Lambda, attached layers are mounted under the /opt directory at runtime. That means your function can read files from the layer while keeping the main deployment package smaller and cleaner.
For Handlebars use cases, this makes layers a practical place to store:
.hbs templates.hbs Files do not Bundle Like TS/JSThis is one of the most important reasons this topic matters.
TypeScript and JavaScript files are usually treated as application code. Build tools such as esbuild, webpack, or similar bundlers understand them well. They compile, transform, and package them into the final Lambda deployment artifact.
But Handlebars templates are different.
Files like .hbs are usually treated as static assets, not executable code. Because of that, they are often not automatically included in the final bundle unless you explicitly copy them or configure your build process to handle them.
So, you might have code like this:
const templateSource = fs.readFileSync('./templates/welcome-email.hbs', 'utf8');
Your TypeScript file gets bundled just fine.
But if the .hbs file is not copied into the final deployment package, the Lambda function will fail at runtime because the template file is missing.
That is where many developers first hit the problem. The application code is deployed, but the template it depends on is not there.
This difference between code files and template assets is a big reason why Handlebars can become messy in serverless projects if not structured carefully.
Lambda Layers help because they give you a cleaner way to manage those non-bundled Handlebars template files.
Before using a layer, many developers keep .hbs files inside the Lambda project and expect them to be available after the TypeScript or JavaScript build. But this is where problems often start. TypeScript and JavaScript files are usually bundled as part of the application code, while Handlebars templates are often treated as static assets. Because of that, .hbs files may not be included automatically in the final deployment package unless they are copied separately.
That means the Lambda function code may deploy successfully, but the template file might be missing at runtime. When the function tries to read the file and Handlebars attempts to compile it, the process fails not because Handlebars itself is broken, but because the template cannot be found in the expected location.
Lambda Layers help solve this by giving those shared templates a predictable place to live. Instead of forcing every Lambda function to carry its own copy of the same .hbs files, partials, and helpers, you can place them in a layer and reuse them across functions. In AWS Lambda, that usually means loading the files from a known path such as /opt/templates, which makes template access much more reliable.
That helps in several ways.
First, it reduces duplication. If five functions use the same email header or PDF layout, you do not need to store that file in five different places.
Second, it improves maintainability. Updating a shared template becomes easier because you can manage it centrally instead of editing the same content across multiple functions.
Third, it keeps your function packages cleaner. The main Lambda code can focus on the business logic, while the shared rendering resources live in the layer.
Fourth, it helps avoid the common deployment issue where .hbs files are not bundled or copied correctly. The layer does not change how Handlebars compiles templates, but it does fix a major part of the real-world problem by making template files available in a consistent shared location.
And finally, it creates a better structure for larger serverless systems. Instead of mixing everything into each individual function, you separate logic from shared rendering assets.
In other words, Lambda Layers are not just a storage trick. They are a practical architectural choice when multiple functions depend on the same Handlebars resources and need those templates to be packaged and loaded reliably at runtime.
Imagine you have a serverless application with three Lambda functions:
All three functions use Handlebars. They also share:
Without a layer, each Lambda might have its own copy of:
header.hbsfooter.hbslayout.hbsThat works at first, but it quickly becomes repetitive.
Now imagine you move those shared files into a Lambda Layer.
Your layer might contain something like:
/opt/templates/ email/ header.hbs footer.hbs welcome.hbs reset-password.hbs pdf/ summary.hbs/opt/helpers/ formatDate.js currency.js
Then your Lambda function reads the template from /opt/templates/... and compiles it using Handlebars.
import fs from 'fs';import path from 'path';import Handlebars from 'handlebars';const templatePath = path.join('/opt/templates/email/welcome.hbs');const templateSource = fs.readFileSync(templatePath, 'utf8');const template = Handlebars.compile(templateSource);const html = template({ name: 'Nimal', role: 'Frontend Developer'});console.log(html);
Now the function only needs to know where the shared template lives. It does not need its own separate copy.
This is a small change, but in a real project, it can make template handling much more organized.
Even though this pattern is useful, it does come with a few challenges.
One of the most common issues is using the wrong path when loading templates.
In local development, you may read templates from a project folder like ./templates. In Lambda with layers, those files are usually mounted under /opt. If your code is not environment-aware, it may work locally but fail in AWS.
A layer only helps if the .hbs files are actually packaged correctly. If your deployment process forgets to include a template file, the function will still fail at runtime.
This is easy to miss because the deployment itself may succeed. The problem only appears when the function tries to read the file.
Layers are versioned. That is useful, but it also means updating a layer does not automatically update all the functions using it.
One Lambda may still point to an older version of the layer while another is using the newest one. That can create confusing behavior, especially when templates change.
When many functions depend on the same layer, a change in that layer can affect all of them.
For example, updating a partial or helper function may break email rendering, PDF generation, and other flows at the same time if the change is not backward-compatible.
Debugging can become a little harder because the problem might be in:
That does not mean the pattern is bad. It just means it needs a little more discipline.
Even with those issues, using Handlebars with Lambda Layers has strong advantages.
This is the biggest benefit.
If the same templates or helpers are used across multiple functions, a layer lets you keep them in one shared place instead of duplicating them everywhere.
Your Lambda function code stays focused on what it should do. Shared templates and helpers are separated into their own package.
That makes the project easier to understand.
When you need to update a shared template, you do it once in the layer instead of repeating the same edit across several Lambdas.
If multiple Lambdas generate branded emails, reports, or PDFs, using shared templates helps keep the output consistent.
Instead of storing repeated template assets inside every Lambda deployment package, you move them into one reusable layer.
That can make individual functions lighter and cleaner.
This is the part many teams skip at the beginning.
At small scale, Handlebars with Lambda Layers may feel simple. At production level, it needs a bit more planning.
A shared layer is not just a folder of files. It should be versioned, tested, and updated carefully.
If your functions rely on templates inside the layer, then the layer is part of your production contract.
Do not assume every function will automatically pick up the latest layer version. Make sure your deployment process updates the function-layer relationship intentionally.
Otherwise, you may end up with inconsistent behavior across environments.
A small template change can have a big impact if that template is used in multiple places.
This is especially important for:
Testing should include both template rendering and the data that gets injected into those templates.
If a template is missing or broken, your system should fail clearly.
Good logging helps a lot here. If a function cannot load /opt/templates/email/welcome.hbs, the error should be easy to trace.
A shared layer is helpful, but it should stay focused.
If you put too many unrelated things into one layer, it becomes harder to maintain. A good layer should have a clear purpose, such as shared rendering assets or shared utilities.
Handlebars and AWS Lambda Layers can work very well together, especially when you have multiple serverless functions using the same templates, partials, or helpers.
The real value comes from solving a practical problem: TypeScript and JavaScript bundle easily, but .hbs files often need extra handling. Lambda Layers offer a clean way to manage those reusable assets without copying them into every function.
That said, this is not just about convenience. It is also about structure.
Used well, this pattern can give you:
But like many good patterns, it works best when handled carefully. Path management, layer versioning, deployment coordination, and testing all matter more at production level.
So, is using Handlebars with Lambda Layers a good idea?
Yes, especially when multiple functions share the same rendering logic and template files.
Just make sure you treat the layer as an important part of your architecture, not just a place to drop extra files.
If you do that, this approach can make your serverless application much easier to manage as it grows.
LinkedIn: https://www.linkedin.com/in/pathumscj
A version of this article was first published on March 23, 2026 on Medium.
EnlearTrigger AWS Workflows from Incoming Emails Using Amazon SES Ever wanted to trigger a workflow based on an email sent to a specific recipient address? That’s exactly what we’re going to discuss …
EnlearCore AWS Services You Must Know as a Developer AWS looks exciting from a distance. Then you open the console for the first time and see a long list of services, categories, and unfamiliar names. EC2 …
EnlearWhat is AWS Amplify? Building a React app is the easy part. Then the “real app” requirements show up: Users need to sign up and log in You need an API You need a database You need file …