The Userfront Next SDK is a fast and easy way interact with the Userfront API from your Next.js application. Fetch and manage Userfront resources, build impressive server or client components, and experience full-fledged transformational auth without the complexity.
NOTE: This library is designed for Next.js applications only. Do not use this library with any other framework. This library is a combination of @userfront/node for support on the server and @userfront/react for support on the client.
- Next.js v14 or later
npm install @userfront/next
# or
yarn add @userfront/next
# or
pnpm add @userfront/nextAdd the UserfrontProvider with your desired tenantId to the root layout (app/layout.tsx).
import { UserfrontProvider } from "@userfront/next/client";
export default function RootLayout({ children }) {
return (
<html lang="en">
<body>
<UserfrontProvider tenantId="...">
{children}
</UserfrontProvider>
</body>
</html>
);
}| Option | Default | Description |
|---|---|---|
tenantId |
string | The tenant identifier, this can be found in workspace Tenants on the Userfront dashboard. |
loginUrl |
string | Redirect URL for unauthenticated visitors that need to login, the default is /login. |
loginRedirect |
string | Redirect URL after login, false to disable. When undefined, uses the path configured to the workspace paths & routing settings. |
signupRedirect |
string | Redirect URL after signup, false to disable. When undefined, uses the path configured to the workspace paths & routing settings. |
logoutRedirect |
string | Redirect URL after logout, false to disable. When undefined, uses the path configured to the workspace paths & routing settings. |
requireAuth |
boolean | When true, unauthenticated visitors will be redirected to the loginUrl. |
Use @userfront/next/client with client React components. These files or functions should have the "use client"; directive.
Use the useUserfront() hook to access Userfront core and the current client auth state.
import { useUserfront } from "@userfront/next/client";
export default function Component() {
const { user, isLoading } = useUserfront();
if (isLoading) {
return <div>Loading...</div>;
}
return <div>Hello, {user.email}</div>;
}In addition to core and the UserfrontProvider properties, these are also available for use:
| Property | Type | Description |
|---|---|---|
isAuthenticated |
boolean | Whether or not the current visitor is signed into a valid user account. |
isLoading |
boolean | Whether or not Userfront has loaded and initialized. |
Userfront toolkit components are included in this package. Import and use them without any necessary additional props:
import { LoginForm } from "@userfront/next/client";
export default function Component() {
return <LoginForm />;
}The available components are LoginForm, SignupForm, PasswordResetForm and LogoutButton.
Use @userfront/next/server on the server. These files or functions should have the "use server"; directive.
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.
"use server";
import { getTenant } from "@userfront/next/server";
// Get current tenant
const tenant = await getTenant();You may choose to instantiate the Node 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.
"use server";
import { UserfrontClient } from "@userfront/next/server";
const Userfront = new UserfrontClient({
apiKey: "...",
tenantId: "...",
});
// Get a tenant by id
const tenant = await Userfront.getTenant("...");| 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. |
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,
});Responses that are not 2xx will throw a UserfrontFetcherError. Catch them to handle Userfront errors appropriately.
import { UserfrontFetcherError } from "@userfront/next/server";
try {
const user = await Userfront.getTenant("...");
} catch (error) {
if (error instanceof UserfrontFetcherError) {
// Handle the error
}
}