@userfront/node

Node.js SDK

The Userfront Node.js SDK is a fast and easy way to interact with the Userfront API from your Node.js application. Built on top of fetch, this library is designed to be a light and type-safe way for you to manage your Userfront resources.

IMPORTANT: This library is designed for server-side Node.js applications only, such as Express, tRPC, or Hapi servers. Do not use this library on a browser or frontend framework.

For React support in the browser, see @userfront/react.

For Next.js support on the server and client, see @userfront/next.

Requirements

• Node.js v18 or later

Installation

npm install @userfront/node
# or
yarn add @userfront/node
# or
pnpm add @userfront/node

Usage

Environment Methods

Define these environment variables in your .env or however they are configured in your application:

USERFRONT_API_KEY="..."
USERFRONT_TENANT_ID="..."

The SDK will use these variables when they are defined.

import { getTenant } from "@userfront/node";

// Get current tenant
const tenant = await getTenant();

Instantiate the Client

You may choose to instantiate the client instead, for example, when your secrets are retrieved asynchronously, if you're using a context, or if you prefer the greater abstraction. There are other debugging and error handling benefits as well.

import { UserfrontClient } from "@userfront/node";

const Userfront = new UserfrontClient({
  apiKey: "...",
  tenantId: "...",
});

// Get a tenant by id
const tenant = await Userfront.getTenant("...");

Debugging

With the client, an additional cURL logger will be enabled by default in development environments.

curl 'https://api.userfront.com/v0/tenants/{tenantId}' -X GET -H "Content-Type: application/json" -H "Authorization: Bearer uf_live_admin_wn9mwypn_59f60f53fa7cc018d8f93deceb0cc8e3" -H "X-Userfront-Node: v1.0.0"

Disable this by setting debug to false in the client options.

const Userfront = new UserfrontClient({
  debug: false,
});

Error Handling

Responses that are not 2xx will throw a UserfrontFetcherError. Catch them to handle Userfront errors appropriately.

import { UserfrontFetcherError } from "@userfront/node";

try {
  const user = await Userfront.getTenant("...");
} catch (error) {
  if (error instanceof UserfrontFetcherError) {
    // Handle the error
  }
}

Client Options

Option	Default	Description
apiKey	USERFRONT_API_KEY	The secret admin API key, from Authentication / API Keys in the Userfront dashboard.
baseUrl	'https://api.userfront.com'	The API URL to use for requests, in case you're using a proxy or custom domain.
version	'v0'	The API version to use, an empty string will remove the version from requests.
tenantId	USERFRONT_TENANT_ID	The parent workspace ID, this can be found on the Userfront dashboard.
mode	NODE_ENV === 'production' ? 'live' : 'test'	The mode to use, live when process.env.NODE_ENV is production, otherwise test. To enable live mode, visit Live Domains in the Userfront dashboard.
origin	undefined	The origin header for requests, this may be required in some cases.
debug	NODE_ENV !== 'production'	Log a cURL per request, disabled when process.env.NODE_ENV is production.