> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lionlang.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Get started with Lion

> Install @lionlang/core, evaluate your first JSON expression, and add a custom environment to call your own JavaScript functions from Lion.

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.

<Note>
  Lion requires two peer dependencies: [`effect`](https://effect.website) for typed asynchronous evaluation, and `typescript` with strict mode enabled. Both must be installed in your project before using `@lionlang/core`.
</Note>

<Steps>
  <Step title="Install @lionlang/core">
    Add the package and its peer dependencies to your project.

    ```bash npm theme={null}
    npm install @lionlang/core effect
    ```

    ```bash yarn theme={null}
    yarn add @lionlang/core effect
    ```

    ```bash pnpm theme={null}
    pnpm add @lionlang/core effect
    ```

    ```bash bun theme={null}
    bun add @lionlang/core effect
    ```
  </Step>

  <Step title="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.

    ```typescript theme={null}
    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.
  </Step>

  <Step title="Evaluate your first expression">
    Pass a Lion expression and the standard library environment to `run`, then execute the `Effect` with `Effect.runPromise`.

    ```typescript theme={null}
    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`.
  </Step>

  <Step title="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.

    ```typescript theme={null}
    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.
  </Step>
</Steps>

## Next steps

<CardGroup cols={2}>
  <Card title="Expression model" icon="sitemap" href="/concepts/expression-model">
    Learn how arrays, strings, objects, and primitives evaluate in detail.
  </Card>

  <Card title="Special forms" icon="code-branch" href="/concepts/special-forms">
    Explore `define`, `lambda`, `cond`, `match`, `begin`, and `quote`.
  </Card>

  <Card title="Standard library" icon="layer-group" href="/stdlib/overview">
    Browse all built-in modules and their available functions.
  </Card>

  <Card title="Custom environment" icon="wrench" href="/guides/custom-environment">
    Learn patterns for injecting JavaScript APIs into the Lion environment.
  </Card>
</CardGroup>