Skip to main content

useAuth

Configuration

Below is the config object for useAuth defined as a TypeScript type:

type UseAuthOptions = {
	/**
	 * Default is "redirect". Learn more about these two strategies
	 * @link https://faustjs.org/docs/auth#strategies
	 */
	strategy?: "redirect" | "local";
 
	/**
	 * The login page Uri. Only applicable/required when strategy is "local".
	 */
	loginPageUri?: string;
 
	/**
	 * If useAuth should automatically redirect to the login page
	 * if there is no authenticated user.
	 */
	shouldRedirect?: boolean;
 
	/**
	 * Used to skip the invocation of the hook. Good for if you
	 * want to call the hook conditionally.
	 */
	skip?: boolean;
};

Further, the useAuth exports defined as a TypeScript type look like this:

type UseAuth = {
  /**
   * A way to determine if a user is authenticated or not. The value is `null` by default, and then changes to a boolean once the state is determined.
   */
  isAuthenticated: boolean | null;
 
  /**
   * A boolean to determine if the useAuth exports are ready to be used.
   */
  isReady: boolean;
 
  /**
   * The url of the login page. This may either be a Next.js file based page or
   * the login page on the WordPress backend based on your strategy.
   */
  loginUrl: string | null;
 
  /**
   * A callable function to login a user from your Faust app. Accepts a parameter of either username/email, password, and an optional url to redirect the user to after a successful login.
   */
  login: (
    usernameEmail: string,
    password: string,
    redirectUrl?: string,
  ) => void;
 
  /**
   * A callable function to logout a user from your Faust app. Accepts an optional uri parameter to redirect after logout.
   */
  logout: (redirectUrl?: string) => void;
 
   /**
   * Exposes viewer options to the toolbar if the user is authenticated.
   */
  viewer: = {
    name?: string;
    username?: string;
    capabilities?: string[];
    databaseId?: number;
    description?: string;
    email?: string;
    firstName?: string;
    id?: number;
    lastName?: string;
    nickname?: string;
    locale?: string;
    registeredDate?: string;
    slug?: string;
    templates?: string[];
    uri?: string;
    url?: string;
    userId?: number;
  } | null;
};

Usage

Below is a full example of login/logout and showing/hiding authenticated content. This below example uses the “redirect” strategy:

import { gql, useQuery } from "@apollo/client";
import { getApolloAuthClient, useAuth } from "@faustwp/core";
import { useLogout } from "@faustwp/core";
 
function AuthenticatedView() {
	const client = getApolloAuthClient();
	const { logout } = useLogout();
 
	const { data, loading } = useQuery(
		gql`
			{
				viewer {
					posts {
						nodes {
							id
							title
						}
					}
					name
				}
			}
		`,
		{ client },
	);
 
	if (loading) {
		return <>Loading...</>;
	}
 
	return (
		<>
			<p>Welcome {data?.viewer?.name}!</p>
 
			<p>My posts</p>
 
			<ul>
				{data?.viewer?.posts?.nodes.map((post) => (
					<li key={post.id}>{post.title}</li>
				))}
			</ul>
 
			<button onClick={() => logout()}>Logout</button>
		</>
	);
}
 
export default function Page(props) {
	const { isAuthenticated, isReady, loginUrl } = useAuth({
		strategy: "redirect",
		shouldRedirect: false,
	});
 
	if (!isReady) {
		return <>Loading...</>;
	}
 
	if (isAuthenticated === true) {
		return <AuthenticatedView />;
	}
 
	return (
		<>
			<p>Welcome!</p>
			<a href={loginUrl}>Login</a>
		</>
	);
}