Getting started

Installation

Installing eryn is pretty straightforward.

npm i eryn --save

If a prebuild is available for your platform, you're good to go. If not, see below Compiling the package.

Prebuilds

OS	Arch	Compiler	Node
Windows 10.0.18363 (SDK 10.0.19041.0)	ia32	MSVC 19.29.30137.0	13.0.0
Windows 10.0.18363 (SDK 10.0.19041.0)	x64	MSVC 19.29.30137.0	13.0.0
Debian 10.4 (Linux 4.19.0-9-amd64)	ia32	GCC 8.3.0 (Debian 8.3.0-6)	14.0.0
Debian 10.4 (Linux 4.19.0-9-amd64)	x64	GCC 8.3.0 (Debian 8.3.0-6)	14.0.0

Compiling the package

If a prebuild isn't available for your platform, the package will need to be compiled. This is automatically done during the installation.

You'll need a C/C++ compiler toolchain for your platform, as well as CMake (3.0 or newer). If either of those is missing, you'll see an error message.

If you plan on using Heroku, and there isn't a prebuild available that works, read this.

Here are the requirements for each platform:

Platform	Compiler	Build Tools
Windows	Visual C++ Build Tools or Visual Studio Community	CMake (v3.0 or higher)
Unix/POSIX	GCC or Clang	CMake (v3.0 or higher) + Ninja or Make

If you want to manually compile the package, run:

npm run rebuild

You can also directly run cmake-js:

npx cmake-js compile

There's also the option to globally install cmake-js:

npm i -g cmake-js

cmake-js compile

If you want to compile for Node.js 10+, use cmake-js v6.0.0 or newer.

Otherwise, use cmake-js v5.

If eryn errors out during the installation, you can do npm i eryn --ignore-scripts and try to manually compile it by running npm i in the node_modules/eryn folder. If you don't pass that flag, the module folder may be deleted on failure and you won't be able to do the installation manually.

Quick examples

Here's an example that shows a glimpse of what eryn can do.

Note: if you don't like the syntax, see below Changing the syntax.

test.js

var path = require("path");
var eryn = require("eryn")();

// Pass the absolute path to the file. Relative paths might not be safe.
var data = eryn.render(path.join(__dirname, "test.eryn"), {
    firstName: "Tyler",
    lastName: "Bounty",
    greeting: "Hey there",
    numbers: [10, 20, 30, 40]
});

test.eryn

Welcome, [|context.firstName|] [|context.lastName|]!

[|? context.greeting.length > 5 |]
The greeting has more than 5 characters!
[|end|]

This is a basic loop:
[|@ num : context.numbers|]
Current number: [|num|]
[|end|]

There is also support for components!
[|% comp.eryn : {message: "Hello"} |]
This is some content for the component!
It can use the parent context: [|context.greeting|]
[|end|]

And self-closing components too!
[|% comp2.eryn : {test: "world"} /|]

comp.eryn

This is a component!

It has context which is automatically stringified: [|context|]
...and works as usual: [|context.message|]

And also some content:
[|content|]

comp2.eryn

Hello, [|context.test|]!
This is a self closing component with no content!

The render function will return a Buffer, containing:

Welcome, Tyler Bounty!


The greeting has more than 5 characters!


This is a basic loop:

Current number: 10

Current number: 20

Current number: 30

Current number: 40


There's also support for components!
This is a component!

It has context which is automatically stringified: {"message":"Hello"}
...and works as usual: Hello

And also some content:

This is some content for the component!
It can use the parent context: Hey there


And self-closing components too!
Hello, world!
This is a self closing component with no content!

You can use this buffer however you want (e.g. write it to a file, use it as-is, etc).

Changing the syntax

If you don't like the default syntax, you can change it by calling the setOptions function before rendering the file. Here's an example:

eryn.setOptions({
    templateStart: "{{",
    templateEnd: "}}",

    conditionalStart: "if ",

    loopStart: "for ",
    loopSeparator: " of ",
    
    componentStart: "component ",
    componentSeparator: " with ",
    componentSelf: " self"
});

eryn.render(...);

Note: you can call the setOptions function as many times as you want. Changes will take effect immediately.

The files can now be written using this syntax. Here's how the first file would look:

test.eryn

Welcome, {{context.firstName}} {{context.lastName}}!

{{if context.greeting.length > 5 }}
The greeting has more than 5 characters!
{{end}}

This is a basic loop:
{{for num of context.numbers}}
Current number: {{num}}
{{end}}

There is also support for components!
{{component comp.eryn with {message: "Hello"} }}
This is some content for the component!
It can use the parent context: {{context.greeting}}
{{end}}

And self-closing components too!
{{component comp2.eryn with {test: "world"} self}}

This will give the exact same result.

Note: you have to change the syntax in all files.

Also: change the syntax wisely. Otherwise, you might run into some problems (see here).