Quick Start
Share your feedback
Reach out to us with feedback and suggestions to improve the Wix Headless experience, and join the Headless channel of the Devs on Wix Discord community to discuss features and connect with our growing community of developers.
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 the Wix Headless example site. You can test out the live example site, or fork the site's code repo to use as a starting point for your own site or app.
This implementation focuses on simplicity and understandability, rather than feature richness, performance or completeness. For details about additional functionality, see the API Reference. Looking for a more comprehensive example site integrating Wix Headless APIs? Check out our starter templates.
Note: The code in this tutorial is written in JSX, but you can use the SDK in any JavaScript environment.
Implementing the session management flow includes the following steps:
- Set up the Wix Headless environment.
- Create a login component.
- Create a callback page.
- 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:
- If you haven't already, create a project.
When prompted to add functionalities to your new project, select whichever business solutions your project needs. - Set up authorization for your site by creating and configuring an OAuth app.
- Install the SDK client and relevant SDK module packages by running the following commands:
For NPM:For Yarn:Copy1Copy1 - Install the
react
package to handle UI rendering, thejs-cookie
package to handle session cookies, and thenext/server
package with helper functions for Next.js middleware.
For NPM:For Yarn:Copy1Copy1
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:
-
Add the following import statements to the top of your code file:
Copy1 -
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 menu.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.Copy1
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:
-
Define the component function as a default export in your code file:
Copy1 -
Define a state variable by adding the following code in the component function:
Copy1In 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:
-
fetchMember()
- Uses the SDK client'sauth.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.Copy1 -
login()
- Uses the SDK client'sauth.generateOAuthData()
andauth.getAuthUrl()
functions to log in a site visitor. This function runs when a Login button in the rendered UI is clicked.Copy1The SDK client's
auth.generateOAuthData()
function generates the data needed for authorization, which is saved in local storage with the keyoauthRedirectData
. When the Wix-managed authentication process is over, Wix redirects the visitor to the URL provided inredirectUri
. Theauth.getAuthUrl()
function returns a URL for a Wix-managed authentication page calledauthUrl
. -
logout()
- Uses the SDK client'sauth.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.Copy1
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.
1
5. Render the UI
Add the following code to the LoginBar
component function's return
statement to render the UI.
1
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:
-
Add the following import statements to the top of your code file:
Copy1 -
Create an SDK client by adding the following code to your code file:
Copy1
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:
-
Define the component function as a default export in your code file:
Copy1 -
Define state variables by adding the following code in the component function:
Copy1In the steps that follow, the
nextPage
state variable stores the URL of the page to redirect the visitor to, and theerrorMessage
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 /
.
1
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.
1
5. Render the UI
Add the following code to the LoginCallback
component function's return
statement to render the UI.
1
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:
-
Add the following import statements to the top of your code file:
Copy1
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:
1
Complete code examples
You can use the following full code examples as a starting point for developing your own site:
Login component
1
Callback page
1
Middleware
1