Both directory options are resolved from process.cwd(), not from the file that registers the module. Starting the app from another directory (pm2, a Docker image with a different WORKDIR) will break them.

Helpers

HandlebarsModule.forRoot({
  templateDirectory: 'templates',
  helpers: [
    { name: 'upper', fn: (value: string) => value.toUpperCase() },
    { name: 'day', fn: (date: Date) => date.toISOString().slice(0, 10) },
  ],
});

{{upper name}} joined on {{day createdAt}}

Partials

Given templates/partials/header.hbs, use it as {{> header}}. The partial receives the current context, so {{name}} inside the partial resolves against the same data you passed to render().

When registration happens

Helpers and partials are read once, at module startup. Editing a partial on disk does nothing until the process restarts. A partialDirectory that does not exist makes the application fail on boot instead of on the first render.

Every service instance gets its own Handlebars environment, so nothing registered here leaks into the global Handlebars object or into other libraries rendering templates in the same process.

Caching

renderFile() reads and compiles each template once, then keeps the compiled form keyed by its absolute path. Compilation is the expensive half of a render and the result is reusable, so subsequent calls skip both the disk read and the compilation.

There is no invalidation. A template edited on disk is only picked up after a restart, the same way partialDirectory already behaves. While developing, turn it off:

HandlebarsModule.forRoot({
  templateDirectory: 'templates',
  cache: process.env.NODE_ENV === 'production',
});

The cache holds one entry per template file, so it is bounded by what is on disk, and it belongs to the service instance rather than being shared process-wide.

render() is never cached. Its input is an arbitrary string, and keying a cache on that would let a caller grow it without limit.

Usage

Inject HandlebarsService and call one of its two methods. Both run synchronously and return a string.

parameters is the context object the template reads from. It defaults to {}.

import { Controller, Get } from '@nestjs/common';
import { HandlebarsService } from '@gboutte/nestjs-hbs';

@Controller()
export class AppController {
  constructor(private readonly hbsService: HandlebarsService) {}

  @Get()
  fromFile(): string {
    return this.hbsService.renderFile('hello.hbs', { name: 'John Doe' });
  }

  @Get('template-string')
  fromString(): string {
    return this.hbsService.render('<h1>Hello {{name}}</h1>', {
      name: 'John Doe',
    });
  }
}

A runnable version of this lives in demo-app/.

Template paths are confined

renderFile resolves its argument inside templateDirectory and rejects anything that lands outside of it, so a template name built from user input cannot be turned into an arbitrary file read:

this.hbsService.renderFile(`${req.query.theme}.hbs`); // '../../../etc/passwd' is refused

The check is lexical. A symlink placed inside templateDirectory and pointing outside of it is still followed.

Errors

Everything thrown by this library extends HandlebarsError, so one catch clause covers it. Nothing carries an HTTP status: rendering also backs emails, PDFs and CLI output, where a 500 means nothing. Applications behind HTTP map these onto the responses they want.

import {
  HandlebarsError,
  HandlebarsInvalidPathError,
} from '@gboutte/nestjs-hbs';
import { BadRequestException, NotFoundException } from '@nestjs/common';

try {
  return this.hbsService.renderFile(name, { name: 'John Doe' });
} catch (err) {
  if (err instanceof HandlebarsInvalidPathError) {
    throw new BadRequestException('Unknown template');
  }
  if (err instanceof HandlebarsError) {
    throw new NotFoundException('Template unavailable');
  }
  throw err;
}

License

MIT