​
Available Modules

The SDK provides a number of modules with methods for interacting with Nile:

Auth

Securely authenticating users

DB

Tenant-aware querying of your database

Users

Managing users

Tenants

Managing tenants

Routes

Built-in and custom routes

​
Understanding the Nile Instance

A configured Nile instance handles proxying requests to the Nile Auth API. Your client connects to your server, which then formats and ensures the requests can be handled by the Nile Auth API. The SDK is designed to make clients talking through your server to the Nile auth service as transparent as possible. In addition, you can use the SDK to directly access the Nile Auth API from your server.

​
A Note on Context

It is important to ensure that the proper context is being used when calling functions from the server side. This can be done in extensions intelligently, or by using nile.withContext. Additionally, the context for the database is enforced for calls via nile.query(...), but not for nile.db.query(...). The SDK will try its hardest to use context whenever possible. Under the hood, it uses AsyncLocalStorage, which relies on execution within the same request lifecycle. If you await or dispatch across async boundaries without using the SDK, the context may be lost, in which will default to the last used. The easiest way to deal with this and ensure proper context 100% of the time is to use a cookie saved by your application when a user determines their tenant, and the SDK will automatically look for nile.tenant-id cookie (TENANT_COOKIE exported by @niledatabase/server).

​
Authentication Flow

​
1. User Initiates Authentication

  • The user clicks a “Sign in” button.
  • This action triggers a signIn method with the chosen provider. Your server handles all requests, which in most cases is simply forwarding them on to the Nile auth service with some additional information to help identify the client.

​
2. Redirect to Provider (OAuth Flow)

  • If an OAuth provider (e.g., Google, GitHub) is used, the user is redirected to the provider’s authentication page. This works by Nile auth returning redirects to your application, which the SDK handles in order to send the user to the provider.
  • The user enters their credentials and grants permission to the application. Because your server is handling the requests, the user is redirected back to your application.

​
3. Provider Callback & Token Exchange

  • After successful authentication, the provider redirects the user back to your application, which proxies the request to the Nile auth service.
  • Nile auth exchanges the authorization code for an access token and forwards the authorization information to your server, which in turn would just pass that on to the client.

​
4. Session Creation

  • Via your service, nile auth provides a secure cookie.
  • The cookie includes basic user information, which can be accessed using the nile.auth.getSession or a full user profile via nile.users.getSelf

​
5. Accessing the Session

  • A session is always within the context of a request. For some frameworks, the session management is handled by an extension, but you can always session data by forwarding the client’s request:
import http from "http";
import { Nile } from "@niledatabase/server";

const nile = Nile();

const server = http.createServer(async (req, res) => {
  const session = await nile.auth.getSession(req);
  if (session) {
    console.log("User is authenticated", session.user);
  });
)}

​
API Reference

The API reference is available in the API Reference section.