js-genai: a browser-and-node SDK with two major versions queued up

One npm package with three entry points

Installation is a single command, and the published name is scoped.

npm install @google/genai

What follows that command is more interesting than it first appears, because the `package.json` declares several conditional export paths rather than one main entry. There is a root export, a `./web` subpath, a `./node` subpath, a `./tokenizer` subpath and a `./tokenizer/node` subpath, plus a `./vertex_internal` path that is not obviously meant for public use.

Each of those resolves differently depending on environment. The root export has a browser condition and a node condition, and the browser condition points at a web bundle while the node condition points at an ES module with a CommonJS sibling. There is also a `type` field set to `module`, so the package is ESM first with a CommonJS fallback rather than the other way round.

The practical consequence is that the same import specifier works in a bundler and in Node without conditional import logic in your own code, and that token counting is available as a separate import so it does not pull into a browser bundle. The `browser`, `main`, `module` and `typings` fields all point at the `dist/` directory, with typings resolving to a single generated declaration file.

This is the part of the layout most likely to save you an afternoon. There are near-certainly projects that reached for a deep import path to get at a tokenizer or a Node-specific client, and the export map exists specifically so you do not have to.

The quickstart is a dozen lines and one environment variable

The entry example reads an API key from the environment, constructs the client and awaits a single call.

import {GoogleGenAI} from '@google/genai';
const GEMINI_API_KEY = process.env.GEMINI_API_KEY;

const ai = new GoogleGenAI({apiKey: GEMINI_API_KEY});

async function main() {
  const response = await ai.models.generateContent({
    model: 'gemini-flash-latest',
    contents: 'Why is the sky blue?',
  });
  console.log(response.text);
}

main();

Two details carry weight. The model is given as the floating `gemini-flash-latest` alias rather than a pinned version, which means your application tracks Google's model rollouts without a code change. That is a deliberate choice with a real consequence: behaviour can shift under a deployment that did not change.

The second is that the call takes a single options object rather than positional arguments, which is a change from the Go SDK's shape where the model name is a bare string argument and the config is a trailing nil. The object form is friendlier in a language with named properties.

The response object exposes `.text` directly rather than making you walk a content array, which saves the most tedious part of using a generated client.

The SDK targets Gemini 2.0 and later features, and the prerequisite stated up front is Node.js version 20 or later. That number is about to change, as covered below.

The warning block is the most useful paragraph in the README

A warning box sits near the top and it is dense, so it is worth taking apart. Three separate changes are queued for the next major version, and they are announced together.

The first is automatic function calling. The behaviour is changing such that users will not be able to invoke AFC from direct calls to `Models.generateContent` or its stream variants. Instead, AFC should be invoked from the `Chats` modules. This is the most consequential item because it changes where your code lives rather than what a field is called.

The second is the runtime floor. Starting from SDK version 3.0.0, Node.js version 22 or later is required. Today the prerequisite is 20, so this is a jump within the supported range rather than a leap to something exotic.

The third is a rename table, listing three things being removed and what to use instead: the `generation_config` field on `LiveConnectConfig`, the `prompt`, `text` and `image` arguments in `Models.generate_videos` and its async variants, and the `GenerationConfigThinkingConfig` type. The replacements given are setting fields on `LiveConnectConfig` directly, the `source` argument, and `ThinkingConfig` respectively.

The instruction that closes the block is the operative one: to avoid unexpected updates, pin the SDK version to below 3.0.0.

The video rename is the same change the Go SDK warns about, which is a useful cross-check. If you are evaluating the JavaScript and Go SDKs together, that particular migration is not language specific and you will hit it in both.

Choosing a backend, and the security note that comes with it

The SDK covers the Gemini Developer API and the Gemini Enterprise Agent Platform, and initialization is the only place the choice gets made. An API key is the server-side Developer API route.

import { GoogleGenAI } from '@google/genai';
const ai = new GoogleGenAI({apiKey: 'GEMINI_API_KEY'});

The Enterprise route takes an enterprise flag with a project and a location instead of a key.

import { GoogleGenAI } from '@google/genai';

const ai = new GoogleGenAI({
    enterprise: true,
    project: 'your_project',
    location: 'your_location',
});

For Node environments the constructor can take no arguments at all, with configuration coming from environment variables. The Developer API needs one.

export GOOGLE_API_KEY='your-api-key'

The Enterprise route needs three, including a boolean switch rather than inference from the others.

export GOOGLE_GENAI_USE_ENTERPRISE=true
export GOOGLE_CLOUD_PROJECT='your-project-id'
export GOOGLE_CLOUD_LOCATION='us-central1'

The security caution is repeated twice and it is the one thing here that is not optional advice. Avoid exposing API keys in client-side code, and use server-side implementations in production. The browser initialization example is given with the caution attached, and the code is identical to the server-side version, which is exactly why the warning is there. If you ship that snippet to a browser you have published your key.

For local development against the Enterprise backend, the prerequisites section routes you through the gcloud CLI, and the specific command is short.

gcloud auth application-default login

Beta endpoints by default, and how to leave them

There is a default that will surprise anyone who has used other Google client libraries, and it is stated plainly in the API Selection section. By default the SDK uses the beta API endpoints provided by Google, in order to support preview features. The stable endpoints are selected by setting the API version to `v1`.

The setting is `apiVersion` on the client constructor, and it applies to either backend.

const ai = new GoogleGenAI({
    enterprise: true,
    project: 'your_project',
    location: 'your_location',
    apiVersion: 'v1'
});

The same field selects `v1alpha` for the Developer API.

const ai = new GoogleGenAI({
    apiKey: 'GEMINI_API_KEY',
    apiVersion: 'v1alpha'
});

So there are three usable positions: beta by default, `v1` for stable, and `v1alpha` for the earliest surface. That is an unusual default and it is worth being deliberate about it. The upside is access to preview features, which is presumably why the project chose it. The cost is that your application depends on endpoints Google does not consider stable, so a beta-only field appearing in your code is a portability risk when you eventually pin to `v1`.

All API features are accessed through an instance of the `GoogleGenAI` class, and the README describes submodules that bundle related methods. The first of them is `ai.models`, and the pattern continues across the surface.

What the tree says about how this package is built

The repository is a TypeScript source tree with a build and a release pipeline that is easier to infer than to find documented. `codegen_instructions.md` at the root is the clearest signal, and the README does something unusual with it rather than just mentioning the file. It recommends copying the contents into your development environment so a code-generating model produces current SDK usage instead of outdated examples. The stated reason is that generative models are often unaware of recent API and SDK updates and may suggest legacy code. That is a candid admission that SDK documentation drift is a real problem, and a reasonable answer to it.

The rest of the tree supports a picture of heavily automated release. There are `release-please-config.json`, `.release-please-manifest.json` and a `releases.txt`, the same trio the Go SDK carries. `api-extractor.json` is joined by four variants keyed to different outputs: a node one, a tokenizer-node one, a vertex_internal one and a web one, with an `api-report/` directory holding the checked-in public surface. That means breaking changes in the API surface are detected in review rather than discovered by users, which is the main thing a generated SDK can do for you.

A `rollup.config.mjs` builds the bundles, `typedoc.json` drives the reference documentation published at googleapis.github.io, `eslint.config.mjs` and `.prettierrc` handle style, and a `patches/` directory suggests dependency patching is part of the build. Samples live in two directories, `google_samples/` and `sdk-samples/`, alongside `test/` and `tests/`.

The recent release history is a good indicator of pace. v2.21.0 on 2026-09-02, v2.22.0 on 2026-09-10 and v2.23.0 on 2026-09-16, roughly weekly, with entries that add a new model, add an environment-copying feature, and add credential APIs and interaction step types. The repository was pushed to on 2026-09-20 and is not archived, with 1,679 stars. The 173 open issues are worth noting against that cadence.

Editorial conclusion

js-genai is a well organised SDK whose near term risk is concentrated in one place, the version 3 boundary the README keeps warning about. Automatic function calling is changing shape, two fields and an argument list are being renamed, and Node 22 becomes a requirement, all at once. Everything else about the package is in good order: separate entry points for browser and node, an API version switch so you can leave beta endpoints, and environment variable configuration that keeps keys out of source. Read the warning table before you adopt it rather than after, decide whether your calls use automatic function calling through Chats rather than direct model calls, and pin below 3.0.0 until you have looked at that migration yourself.

Frequently asked questions

Official sources

1. googleapis/js-genai on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases