Compilers.md

Compilers

This spec aims to define a set of common interfaces that all compilers/transformers/template languages should aim to follow.

Methods

Each method can have either a synchronous or asynchronous version. Implementations should seek to offer the synchronous version where possible and only offer the asynchronous version where it is necessary. The asynchronous versions always take a callback of the form callback(error, result). Asynchronous APIs should take care never to throw synchronously and to never call the callback multiple times.

Each method takes an options object. It should treat the following properties specially if appropriate:

• options.filename can be used to load relative files.
• options.basedir can be used to load absolute files.
• options.debug can have more helpful debugging info but larger code.

compileSync(src, options) / compileAsync(src, options, cb)

Compile the source, potentially loading any imports relative to options.filename or options.basedir. You are encouraged to make the imports static, so that caching the compiled function can be as efficient as possible. It should return a compiled object with either a renderSync method or a renderAsync method.

compiled.renderSync(options) / compiled.renderAsync(options, cb)

Should render the template and return the resulting string or binary data. This function would typically be called separately for each request even in production applications.

clientSync(src, options) / clientAsync(src, options, cb)

Compile the function and return a client object with a source property. This object may also optionally have properties for runtimeName and runtimeFile which can be used to load shared runtime dependencies.

client.source

This contains the source code for a CommonJS module that exports this template. It should contain only code directly related to this specific template.

client.runtimeName

The name of a variable that will to be in scope inside the CommonJS module represented by client.source

client.runtimeFile

The full file path of a CommonJS module that represents any shared runtime dependencies that templates have once compiled for client use. You should avoid placing shims in this code where possible.

dependantsSync(src, options) / dependantsAsync(src, options, cb)

Return a complete list of the files that will be required in order to render src. This is useful in file watching and automatic re-compilation.