Plugins, Engines & Utilities
Plugins & PluginComponent
Accessible via pod.plugins. Manages built-in and custom plugins and dispatches lifecycle hooks.
Plugins Methods
| Method | Signature | Description |
|---|---|---|
register |
register(PluginClass, config) |
Instantiates and registers a plugin implementing PluginComponent. |
get |
get(name: string) |
Returns the first registered plugin matching class name name (e.g. 'NunjucksPlugin'), or null. |
trigger |
trigger(hookName, ...args): Promise<void> |
Asynchronously invokes <hookName>Hook on every registered plugin. |
triggerSync |
triggerSync(hookName, ...args): void |
Synchronously invokes <hookName>Hook on every registered plugin. |
PluginComponent Lifecycle Hooks
Any plugin class may implement one or more of these optional hook methods:
| Hook Method | Arguments | When Invoked |
|---|---|---|
createYamlTypesHook |
(yamlTypeManager: YamlTypeManager) |
When building pod.yamlSchema. |
createTemplateEngineHook |
(templateEngine: TemplateEngineComponent, extension: string) |
When a template engine is instantiated for an extension. |
updatePathFormatContextHook |
(context: Record<string, any>) |
When interpolating $path / $localization.path strings. |
createServerHook |
(app: express.Express) |
When the dev server creates its Express application. |
beforeBuildHook |
(builder: Builder) |
Immediately before pod.builder.build() starts rendering routes. |
afterRenderHook |
(result: TemplateEngineRenderResult) |
Synchronously after a template engine renders output (allows mutating result.content). |
afterBuildHook |
(result: BuildResult) |
After pod.builder.build() finishes writing files and manifests. |
Built-in Plugins
All five built-in plugins are registered automatically on every Pod and can be retrieved via pod.plugins.get('<Name>'):
NunjucksPlugin & NunjucksBuiltInFilters
const nunjucksPlugin = pod.plugins.get('NunjucksPlugin') as NunjucksPlugin;
nunjucksPlugin.addFilter('uppercase', (value: string) => value.toUpperCase());
nunjucksPlugin.addGlobal('siteYear', new Date().getFullYear());
Built-in Nunjucks filters (registered automatically):
| Filter | Usage | Description |
|---|---|---|
markdown |
{{doc.body | markdown | safe}} |
Converts Markdown to HTML (with GFM heading IDs). |
t |
{{'Hello' | t}} |
Translates a string or TranslationString in the current doc.locale. |
relative |
{{otherDoc | relative}} |
Returns a path relative to the current doc.url.path. |
formatBytes |
{{1024 | formatBytes}} |
Formats a byte count into human-readable units ('1.00 KB'). |
await |
{{asyncFn() | await}} |
Async Nunjucks filter that awaits a Promise in a template. |
YamlPlugin & YamlTypeManager
const yamlPlugin = pod.plugins.get('YamlPlugin') as YamlPlugin;
yamlPlugin.addType('!custom', {
kind: 'scalar',
construct: value => ({custom: value}),
});
Built-in YAML tags: !pod.doc, !pod.docs, !pod.collection, !pod.collections, !pod.staticFile, !pod.string, !pod.yaml, !pod.locale, !pod.locales, !pod.meta, !pod, !IfEnvironment, !IfLocale.
RouterPlugin
const routerPlugin = pod.plugins.get('RouterPlugin') as RouterPlugin;
routerPlugin.addPathFormatFunction('slugify', (value: string) =>
value.toLowerCase().replace(/[^a-z0-9]+/g, '-')
);
BuilderPlugin
const builderPlugin = pod.plugins.get('BuilderPlugin') as BuilderPlugin;
builderPlugin.addBeforeBuildStep(async builder => {
// Run before routes are built.
});
builderPlugin.addAfterBuildStep(async result => {
// Inspect result.metrics, result.manifest, result.diff.
});
ServerPlugin
const serverPlugin = pod.plugins.get('ServerPlugin') as ServerPlugin;
serverPlugin.register(async app => {
app.get('/healthz', (_req, res) => res.send('ok'));
});
TemplateEngineManager
Accessible via pod.engines. Maps file extensions to TemplateEngineComponent implementations.
| Method | Signature | Description |
|---|---|---|
associate |
associate(extension: string, TemplateEngineClass) |
Associates a file extension (e.g. '.tsx') with a template engine class. |
getEngineByExtension |
getEngineByExtension(extension: string) |
Returns (and caches) the engine for extension. Throws InvalidExtensionError or MissingTemplateEngineError. |
getEngineByFilename |
getEngineByFilename(fileName: string) |
Looks up the engine based on fileName's extension. |
Utility Functions & DataType
Exported directly from @amagaki/amagaki:
| Export | Signature | Description |
|---|---|---|
interpolate |
interpolate(pod, templateString, params) |
Evaluates ${...} expressions against params (cached per pod). |
localizeData |
localizeData(data, locale) |
Recursively resolves TranslationString and LocalizableData values inside an object graph for locale. |
splitFrontMatter |
splitFrontMatter(content) |
Splits YAML front matter (---) from body text, returning {frontMatter?, body?}. |
queryObject |
queryObject(query, data) |
Reads nested dot-delimited keys (e.g. 'hero.title') from an object. |
walk |
walk(path, newFiles?, removePrefix?) |
Recursively lists file paths under a directory. |
basename |
basename(path) |
Returns filename without its extension. |
formatBytes |
formatBytes(bytes) |
Formats byte counts into readable strings (Bytes, KB, MB, GB). |
debounce |
debounce(fn, delay, immediate?) |
Debounces a function call within a delay millisecond window. |
DataType |
DataType.isDocument(v), isCollection(v), isStaticFile(v), isObject(v), isArray(v), isString(v), isNumber(v), isBoolean(v), isDate(v), isFunction(v), isNull(v), isUndefined(v), isRegExp(v), isSymbol(v), isInstance(v) |
Type-checking helpers used internally and available to plugins. |