npm package: @jymfony/kumis
Description: A powerful asynchronous templating engine (jinja2 inspired)
Author: Alessandro Chitolina
Latest version: 0.1.0

# Kumis

[![CI](https://github.com/jymfony/kumis/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/jymfony/kumis/actions/workflows/ci.yml)
[![Coverage](https://codecov.io/gh/jymfony/kumis/branch/master/graph/badge.svg)](https://codecov.io/gh/jymfony/kumis)
[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Fjymfony%2Fkumis.svg?type=shield)](https://app.fossa.io/projects/git%2Bgithub.com%2Fjymfony%2Fkumis?ref=badge_shield)

Kumis is a full-featured, fully asynchronous templating engine for modern JavaScript runtimes. Inspired by [Jinja2](https://jinja.palletsprojects.com/) and originally built on top of [Nunjucks](https://mozilla.github.io/nunjucks/), the engine brings familiar syntax together with first-class async rendering, a robust extension system, and integration with the [Jymfony](https://jymfony.com/) ecosystem.

## Features

- **Asynchronous by design** &mdash; render templates and stream output without blocking the event loop.
- **Jinja-compatible syntax** &mdash; use template inheritance, macros, filters, tests, and control structures you already know.
- **Extensible runtime** &mdash; register custom filters, tests, globals, and extensions to adapt Kumis to your application.
- **Filesystem and cached loaders** &mdash; ship templates from disk, memory, or bespoke loaders tailored to your needs.
- **Jymfony integration** &mdash; 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:

```bash
npm install @jymfony/kumis
```

## Quick start

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

```js
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` &mdash; execute the full test suite.
- `npm run test:instrument` &mdash; run the tests with [nyc](https://github.com/istanbuljs/nyc) to produce coverage reports in `coverage/`.

Coverage reports can be uploaded to services such as [Codecov](https://about.codecov.io/) or [Coveralls](https://coveralls.io/). 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](https://github.com/jymfony/kumis/releases))

## Contributing

Contributions are always welcome! Please review the [contribution guidelines](CONTRIBUTING.md) 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](https://github.com/jymfony/kumis/graphs/contributors)

## License

[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Fjymfony%2Fkumis.svg?type=large)](https://app.fossa.io/projects/git%2Bgithub.com%2Fjymfony%2Fkumis?ref=badge_large)