Quick Start

Follow this quick start tutorial to get up and running with your first Headless project.

This tutorial walks you through the project setup process and builds a simple site that uses tokens to maintain persistent visitor sessions and to authenticate site members.

You can use the code described here as a springboard for your own project. After building the foundation here to handle visitors and members, you can continue your development by making use of the various modules in the Wix Javascript SDK.

For detailed instructions for managing visitors and members, see Handle Visitors, Handle Members with Managed Login, Handle Members with a Custom Login Page, and Handle Members with Externally-Managed Login.

This tutorial shows you how to implement:

• A React component that handles login and logout by redirecting the visitor to a Wix-managed page.
• A callback page that verifies login and saves member tokens in a cookie.
• Next.js middleware that checks for an existing member or visitor token and generates a new visitor token if one is not found.

The tutorial is based on this example site. To get the code, fork the Headless Templates repo. The site code is under minimal examples.

The site focuses on simplicity and understandability, rather than feature richness, performance or completeness. Looking for a more comprehensive example site integrating Wix Headless APIs? Check out our starter templates.

Implementing the session management flow includes the following steps:

1. Set up the Wix Headless environment.
2. Create a login component.
3. Create a callback page.
4. Create middleware for managing tokens.

Step 1: Set up the Wix Headless environment

Before using the SDK, there are a few things you need to set up on your Wix account and in your external site or app's coding environment.

To set up the Wix Headless environment, follow these steps:

1. If you haven't already, create a project. When prompted to add functionalities to your new project, select whichever business solutions your project needs.
2. Set up authorization for your site by creating and configuring an OAuth app.
3. Install the SDK client and relevant SDK module packages by running the following commands: For NPM:
   Copy

   For Yarn:
   Copy

4. Install the react package to handle UI rendering, the js-cookie package to handle session cookies, and the next/server package with helper functions for Next.js middleware. For NPM:
   Copy

   For Yarn:
   Copy

Step 2: Create a login component

Follow these steps to create a React component that handles login and logout by redirecting the visitor to a Wix-managed page.

1. Import the SDK modules and create an SDK client

To set up the code file for the login component, follow these steps:

1. Add the following import statements to the top of your code file:

   Copy

2. Create an SDK client by adding the following code to your code file. Replace the value for clientId with your OAuth app's client ID. You can find the ID in your project's Headless Settings.

   The value for tokens is the 'session' cookie on the visitor's browser. It's used to make calls to the Wix API. This way, you can maintain previous visitor sessions. If a token has already been generated for the visitor, this token is used.

   Copy

2. Create a React component and a state variable

The logic for our example login request flow is contained in a React component called LoginBar. To create the component, follow these steps:

1. Define the component function as a default export in your code file:

   Copy

2. Define a state variable by adding the following code in the component function:

   Copy

   In the steps that follow, the member state variable stores a visitor's data if they are a logged-in site member.

3. Define functions to handle member sessions

Add the following 3 functions for handling member sessions to the LoginBar component:

1. fetchMember() - Uses the SDK client's auth.loggedIn() function to check if the current site visitor is a logged-in site member. If they are, the rendered UI is updated with the member's details. This function runs when the component is mounted.

   Copy

2. login() - Uses the SDK client's auth.generateOAuthData() and auth.getAuthUrl() functions to log in a site visitor. This function runs when a Login button in the rendered UI is clicked.

   Copy

   The SDK client's auth.generateOAuthData() function generates the data needed for authorization, which is saved in local storage with the key oauthRedirectData. When the Wix-managed authentication process is over, Wix redirects the visitor to the URL provided in redirectUri. The auth.getAuthUrl() function returns a URL for a Wix-managed authentication page called authUrl.

3. logout() - Uses the SDK client's auth.logout() function to log out a site member and remove the session cookie from their browser. This function runs when a Logout button in the rendered UI is clicked.

   Copy

4. Add the useEffect hook

Add the following code to the LoginBar component to run the fetchMember() function after the component is rendered. This ensures that member data is retrieved when the component mounts.

5. Render the UI

Add the following code to the LoginBar component function's return statement to render the UI.

The UI displays the following:

• If no member is logged in: Hello visitor and a Login link.
• If a member is logged in: Hello, <USER_NAME> and a Logout link.

Step 3: Create a callback page

Follow these steps to create a callback page for Wix to redirect the visitor to after handling authentication.

1. Import the SDK modules and create an SDK client

To set up the code file for the callback page, follow these steps:

1. Add the following import statements to the top of your code file:

   Copy

2. Create an SDK client by adding the following code to your code file:

   Copy

2. Create a React component and state variables

The logic for our example login request flow is contained in a React component called LoginCallback. To create the component, follow these steps:

1. Define the component function as a default export in your code file:

   Copy

2. Define state variables by adding the following code in the component function:

   Copy

   In the steps that follow, the nextPage state variable stores the URL of the page to redirect the visitor to, and the errorMessage state variable stores the error received if there is an error generating a member token.

3. Define a function to verify login

Add the following function to the LoginCallback component. This function first retrieves the authorization data saved in local storage by the Login component. Then it retrieves the authorization code and state from the callback page's URL using auth.parseFromUrl(). Using this data, it calls auth.getMemberTokens() to generate access and refresh tokens, which it stores in the 'session' cookie. It then redirects the visitor to the page specified in data.originalUri if it exists, or otherwise to /.

4. Add the useEffect hook

Add the following code to the LoginCallback component to run the verifyLogin() function after the component is rendered. This ensures that tokens are stored when the component mounts.

5. Render the UI

Add the following code to the LoginCallback component function's return statement to render the UI.

The UI displays the following before redirecting the visitor:

• If there was an error, errorMessage is displayed.
• If login was verified, a link to the next page with the text Continue is rendered, along with the text Loading....

Step 4: Create middleware for managing tokens

Once you've implemented a login component and a callback page, follow these steps to create Next.js middleware to check a visitor's session status when loading every page.

1. Import the SDK modules

To set up the code file for the session management middleware, follow these steps:

1. Add the following import statements to the top of your code file:

   Copy

2. Create a middleware function

The logic for our middleware is contained in a function called middleware(). This function checks if a 'session' cookie already exists in the page request. If the cookie isn't found, it generates new visitor tokens using auth.generateVisitorTokens() and stores them in a 'session' cookie to create a new anonymous session which persists when the visitor uses the site from the same browser. Implement this function as follows:

Complete code examples

You can use the following full code examples as a starting point for developing your own site:

Login component

Callback page

Middleware