# v2.0 - A Node.JS library

> GenAIScript v2.0 introduces a major architectural refactoring with proper TypeScript packages, unified types, pnpm migration, and improved developer experience.

[Your browser does not support the audio element.](https://microsoft.github.io/genaiscript/llms-full.txt.mp3 "Generated by 🤖 AI with random voice personality. Content interpretation may vary.")

Generated by 🤖 AI

GenAIScript 2.0 represents a significant architectural milestone. We’ve fundamentally restructured the codebase to liberate the runtime from CLI dependency, enabling GenAIScript to run natively in any Node.js application.

**Your existing scripts remain largely compatible**. Most changes happen behind the scenes, though we’ve introduced some breaking changes to the CLI and certain APIs that enhance long-term maintainability.

> The v2.0 release is available in [npm](https://www.npmjs.com/package/genaiscript) and in Visual Studio Code.

## A Major Refactor

[Section titled “A Major Refactor”](#a-major-refactor)

When [Matthew Podwysocki](https://www.linkedin.com/in/podwysocki/) ([@mattpodwysocki](https://github.com/mattpodwysocki)) approached us about contributing to GenAIScript, we initially suggested smaller features to help him get familiar with the codebase. Instead, Matthew saw the bigger picture and proposed **a comprehensive architectural refactoring to create a more modular and maintainable system**.

This suggestion addressed some large technical debt in the project. GenAIScript originated as a research project that evolved organically, accumulating assumptions about its runtime environment. The most significant constraint: scripts could only execute within an augmented Node.js runtime managed by our CLI. This architecture created an artificial barrier—every GenAIScript execution required the CLI as an intermediary.

**Matthew transformed this limitation into an opportunity.** He spearheaded the complex task of [refactoring our entire build system](https://github.com/microsoft/genaiscript/pull/1594), decomposing the monolithic structure into consumable ESM and CommonJS npm packages. This wasn’t just a technical upgrade—it fundamentally changed how developers can integrate GenAIScript into their projects.

### Introducing `@genaiscript/runtime`

[Section titled “Introducing @genaiscript/runtime”](#introducing-genaiscriptruntime)

The new [@genaiscript/runtime](https://www.npmjs.com/package/@genaiscript/runtime) package provides a standalone GenAIScript [runtime](/genaiscript/reference/runtime) that operates independently in any Node.js environment—no CLI wrapper required.

Previously, accessing runtime functionality meant importing a custom export `genaiscript/runtime` from the `genaiscript` package. Now, `@genaiscript/runtime` exists as a dedicated, purpose-built package with a clean API surface.

**Getting started is straightforward:**

* npm

  ```sh
  npm i @genaiscript/runtime
  ```

* pnpm

  ```sh
  pnpm add @genaiscript/runtime
  ```

* yarn

  ```sh
  yarn add @genaiscript/runtime
  ```

```typescript
import { initialize } from "@genaiscript/runtime";


// Initialize before using any global types
await initialize();
```

The initialization process loads global parsers and [inline prompt helpers](/genaiscript/reference/scripts/inline-prompts), preparing the runtime for script execution.

**Important architectural note:** Top-level prompt functions like `$` and `def` remain exclusive to the CLI context, as they depend on CLI-specific initialization. When using the runtime directly, you’ll work with inline prompts instead:

```typescript
import { prompt, runPrompt } from "@genaiscript/runtime";


const { text: recipe } = await prompt`write a recipe`;
const { text: poem } = await runPrompt(
  (ctx) => ctx.$`write a poem for this recipe: ${recipe}`,
);
```

### Unified Development: CLI and Node.js Runtime

[Section titled “Unified Development: CLI and Node.js Runtime”](#unified-development-cli-and-nodejs-runtime)

This architectural evolution unlocks a powerful new capability: you can now write GenAIScript library code that works seamlessly in both CLI and Node.js environments. This unified approach eliminates the friction of maintaining separate implementations for different deployment contexts.

### Streamlined API Access with `@genaiscript/api`

[Section titled “Streamlined API Access with @genaiscript/api”](#streamlined-api-access-with-genaiscriptapi)

The [@genaiscript/api](https://www.npmjs.com/package/@genaiscript/api/) package delivers a lightweight Node.js runner optimized for [programmatic execution](/genaiscript/reference/api/) with minimal runtime dependencies. This package focuses on performance and simplicity, providing just what you need to [run](/genaiscript/reference/api/) GenAIScript in production environments.

```typescript
import { run } from "@genaiscript/api";
```

### Plugins

[Section titled “Plugins”](#plugins)

Some of the large functionalities have been moved out to separate packages (plugins) to reduce the default installation footprint. We dropped 200Mb of dependencies…

* `@genaiscript/plugin-mermaid` - mermaid parse
* `@genaiscript/plugin-ast-grep` - the ast grep parser
* `@genaiscript/plugin-z3` - the Z3 solver

Read more about the [runtime plugins](/genaiscript/reference/runtime/) and how to use them.

### Other breaking changes

[Section titled “Other breaking changes”](#other-breaking-changes)

* the short options of the command line tools have been modified to support upgrading to the latest Commander library.

## Acknowledgments

[Section titled “Acknowledgments”](#acknowledgments)

Big thanks to [@matthew-podwysocki](https://github.com/matthew-podwysocki) for investing his time and effort into this project.