Kumis

Kumis is a full-featured, fully asynchronous templating engine for modern JavaScript runtimes. Inspired by Jinja2 and originally built on top of Nunjucks, the engine brings familiar syntax together with first-class async rendering, a robust extension system, and integration with the Jymfony ecosystem.

Features

• Asynchronous by design — render templates and stream output without blocking the event loop.
• Jinja-compatible syntax — use template inheritance, macros, filters, tests, and control structures you already know.
• Extensible runtime — register custom filters, tests, globals, and extensions to adapt Kumis to your application.
• Filesystem and cached loaders — ship templates from disk, memory, or bespoke loaders tailored to your needs.
• Jymfony integration — includes a framework bundle, cache warmers, and security/var-dumper extensions for seamless usage inside Jymfony apps.

Installation

Kumis targets Node.js 18 and newer. Add it to your project with npm:

npm install @jymfony/kumis

Quick start

Render a template string or load templates from disk using the built-in filesystem loader:

import { Environment, Loader, Template } from '@jymfony/kumis';

// Configure the loader to point to your template directory.
const loader = new Loader('/absolute/path/to/templates');
const env = Environment.create(loader);

// Render from a template string.
const greeting = new Template('Hello {{ name }}!', env);
console.log(await greeting.render({ name: 'Kumis' }));

// Or render a file located inside the loader's directory.
console.log(await env.render('emails/welcome.kumis', { user: 'Alice' }));

When running inside a Jymfony application you can also rely on the provided bundle and services defined under src/Bundle to register the engine automatically.

Scripts

• npm run test — execute the full test suite.
• npm run test:instrument — run the tests with nyc to produce coverage reports in coverage/.

Coverage reports can be uploaded to services such as Codecov or Coveralls. The badge above references Codecov; configure your CI workflow to publish the coverage/lcov.info output generated by npm run test:instrument.

Release automation

Publishing a new version is handled by the "Release" GitHub Actions workflow. Push a tag such as v1.2.3 to GitHub and the job will:

1. Update package.json and package-lock.json with the tag's semantic version.
2. Install dependencies and generate release notes while creating a GitHub Release for the tag.
3. Publish the package to npm with npm publish --access public.

The workflow authenticates with npm using the NPM_TOKEN secret, which must have the publish scope for the @jymfony organization.

(View the CHANGELOG)

Contributing

Contributions are always welcome! Please review the contribution guidelines before submitting an issue or pull request. Feel free to open discussions about new filters, loaders, or bundle integrations that could benefit the community.

Contributors

License