refactor(v2): precompile ETA templates

[slorber]

Motivation

ETA has a caching system but reading the doc, it's not totally clear if we leverage it correctly (+ current code did .trim() on each SSR page: useless work)

I just precompiled the templates lazily in a memoize call to see if it can improve build times.

cc @nebrelbug if you can review and tell me what you think. I'm not sure we leveraged Eta caching anyway (despite providing a template name), as the default cache option is not documented here: https://eta.js.org/docs/api/configuration

Do you think this PR has an impact?

[slorber]

@nebrelbug I found this part a bit confusing. Why do I need to provide some config in the compiled template. Can't it uses the partial config I set during compilation?

[slorber]

also this looks weird to me to expect a full config here, why not partial + you merge to defaults in the lib directly?

[nebrelbug]

Hi @slorber, good question. You need to provide a config to the compiled template function because the config object holds partials, filters, and other utility methods Eta uses while actually rendering the template.

[nebrelbug]

We do accept partial configs in compile and render. Those functions merge passed-in config options with Eta's default configuration.

It's better for performance, though, to not have to merge the config every time we call the compiled function. Plus, in most cases it would be redundant (most users call render() to render a template, which already merges the config before calling the compiled template function and returning the result) 👍

[nebrelbug]

I did realize that in this case, we can just call the compiled function with eta.defaultConfig. The {rmWhitespace: true} option is applied only when the template is compiled, and doesn't affect the template's rendering.

[docusaurus-bot]

Deploy preview for docusaurus-2 ready!

Built with commit bab2dd6

https://deploy-preview-3238--docusaurus-2.netlify.app

[slorber]

It does not seem to improve anything 😓

[nebrelbug]

Hi @slorber, it looks like you're right: I forgot to set the cache option to true, and Eta doesn't have caching enabled by default!

[nebrelbug]

When Eta compiles a template, it returns a function which can be called with data and a valid configuration object. Since the templates won't change, I might suggest doing something like this:

// createRedirectPageContent.ts

// We don't have to generate this every time because the template won't change
let compiledTemplate = eta.compile(redirectPageTemplate.trim())

function renderRedirectPageTemplate(data: object) {
  return compiledTemplate(data, eta.defaultConfig);
}

// We could memoize the renderRedirectPageTemplate function,
// since it will always return the same result when called with the same data

// Since compiled template functions are very fast, though,
// I'm not sure if it would bring a noticeable performance gain.

// docusaurus-theme-search-algolia/src/index.js

let compiledOpenSearchTemplate = eta.compile(openSearchTemplate.trim())

function renderOpenSearchTemplate(data) {
  return compiledOpenSearchTemplate(data, eta.defaultConfig);
}

// docusaurus/src/client/serverEntry.js

let compiledSSRTemplate = eta.compile(ssrTemplate.trim(), {rmWhitespace: true})

function renderSSRTemplate(data) {
  // We can render with eta.defaultConfig, because {rmWhitespace: true} only affects the template
  // during compilation
  return compiledSSRTemplate(data, eta.defaultConfig);
}

[nebrelbug]

Note that we could memoize renderRedirectPageTemplate, renderOpenSearchTemplate, and renderSSRTemplate. This would make the functions automatically return the same result if they were called with the same data.

Since the template functions basically just perform string concatenation, however, I'm not sure this would bring an additional noticeable performance increase.

[slorber]

@nebrelbug

// We don't have to generate this every time because the template won't change
let compiledTemplate = eta.compile(redirectPageTemplate.trim())

function renderRedirectPageTemplate(data: object) {
  return compiledTemplate(data, eta.defaultConfig);
}

this means the template is compiled at plugin initialization time. I don't necessarily want the template to be compiled early in the process, particularly if it's only used in the postBuild step, that's why I use the memoize in code, to compile it lazily, yet cache for further uses.

I don't want to memorize the render() call because it will be very often called with different args, and the memorize cache would grow, consume memory, and mostly produce cache misses.

Does this PR looks good to merge or do you see things to improve?

[nebrelbug]

We can change this to return compiled(data, eta.defaultConfig);

[nebrelbug]

We can remove the name option: it's used only for Eta's built-in caching inside render() and compile(), which we're bypassing to render.

[nebrelbug]

That makes sense. I just suggested a few additional changes, then I think it looks good! 👍

[slorber]

Thanks, just made the last changes and will merge asap