The Nile-JS SDK is a toolkit for building multi-tenant applications with React, Next.js, Remix, Express, and more. The React and web components are documented under components. This reference is for the server-side SDK, which is used to build your server-side application logic.

​
Installation

npm install @niledatabase/server

​
Configuration

The SDK is configured using environment variables. You can get these from the Nile Console:

1

Obtain Database Credentials

  1. If you haven’t signed up for Nile yet, sign up here and follow the steps to create a database.
  2. Navigate to Database Settings in your database’s UI at console.thenile.dev.
  3. Go to Connection settings.
  4. Select the CLI icon, and click Generate credentials
  5. Copy the required credentials and store them in an .env file so they can be used in the application to connect to the Nile auth service. 
    NILEDB_USER=niledb_user
NILEDB_PASSWORD=niledb_password
NILEDB_API_URL=https://us-west-2.api.thenile.dev/v2/databases/<database_id>
NILEDB_POSTGRES_URL=postgres://us-west-2.db.thenile.dev:5432/<database_name>

​
Initializing the SDK

The SDK is initialized using the Nile instance. If you initialize the SDK without any arguments, it will use the configuration in the .env file. You can also pass in a configuration object to the Nile constructor to override the configuration in the .env file. For more information about the available configuration options, see configuration.

The Nile object is a singleton. Initializing it multiple times in the same application will return the same instance. 
import { Nile } from "@niledatabase/server";

const nile = await Nile();

​
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.

​
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

​
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.api.auth.getSession or a full user profile via nile.api.auth.me

​
5. Accessing the Session

  • A session is always within the context of a request. You can access session data using:
import http from "http";
import { Nile } from "@niledatabase/server";

const nile = await Nile();

const server = http.createServer(async (req, res) => {
  const session = nile.api.auth.getSession(req);
  // or const session = nile.api.auth.getSession(new Headers('cookie', req.headers.cookie));
  if (session) {
    console.log("User is authenticated", session.user);
  });
)}

​
API Reference

The API reference is available in the API Reference section.

Was this page helpful?