The new Nhost JavaScript SDK: generated, simplified, isomorphic

We're excited to release a redesigned JavaScript SDK and a new approach to how we build and maintain SDKs at Nhost.

Why we rebuilt our SDK architecture

Our previous SDK ecosystem was built around several problematic patterns. First, we maintained individual packages for each service: nhost-graphql, hasura-auth-js, and hasura-storage-js, with the main nhost-js package aggregating them. Very few people were using these individual packages, so there wasn't much benefit to maintaining them separately. Second, the SDKs didn't follow the same patterns as our APIs, making things harder to maintain and understand. Third, the Auth SDK assumed it would run in the browser and didn't work well with non-browser scenarios like server-side rendering.

This approach created several issues:

Complex state management: our SDKs relied heavily on a complex state machine that was difficult to understand, debug, and extend, leading to bugs with server-side logic and multi-tab synchronization.
Maintenance overhead: each time we added or modified service APIs (auth, storage), we had to manually implement those changes across all packages and frameworks.
Inconsistency: manual maintenance across multiple SDKs inevitably led to inconsistencies and version drift between different implementations.

The new SDK addresses these fundamental issues by creating a 1:1 mapping between the API specification and the SDK implementation. For the auth and storage services, the client code is automatically generated from OpenAPI specifications, bringing consistency and making reasoning about the SDK much simpler. The complex state machines are gone, replaced by straightforward, auto-generated code that eliminates the synchronization bugs and complexity that plagued the previous versions.

We've seen these improvements ourselves after migrating our own dashboard two months ago, we experienced significant stability improvements. Beta users have reported similar results.

Automatic SDK generation from OpenAPI specifications

Our solution was to build an SDK generator that automatically creates SDKs from our OpenAPI specifications. This approach consolidates everything into a single @nhost/nhost-js package with clean modules for auth, storage, graphql, functions, and complementary modules for things like session management or SSR support.

When we update our APIs, the SDK automatically reflects the changes - no more manual synchronization across multiple packages. The OpenAPI spec becomes the single source of truth, ensuring consistency across all implementations.

Building for LLMs

While the SDK maintains the familiar nhost.auth, nhost.storage module structure, the individual functions now map 1:1 to the OpenAPI specification. Instead of a single nhost.auth.signIn() function that inferred the authentication method from arguments, we now have dedicated functions like nhost.auth.signInEmailPassword(), nhost.auth.signInOTPEmail(), and nhost.auth.signInIdToken() that directly correspond to API endpoints.

This explicit approach isn't just about developer ergonomics, it's essential for building SDKs that work well with LLMs. LLMs and code generation tools perform significantly better with predictable, explicit function signatures rather than complex inference patterns. When every function maps directly to an API endpoint, AI assistants can understand, suggest, and generate code more accurately.


_20import { createClient } from "@nhost/nhost-js";
_20
_20const nhost = createClient({
_20  subdomain: "your-project",
_20  region: "eu-central-1",
_20});
_20
_20// clean, predictable authentication
_20const response = await nhost.auth.signInEmailPassword({
_20  email: "user@example.com",
_20  password: "password123",
_20});
_20
_20const users = await nhost.graphql.request({
_20  query: `
_20    query GetUsers {
_20      users { id displayName email }
_20    }
_20  `,
_20});

Multi-language foundation

This foundation prepares us for multi-language support. The SDK generator is designed to support multiple languages from the same OpenAPI specification. We're planning to replace the existing hand-written SDK for Dart/Flutter and expanding into other languages like Golang, Python, and more based on community demand.

Transitioning from framework-specific packages

We've deprecated our framework-specific packages (@nhost/react, @nhost/nextjs, @nhost/vue) in favor of the new isomorphic JavaScript SDK. While this requires a bit more initial setup, the consolidation eliminates inconsistencies and version drift, while reducing maintenance burden.

The new approach works universally across all JavaScript environments: Node.js, browsers, and React Native, without framework-specific bloat. More importantly, it ensures that new features and bug fixes are immediately available everywhere, rather than requiring separate updates across multiple packages.

We recognize that this approach requires more manual scaffolding for authentication flows. Based on user feedback, we may re-evaluate this approach and potentially reintroduce framework-specific packages following recommended patterns, or even provide full-blown UI components to simplify getting started.

Getting started

The new SDK is now available. To get started, install the SDK using your favorite package manager:


_10npm install @nhost/nhost-js@^4.0.0


_28import { createClient } from "@nhost/nhost-js";
_28
_28const nhost = createClient({
_28  subdomain: "your-project-subdomain",
_28  region: "eu-central-1",
_28});
_28
_28// authentication
_28await nhost.auth.signUpEmailPassword({
_28  email: "user@example.com",
_28  password: "securePassword123"
_28});
_28
_28// storage
_28await nhost.storage.uploadFiles({
_28  "file[]": [myFile],
_28});
_28
_28// graphQL queries
_28const data = await nhost.graphql.request({
_28  query: "query GetPosts { posts { id title } }"
_28});
_28
_28// functions
_28await nhost.functions.fetch("/my-function", {
_28  method: "POST",
_28  body: JSON.stringify({ data: "example" })
_28});

If you're building a new app: start with @nhost/nhost-js for the best developer experience and future compatibility.

If you're using existing packages (nhost-js < 4.x or framework packages): we'll continue to support them with security patches and bug fixes for at least 6 months, but they won't receive new functionality. While there's no immediate rush to migrate, we recommend starting to plan your transition to the new SDK. Check out our quickstart guides & tutorials for various frameworks and the JavaScript SDK reference for detailed documentation. We're also working on a migration guide and will release it soon.

If you're interested in other languages: our SDK generator is designed to support multiple languages, and we'll be expanding based on community interest and feedback.

We're excited to see what you build with the new SDK. As always, we'd love your feedback on Twitter or Discord. Come help us building the foundation for better code generation tools.