stencil v2

After what feels like ages, we're finally releasing a stable version of stencil! By the time this post has been launched, v2 will be out. Now, you might be asking why v2, there's not even a v1! And you'd be right, there is no v2. However, due to the history of stencil being that it was forked from getoutreach/stencil back in December 2023, it made sense to skip v1. v2 signifies to consumers that there is breaking changes, both migrators and users who've only used this version of stencil, and there's a few!

Breaking Changes

Nobody likes breaking changes and stencil does its best to avoid them, however it was time for a few targeted changes to allow us to reduce some of the friction when using stencil. Let's walk through them.

Module Hook Calls Are Now Variadic

Previously, when calling a module hook you'd need to wrap your arguments in a list. This was an oversight in their original design. Module hooks can have n data inserted into them, so the theory around this is that it'd make it more clear to consumers and implementers. In practice however, this lead to complicated list building that wasn't really necessary. An example of this looks like so:

// Before
{{- stencil.AddToModuleHook "github.com/rgst-io/stencil-golang" "hookName" (list "myData") -}}

// After
{{- stencil.AddToModuleHook "github.com/rgst-io/stencil-golang" "hookName" "myData" -}}

stencil.ApplyTemplate is now stencil.Include

stencil.ApplyTemplate was never a very intuitive name for including the contents of another template (or define). So, we've renamed it to be more clear. While this is not actually a breaking change (ApplyTemplate will continue to work until the next major release), we highly recommend updating calls now as stencil will print a very annoying warning message on each run until you do 😄

configuration: NewManifest and NewDefaultManifest removed

This applies to anyone who was consuming the public configuration Go package. NewManifest and NewDefaultManifest have been deprecated for a long time now, replaced by their Load counterparts. They no longer exist, now.

New Features

Now, lets get onto the new features added in this release.

Module Hooks Now Support JSON Schemas

Previously, a template would need to rely on its own validation of its module hook data. Now, a module hook can have typed data through defining its module hooks in its manifest.yaml. Using the new moduleHooks key, you can embed a schema. An example of this looks like so:

# manifest.yaml
name: github.com/rgst-io/stencil-golang
moduleHooks:
  extraImports:
    schema:
      type: string

It's important to note that the above schema applies to each item inserted into the module hook. Meaning, you do not need to check the entire list (since module hook data is always a list from the consumer's point of view).

What's Next

v2 is an important milestone for stencil! With this, we'll no longer be shipping breaking changes in minor versions. Next up on the roadmap is:

• Testing framework for stencil templates
• Generated documentation for stencil modules from manifest.yaml
• Tighter integration with language specific features from templates (e.g., comments, imports)
• ... and more!

Think stencil could benefit from something not here? Feel free to reach out on the issue tracker!