The Session Client app provides React hooks and GraphQL queries for your components to read and update the VTEX Session cookie, responsible for saving data of a specific session of a user browsing in your store.
Installation
In your React app's manifest.json file, add the Session Client app to the dependency list:
_10"dependencies": {_10 "vtex.session-client": "1.x"_10 }
You can have full TypeScript support running
vtex setup --typingsin your CLI afterwards.
Configuration
The Session Client's React hooks allow you to read and update the VTEX Session cookie as desired. On the other hand, the GraphQL query and mutation enable your app to fetch and change the current user session.
React hooks
To read the VTEX Session cookie:
To update the VTEX Session cookie:
useRenderSession hook
This hook is the fastest way to access session data, using the session response from render-session. One caveat: the session values are limited to a set of values. If you need fields that are not in this set, you can use useFullSession or useLazyFullSession.
_20import React from 'react'_20import { useRenderSession } from 'vtex.session-client'_20_20function MyComponent() {_20 const { loading, session, error } = useRenderSession()_20_20 if (loading) {_20 return \<\>Session is loading</>_20 }_20_20 if (error) {_20 return \<\>Session has errors</>_20 }_20_20 console.log({ session })_20_20 return \<\>Session is ready</>_20}_20_20export default MyComponent
useFullSession hook
It's not possible to return the session during Server Side Rendering since it is a private query.
Runs a GraphQL query on the client side to query the full user session.
Under the hood, it's a wrapper of React Apollo's useQuery passing the GraphQL session query. You can read more about the useQuery API here.
_20import React from 'react'_20import { useFullSession } from 'vtex.session-client'_20_20function MyComponent() {_20 const { loading, data, error } = useFullSession()_20_20 if (loading) {_20 return \<\>Session is loading</>_20 }_20_20 if (error) {_20 return \<\>Session has errors</>_20 }_20_20 console.log({ session: data?.session })_20_20 return \<\>Session is ready</>_20}_20_20export default MyComponent
It also accepts a GraphQL variable called items which is an array of strings. These strings should match attributes inside the Session object, and only those attributes will be then fetched and returned.
For example:
_10useFullSession({_10 variables: {_10 items: ['store.channel', 'store.countryCode']_10 }_10})
useLazyFullSession hook
The same as useFullSession, but it uses React Apollo's useLazyQuery hook instead. You can read more about useLazyQuery API here.
_12import React from 'react'_12import { useLazyFullSession } from 'vtex.session-client'_12_12function MyComponent() {_12 const [getSession, session] = useLazyFullSession()_12_12 console.log({ session })_12_12 return <button onClick={() => getSession()}>Get session</button>_12}_12_12export default MyComponent
It also accepts a GraphQL variable called items, which is an array of strings. These strings should match attributes inside the Session object, and only those attributes will be then fetched and returned.
For example:
_10useLazyFullSession({_10 variables: {_10 items: ['store.channel', 'store.countryCode']_10 }_10})
useUpdateSession hook
Updates the values of a session. Under the hood, it uses React Apollo's useMutation hook. You can read more about useMutation API here.
Unlike the useMutation hook, this one only returns the mutation function (called in the example below as updateSession) — it does not return the mutation result.
After calling the mutation function, the hook reloads the page, guaranteeing that the whole page data is updated to the new session parameters. This is extremely useful in pages where the content changes according to the session values, such as the search results.
_22import React from 'react'_22import { useUpdateSession } from 'vtex.session-client'_22_22function MyComponent() {_22 const updateSession = useUpdateSession()_22_22 return (_22 <button_22 onClick={() =>_22 updateSession({_22 variables: {_22 fields: { foo: 'bar', baz: 123 },_22 },_22 })_22 }_22 >_22 Update session_22 </button>_22 )_22}_22_22export default MyComponent
useUpdateSessionInline hook
Updates the values of a session. Under the hood, it uses React Apollo's useMutation hook. You can read more about useMutation API here.
Differently from the useUpdateSession, this hook will not reload the page after calling the mutation function.
_24import React from 'react'_24import { useUpdateSessionInline } from 'vtex.session-client'_24_24function MyComponent() {_24 const [updateSession, updatedSession] = useUpdateSessionInline()_24_24 console.log({ updatedSession })_24_24 return (_24 <button_24 onClick={() =>_24 updateSession({_24 variables: {_24 fields: { foo: 'bar', baz: 123 },_24 },_24 })_24 }_24 >_24 Update session_24 </button>_24 )_24}_24_24export default MyComponent
It also accepts a GraphQL variable called items, which is an array of strings. These strings should match attributes inside of the Session object, and only those attributes will be then fetched and returned.
For example:
_10updateSession({_10 variables: {_10 fields: { foo: 'bar', baz: 123 },_10 items: ['store.channel', 'store.countryCode']_10 }_10})
GraphQL query and mutation
session query
Gets the current user session.
_12query session($items: [String]) {_12 session(items: $items) @context(provider: "vtex.session-client") {_12 ... on SessionSuccess {_12 id_12 namespaces_12 }_12 ... on SessionError {_12 type_12 message_12 }_12 }_12}
updateSession mutation
Changes the current user session using the following variables: { "fields": { "foo": 123, "baz": "abc" } }
_13mutation updateSession($fields: SessionFieldsJSONInput!, $items: [String]) {_13 updateSession(fields: $fields, items: $items)_13 @context(provider: "vtex.session-client") {_13 ... on SessionSuccess {_13 id_13 namespaces_13 }_13 ... on SessionError {_13 type_13 message_13 }_13 }_13}