# Installation

> Install the package, meet the requirements, and put an API key where the runtime can find it.

Section: Getting started · HTML: https://jevascript.org/docs/installation · Markdown: https://jevascript.org/docs/installation.md

## Install the package

```bash
npm i jevascript
pnpm add jevascript
yarn add jevascript
bun add jevascript
```

The package has **zero runtime dependencies**. It uses the platform's `fetch`, `AbortSignal.any` and `AbortSignal.timeout`, which is why it needs a recent Node.

## Requirements

| | Minimum | Notes |
|---|---|---|
| Node.js | 22.6 | `AbortSignal.any` and `--experimental-strip-types` landed here. |
| TypeScript | 5.0 | Types are shipped in the package. `moduleResolution` must be `bundler`, `node16` or `nodenext`. |
| Module system | ESM | The package is ESM only. See below if your project is CommonJS. |

Bun and Deno work with the same code paths; both implement the standard `fetch` and `AbortSignal` APIs the package relies on.

### ESM only

`jevascript` ships as ES modules. In a Node project, either set `"type": "module"` in `package.json` or use `.mts` files. `require("jevascript")` is not supported.

If you must call it from CommonJS, use a dynamic import:

```ts
// legacy.cjs
const { semantic } = await import("jevascript")
```

### Two entry points

| Import | Contains |
|---|---|
| `jevascript` | The runtime: `semantic`, `createSemantic`, the primitives, definitions, collections, providers, errors and every type. |
| `jevascript/testing` | `createMockSemanticProvider`, a provider that answers from a lookup table so tests run without a network or a key. |

## Add the API key

The first provider is Jev, a decision model reached over HTTPS. It needs an API key. Put it in the environment under `JEV_API_KEY` and the runtime configures itself on first use:

```bash
# .env
JEV_API_KEY=apikey_...
```

How the variable reaches your process depends on how you run it:

  **Node 22**

```bash
node --env-file=.env app.ts
```
  
  **dotenv**

```ts
import "dotenv/config"
import { semantic } from "jevascript"
```
  
  **Frameworks**

Next.js, Nuxt, SvelteKit, Remix and Astro load `.env` files themselves. Add `JEV_API_KEY` to `.env.local` or your host's secret store. Never prefix it with `NEXT_PUBLIC_` or `VITE_`; the key must stay on the server.
  

> **Note:** Where the key comes from, and how to set the model or endpoint explicitly, is covered in [Providers](https://jevascript.org/docs/providers). If you would rather not rely on the environment, pass the key directly: `createSemantic({ provider: jev({ apiKey }) })`.

## Verify the install

This runs without a key. The mock provider answers from a table instead of the network, so it proves the import, the types and the batching:

```ts
// check.ts
import { createSemantic } from "jevascript"
import { createMockSemanticProvider } from "jevascript/testing"

const provider = createMockSemanticProvider({ urgent: 0.9 })
const semantic = createSemantic({ provider })

const urgent = await semantic("All card payments are failing.").is("This is urgent.")

console.log(urgent)               // true
console.log(provider.requestCount) // 1
```

```bash
node --experimental-strip-types check.ts
```

If you see `true` and `1`, the package is installed correctly. Continue with the [quick start](https://jevascript.org/docs/quick-start).

## Upgrading

The API may change before 1.0. Pin a minor version in `package.json` and read the [changelog](https://jevascript.org/docs/changelog) before moving between minors. Within a minor, releases are additive.