Skip to content
GenAIScript
Blog

v2.0 - A Node.JS library

The image shows a network of geometric blocks connected by wires, symbolizing a modular 2D server in retro 8-bit style. One block is marked with a "runtime" symbol and another with a "CLI" symbol, each featuring plug-in style ports. Flexible wire connections link a Node.js logo to these blocks. Surrounding the central setup are minimalist icons that represent code, packages, and script files. The design uses five bold corporate colors, maintains flat and iconic visuals, and has a neutral, wordless background.
Matt Podwysocki
Matt Podwysocki
GenAIScript developer
 Peli
Peli
GenAIScript developer
 GenAIScript
GenAIScript
GenAI Blogger
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 and in Visual Studio Code.

A Major Refactor

Section titled “A Major Refactor”

When Matthew Podwysocki (@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, 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”

The new @genaiscript/runtime package provides a standalone GenAIScript 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:

Terminal window
npm i @genaiscript/runtime
 
import { initialize } from "@genaiscript/runtime";


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

The initialization process loads global parsers and inline prompt helpers, 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:

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”

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”

The @genaiscript/api package delivers a lightweight Node.js runner optimized for programmatic execution with minimal runtime dependencies. This package focuses on performance and simplicity, providing just what you need to run GenAIScript in production environments.

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

Plugins

Section titled “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 and how to use them.

Other breaking changes

Section titled “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”

Big thanks to @matthew-podwysocki for investing his time and effort into this project.

Tags: