feat(google): consolidate Google packages into unified @langchain/google package

[christian-bromann]

This PR consolidates the multiple Google-related packages into a single, unified @langchain/google package that provides automatic environment detection and simplified usage for both Node.js and web environments.

📦 Packages Consolidated

• @langchain/google-gauth
• @langchain/google-vertexai
• @langchain/google-vertexai-web
• @langchain/google-webauth

🎯 Key Benefits

1. Simplified Developer Experience: Users no longer need to choose between different Google packages - one package works everywhere
2. Automatic Environment Detection: The package automatically uses the correct authentication method based on the runtime environment (Node.js vs web)
3. Reduced Bundle Size: Eliminates code duplication across packages while maintaining tree-shaking capabilities
4. 100% Backward Compatible: All existing imports continue to work unchanged
5. Unified Documentation & Examples: Single source of truth for all Google integrations

🏗️ Technical Implementation

• Environment-Aware Architecture: Generic classes with environment type parameters ("node" | "web")
• Dual Entry Points: Default export for Node.js, /web export for browsers
• Runtime Authentication Selection: Automatically chooses between google-auth-library (Node.js) and web-auth-library (web)
• Delegation Pattern: Existing packages now simply re-export from the consolidated package

📋 Usage Examples

// Node.js - automatic environment detection
import { ChatGoogle, ChatVertexAI } from "@langchain/google";

// Web/Browser - explicit web import
import { ChatGoogle, ChatVertexAI } from "@langchain/google/web";

// Both work identically!
const chat = new ChatGoogle({ model: "gemini-1.5-pro" });

From a user's perspective, the authentication detection is completely transparent. Users simply import from different entry points and the package automatically handles the environment-specific authentication behind the scenes. The type system is configured to ask for the right type in authOptions.

📋 Node.js Example

// 🟢 Node.js Usage - Default import
import { ChatGoogle, ChatVertexAI } from "@langchain/google";

// The package automatically uses google-auth-library under the hood
const chat = new ChatGoogle({
  model: "gemini-1.5-pro",
  // 🎯 Authentication happens automatically in this order:
  // 1. API Key (if provided)
  apiKey: "your-api-key", 
  
  // 2. Or service account credentials
  // authOptions: { 
  //   credentials: "./path/to/service-account.json" 
  // },
  
  // 3. Or falls back to environment variables:
  //    - GOOGLE_API_KEY
  //    - GOOGLE_APPLICATION_CREDENTIALS (service account file)
  //    - Default credentials (if running on GCP or gcloud auth)
});

const vertexChat = new ChatVertexAI({
  model: "gemini-1.5-pro",
  location: "us-central1",
  // 🔄 Same authentication options as above
  // No need to worry about Node.js vs web - it just works!
});

// Usage is identical regardless of auth method
const response = await chat.invoke("Hello, world!");
console.log(response.content);

🌐 Web/Browser Example

// 🔵 Web Usage - Explicit /web import
import { ChatGoogle, ChatVertexAI } from "@langchain/google/web";

// The package automatically uses web-auth-library under the hood
const chat = new ChatGoogle({
  model: "gemini-1.5-pro",
  // 🎯 Authentication for web environments:
  
  // Option 1: API Key (simplest for web)
  apiKey: "your-api-key",
  
  // Option 2: Service account credentials (for server-side web apps)
  // authOptions: {
  //   credentials: {
  //     type: "service_account",
  //     project_id: "your-project-id",
  //     private_key_id: "key-id",
  //     private_key: "-----BEGIN PRIVATE KEY-----\n...",
  //     client_email: "[email protected]",
  //     // ... other service account fields
  //   }
  // },
  
  // Option 3: Environment variables (webpack/vite will inject these)
  // GOOGLE_API_KEY or GOOGLE_WEB_CREDENTIALS
});

const vertexChat = new ChatVertexAI({
  model: "gemini-1.5-pro", 
  location: "us-central1",
  // 🔄 Same authentication options work here too
});

// Usage is identical to Node.js!
const response = await chat.invoke("Hello from the browser!");
console.log(response.content);

🔄 Migration Path

No migration required! All existing code continues to work:

// These still work exactly as before
import { ChatGoogle } from "@langchain/google-gauth";
import { ChatVertexAI } from "@langchain/google-vertexai"; 
import { ChatGoogle } from "@langchain/google-webauth";

🧪 Testing

• All existing tests have been consolidated and continue to pass
• Environment-specific tests ensure proper authentication flow in both Node.js and web contexts
• Integration tests verify backward compatibility
• type tests have been added to ensure that node/web imports have the right types

This change significantly improves the developer experience for Google integrations while maintaining full backward compatibility and reducing maintenance overhead.

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
langchainjs-docs	✅ Ready (Inspect)	Visit Preview		Jun 19, 2025 11:37pm

1 Skipped Deployment

Name	Status	Preview	Comments	Updated (UTC)
langchainjs-api-refs	⬜️ Ignored (Inspect)			Jun 19, 2025 11:37pm

[christian-bromann]

@hntrl let me know what you think. I am not sure if this diverges from the python package too much. If you are ok with the direction I am happy to finish the PR and update remaining docs to use the consolidated package.

[hntrl]

My primary concern with this is we're making a lot of assumptions about how this dependency gets bundled. These packages are fractured in the way they are because the underlying dependencies we use (google-auth-library and web-auth-library) are unfortunately written in a way that doesn't make them transferable between environments. I liked the way that you approached the passing of the dependency based on the entrypoint, but I don't know if we can say with 100% certainty that downstream users of the package have a picture-perfect bundling/tree-shaking setup that won't try to include the web specific internal dep for a node build target, for example.

These packages are fractured in the way they are for two reasons:

• We want to make a distinction between AI studio and Vertex AI
• We want to make use of the web & node specific deps provided by google

I know there were some developments within one of the google packages specifically that might give us a path to use them interchangeably between node & web, but that requires further investigation.

Also doing a export * from "@langchain/google"; for backwards compat reasons seems especially heavy handed considering our current build pipeline.

cc @afirstenberg

[afirstenberg]

Let me start by saying that I am fully in support of the desire behind this, and bravo @christian-bromann for trying to tackle it (and even getting some of the most recent updates incorporated).

Two thoughts replying to @hntrl:

We want to make a distinction between AI studio and Vertex AI

This is a historic split, dating from Google's desire to have two packages. I'm not sure this is relevant anymore. Google's official package (which I do not suggest we switch to) now works for both platforms. I don't know if there are reasons LangChain wishes to keep this distinction (and, if so, then a compatibility layer should be provided anyway, which it is).

We want to make use of the web & node specific deps provided by google

To be clear, Google only provides the "google-auth-library". The "web-auth-library" is a 3p library that has issues (see #8132). I think we'd love to simplify this - but we also need to support non-node platforms as well as Google's Application Default Credentials. (@jacoblee93 might remember the exact platforms that we need to make sure this runs on. While we call it "web", it included other platforms where the credentials were available in ways besides a file system.)

I need to read the entire PR in detail, but some first thoughts:

• As I said - I love the desire to simplify and improve the developer experience. I am completely behind this goal.
• I share @hntrl's concern that the "/web" entry point approach may not be clear.
  • (That said - we know the current multi-package approach isn't clear.)
• I remember that when we first split things up, the desire was to make sure we supported non-node platforms in a way that tree-shaking was well supported. I cannot judge if this will meet those needs, but I appreciate that this was maintained as a listed goal. Again, @jacoblee93 may remember more/better.
• While we are at it, we should also consider and evaluate if the @langchain/google-genai package can be consolidated into this as well, thus completely eliminating confusion.

[christian-bromann]

@hntrl @afirstenberg thanks for the feedback!

I know there were some developments within one of the google packages specifically that might give us a path to use them interchangeably between node & web, but that requires further investigation.

I couldn't find any evidence that would state we could use google-auth-library in the browser as well.

but I don't know if we can say with 100% certainty that downstream users of the package have a picture-perfect bundling/tree-shaking setup that won't try to include the web specific internal dep for a node build target, for example.

What are types of downstream packages? Other Node.js libraries that bundle @langchain/google?

I certainly agree with the fact that we have to ensure @langchain/google/web can be bundled e.g. within a browser environment and run without errors. For that I've added an e2e test scenario within libs/langchain-google/e2e. It is a basic Vite React app that consumes @langchain/google/web and implements a basic ChatGPT interface to interact with:

I am using WebdriverIO to open a browser headlessly and run a prompt from e2e, validating that the LLM actually returns a result and no JavaScript errors were logged in the console. I think there is value in having a set of these real browser tests within the codebase. This is a start.

• I share @hntrl's concern that the "/web" entry point approach may not be clear.

For more clarity we could check the environment and log a message or throw an error, e.g.:

// throw or log error if web package is used in Node.js environment in `@langchain/google/web`
if ('process' in globalThis) { ... }
// throw or log error if Node.js package is used in web environment in `@langchain/google`
if ('window' in globalThis) { ... }

• I remember that when we first split things up, the desire was to make sure we supported non-node platforms in a way that tree-shaking was well supported. I cannot judge if this will meet those needs, but I appreciate that this was maintained as a listed goal.

Adding e2e tests validates this for us. Making the following change:

diff --git a/libs/langchain-google/e2e/src/App.tsx b/libs/langchain-google/e2e/src/App.tsx
index c8e0196ec..9dc3739a0 100644
--- a/libs/langchain-google/e2e/src/App.tsx
+++ b/libs/langchain-google/e2e/src/App.tsx
@@ -1,5 +1,5 @@
 import { useState, useRef } from "react";
-import { ChatGoogle } from "@langchain/google/web";
+import { ChatGoogle } from "@langchain/google";
 import "./App.css";

Will throw an error with Vite not being able to transpile the package for the browser.

• While we are at it, we should also consider and evaluate if the @langchain/google-genai package can be consolidated into this as well, thus completely eliminating confusion.

I am happy to include this within this PR, or raise a separate one. It would be good if we can clearly lay out the differences between ChatGoogle, ChatVertexAI and ChatGoogleGenerativeAI and when to use what.

[hntrl]

@afirstenberg

This is a historic split, dating from Google's desire to have two packages. I'm not sure this is relevant anymore.

If we think it's high time to revisit it (especially with the advent of -genai), then yeah I'm all for it! I'm mostly basing my assumptions on surface-level intuition, but I trust your judgement more than mine in this matter honestly.

...the exact platforms that we need to make sure this runs on.

If I had to guess, it's all the platforms tested in the environment tests

Google's official package (which I do not suggest we switch to) now works for both platforms.

I know we've talked about this in private, but (so we can bring it to the public record) is your chief concern that google might switch up on us again with a new package they release? Are there any endemic blockers that the move to -genai untenable for us?

--
@christian-bromann

What are types of downstream packages? Other Node.js libraries that bundle @langchain/google?

Not just other libraries, but anyone that has our google packages in their dependencies (users and libraries alike!). Probably the easiest way this setup would raise errors is if someone has "skipLibCheck": false in their tsconfig and was missing dom and/or node types. I'm also not as confident that this works on cloudflare to boot either.

I couldn't find any evidence that would state we could use google-auth-library in the browser as well.

I was referring to support of both environments in -genai, not the auth packages. Allen admittedly has a lot more context than I do on this so I could very well be hallucinating.

Adding e2e tests validates this for us. Making the following change:

Love this! This is probably a good thing to have in every package, but that's probably more trouble than its worth right now. (currently we have very surface level environment tests)

We're still testing a picture-perfect bundler setup here technically. I have no doubt that this works under lab conditions, but my gut tells me this won't track across a number of existing setups without difficulty (something I'd like to avoid if at all possible).

--
Some additional loose thoughts that I came up with:

• My vote is that we deprecate the old packages in favor of "@langchain/google" instead of re-exporting it from the old packages

  • The one thing that I want to protect against is a difficult upgrade path. What the exports tell me by itself is that we don't want to support all these package splits anymore, so instead of "supporting them by proxy" I'd rather just deprecate them and give people an upgrade path to @langchain/google. Reason being is if we went with this approach for backwards-compat, I think it's important that these packages get a minor bump since again we're violating our initial assumptions. Which means we're telling people to either (1) upgrade to ^0.3.0 or (2) migrating to @langchain/google which just seems unnecessarily confusing.

  • I'm not a fan of following in google's footsteps when it comes to deprecating whole packages for new ones (-generative-ai -> -genai), but perhaps the key distinction here is that we're collapsing many packages into one in the spirit of DX which is less problematic IMO.

• This might be a hot take, but is there a reason that we have to inundate ourselves with interfacing with the auth deps? Is the reason we're going with gauth because it's first party and has enough 'black-box DX' that we're forced to use their client? Could we have a web and node safe fetch client that acts as default, then if someone wants to use gauth they can provide the fetch client in the constructor params? I.e.

import { GoogleAuth } from "google-auth-library";
import { ChatGoogleGenerativeAI } from "@langchain/google";

const auth = new GoogleAuth(...);
const model = new ChatGoogleGenerativeAI({
  fetch: auth.fetch,
  ...
});

To me that gets rid of the deps that don't work across environments entirely since it's escaping into userland. The underlying assumption is that -genai doesn't try to use google-auth-library as standard

[afirstenberg]

@christian-bromann says:

I couldn't find any evidence that would state we could use google-auth-library in the browser

That is... a non-advised practice since it would expose credentials in the browser. (Not that people seem to care about this, somehow.)

But in this particular case I think @hntrl was talking about the @google-genai library. Which, it should be clear, is not the library we use for @langchain/google-genai.

For more clarity we could check the environment and log a message or throw an error

I wouldn't advise this since I don't think the environments are as clear-cut as this.

For people using an API Key currently, the current packages "do the right thing" and don't actually use either of the auth libraries. I wouldn't want to force people to use the /web version because they're using an API Key. (Although yes... we could check if they are and bypass these warnings...)

It would be good if we can clearly lay out the differences between ChatGoogle, ChatVertexAI and ChatGoogleGenerativeAI and when to use what.

Two references for this:

• My comments on this issue
• My blog post on using these packages.

But I think, going forward, the objective should be to just have one package, leaving the others (at least for a bit) for backwards compatibility.

Which leads me to @hntrl saying:

I'm also not as confident that this works on cloudflare to boot either.

This might be the platform that I had in mind that was "a server-like environment that was not using node, so had to use the web packages". I haven't used it and don't know details - I was mostly going by vague memories of what Jacob said a year or two ago.

Are there any endemic blockers that the move to -genai untenable for us?

The biggest is that it only supports Vertex AI through google-auth-library.

A secondary issue is that it only supports the "Gemini API", which does include support for Gemma on AI Studio. It does not, for example, support Anthropic on Vertex AI (which we do support) or other models on Vertex AI (which... is on my todo list...). And supporting all those ends up tied to the auth issue.

And yes, I have reservations about their support for the JavaScript library for Gemini. This is the third (or fourth, depending how you count) library for Bard/Gemini that they've published. And they published it significantly later than their Python library. Other AI products from Google do not have JavaScript libraries at all.

I'd rather just deprecate them and give people an upgrade path to @langchain/google

My thinking on this is that the best strategy might be something like:

• For a version 0.3, include the compatibility packages clearly marked as deprecated. This gives a good migration path with plenty of time to migrate and to update all documentation to reflect the new @langchain/google package.
• In a future 0.4 (say, after a year), remove these deprecated libraries.

I don't want to do what Google has done - moved to a completely new package with absolutely no migration path and no warning.

is there a reason that we have to inundate ourselves with interfacing with the auth deps?

Mostly because we should make the most common operations the simplest.

Looking at current usage of the various Google packages, about 50% are using -genai, and thus using API Keys. The other 50% are overwhelmingly using -vertexai, and many of these are probably running on Google Cloud, so no authentication key or configuration in the code is specifically needed at all (this is the Application Default Credentials configuration (ADC), that google-auth-library supports). Only a tiny few use -vertex-web.

So requiring additional configuration to run in an ADC environment would defeat the purpose.

We're still testing a picture-perfect bundler setup here technically. I have no doubt that this works under lab conditions, but my gut tells me this won't track across a number of existing setups without difficulty (something I'd like to avoid if at all possible).

I think this is my broad concern as well. We have the list of platforms that @hntrl mentioned in the environment tests, and I think if we're addressing those, my concerns are somewhat mitigated. The term "web" was meant as a generic one - not just to talk about browsers. (And I'll admit and apologize that my concerns are based on vague old memories about why the split was done in the first place.)

Bottom Line

• I think this is on the right track. I just want to make sure we advance carefully.
• I still need to look at the whole thing and make sure I get it. I promise more feedback on this vein soon!