Skip to main content
This guide walks you through installing @lionlang/core, running your first Lion expression, and extending the environment with custom JavaScript values. You will have a working Lion program in under five minutes.
Lion requires two peer dependencies: effect for typed asynchronous evaluation, and typescript with strict mode enabled. Both must be installed in your project before using @lionlang/core.
1

Install @lionlang/core

Add the package and its peer dependencies to your project.
npm
npm install @lionlang/core effect
yarn
yarn add @lionlang/core effect
pnpm
pnpm add @lionlang/core effect
bun
bun add @lionlang/core effect
2

Import run and stdlib

run is the top-level entry point for evaluating Lion expressions. stdlib is the default environment containing all built-in modules.
import { Effect } from "effect";
import { run } from "@lionlang/core/evaluation/evaluate";
import { stdlib } from "@lionlang/core/modules";
The run function accepts any JSON-compatible value as an expression and a plain object as the environment. It returns an Effect that resolves to the evaluation result.
3

Evaluate your first expression

Pass a Lion expression and the standard library environment to run, then execute the Effect with Effect.runPromise.
const result = await Effect.runPromise(
  run(["number/add", 1, 2], stdlib)
);

console.log(result); // => 3
The expression ["number/add", 1, 2] is a plain JSON array. The first element, "number/add", resolves to a function in stdlib. The remaining elements are the arguments. The result is 3.
4

Add a custom environment

Spread stdlib into your own object to add custom bindings. Any string in a Lion expression resolves against the environment — including your own values, objects, and functions.
import { Effect } from "effect";
import { run } from "@lionlang/core/evaluation/evaluate";
import { stdlib } from "@lionlang/core/modules";

const env = {
  ...stdlib,
  price: 100,
  taxRate: 0.08,
  clamp: (min: number, max: number, value: number) =>
    Math.min(max, Math.max(min, value)),
};

// "price" and "taxRate" resolve to 100 and 0.08 from the environment
const total = await Effect.runPromise(
  run(["number/add", "price", ["number/multiply", "price", "taxRate"]], env)
);
console.log(total); // => 108

// "clamp" resolves to your custom JavaScript function
const clamped = await Effect.runPromise(run(["clamp", 0, 100, 150], env));
console.log(clamped); // => 100
Because strings resolve at evaluation time, you can store Lion programs as JSON and supply different environments at runtime — changing behavior without modifying the program.

​
Next steps

Expression model

Learn how arrays, strings, objects, and primitives evaluate in detail.

Special forms

Explore define, lambda, cond, match, begin, and quote.

Standard library

Browse all built-in modules and their available functions.

Custom environment

Learn patterns for injecting JavaScript APIs into the Lion environment.