{"id":39487530,"url":"https://github.com/vtex-apps/session-client","last_synced_at":"2026-01-18T05:28:36.288Z","repository":{"id":47448991,"uuid":"334000505","full_name":"vtex-apps/session-client","owner":"vtex-apps","description":"Provides React hooks and GraphQL queries for your components to read and update the VTEX Session cookie,","archived":false,"fork":false,"pushed_at":"2025-02-10T18:10:23.000Z","size":192,"stargazers_count":6,"open_issues_count":0,"forks_count":1,"subscribers_count":41,"default_branch":"master","last_synced_at":"2025-02-10T18:22:53.407Z","etag":null,"topics":["hacktoberfest","store-framework","vtex-io"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vtex-apps.png","metadata":{"files":{"readme":"docs/README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-01-29T01:12:06.000Z","updated_at":"2025-02-10T18:10:26.000Z","dependencies_parsed_at":"2024-12-13T15:49:53.107Z","dependency_job_id":"f6744fd2-4fea-45e2-8c22-3fe9d7fa012a","html_url":"https://github.com/vtex-apps/session-client","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/vtex-apps/session-client","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vtex-apps%2Fsession-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vtex-apps%2Fsession-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vtex-apps%2Fsession-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vtex-apps%2Fsession-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vtex-apps","download_url":"https://codeload.github.com/vtex-apps/session-client/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vtex-apps%2Fsession-client/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28530817,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-18T00:39:45.795Z","status":"online","status_checked_at":"2026-01-18T02:00:07.578Z","response_time":98,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hacktoberfest","store-framework","vtex-io"],"created_at":"2026-01-18T05:28:36.202Z","updated_at":"2026-01-18T05:28:36.267Z","avatar_url":"https://github.com/vtex-apps.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Session Client\n\nThe Session Client app provides React hooks and GraphQL queries for your components to read and update the [VTEX Session cookie](https://help.vtex.com/en/tutorial/vtex-session-sessions-system-overview--6C4Edou6bYqqEAOCAg2MQQ), responsible for saving data of a specific session of a user browsing in your store. \n\n## Installation\n\nIn your React app's `manifest.json` file, add the Session Client app to the dependency list:\n\n```\n\"dependencies\": {\n    \"vtex.session-client\": \"1.x\"\n  }\n```\n\n\u003e ℹ️ You can have full TypeScript support running `vtex setup --typings` in your CLI afterwards.\n\n## Configuration\n\nThe 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.\n\n### React hooks\n\nTo read the VTEX Session cookie:\n\n- [`useRenderSession`](#useRenderSession)\n- [`useFullSession`](#useFullSession)\n- [`useLazyFullSession`](#useLazyFullSession)\n\nTo update the VTEX Session cookie:\n\n- [`useUpdateSession`](#useUpdateSession)\n- [`useUpdateSessionInline`](#useUpdateSessionInline)\n\n#### `useRenderSession` hook\n\nThis 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](https://github.com/vtex-apps/render-session/blob/master/src/constants.ts). If you need fields that are not in this set, you can use [`useFullSession`](#useFullSession) or [`useLazyFullSession`](#useLazyFullSession).\n\n```tsx\nimport React from 'react'\nimport { useRenderSession } from 'vtex.session-client'\n\nfunction MyComponent() {\n  const { loading, session, error } = useRenderSession()\n\n  if (loading) {\n    return \u003c\u003eSession is loading\u003c/\u003e\n  }\n\n  if (error) {\n    return \u003c\u003eSession has errors\u003c/\u003e\n  }\n\n  console.log({ session })\n\n  return \u003c\u003eSession is ready\u003c/\u003e\n}\n\nexport default MyComponent\n```\n\n#### `useFullSession` hook\n\n\u003e ⚠️ It's not possible to return the session during Server Side Rendering since it is a private query.\n\nRuns a GraphQL query on the client side to query the full user session.\n\nUnder 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](https://www.apollographql.com/docs/react/api/react/hooks/#usequery).\n\n\n```tsx\nimport React from 'react'\nimport { useFullSession } from 'vtex.session-client'\n\nfunction MyComponent() {\n  const { loading, data, error } = useFullSession()\n\n  if (loading) {\n    return \u003c\u003eSession is loading\u003c/\u003e\n  }\n\n  if (error) {\n    return \u003c\u003eSession has errors\u003c/\u003e\n  }\n\n  console.log({ session: data?.session })\n\n  return \u003c\u003eSession is ready\u003c/\u003e\n}\n\nexport default MyComponent\n```\n\nIt 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.\n\nFor example:\n\n```tsx\nuseFullSession({\n  variables: {\n    items: ['store.channel', 'store.countryCode']\n  }\n})\n```\n\n#### `useLazyFullSession` hook\n\nThe same as [`useFullSession`](#useFullSession), but it uses React Apollo's `useLazyQuery` hook instead. You can read more about `useLazyQuery` API [here](https://www.apollographql.com/docs/react/api/react/hooks/#uselazyquery).\n\n```tsx\nimport React from 'react'\nimport { useLazyFullSession } from 'vtex.session-client'\n\nfunction MyComponent() {\n  const [getSession, session] = useLazyFullSession()\n\n  console.log({ session })\n\n  return \u003cbutton onClick={() =\u003e getSession()}\u003eGet session\u003c/button\u003e\n}\n\nexport default MyComponent\n```\n\nIt 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.\n\nFor example:\n\n```tsx\nuseLazyFullSession({\n  variables: {\n    items: ['store.channel', 'store.countryCode']\n  }\n})\n```\n\n#### `useUpdateSession` hook\n\nUpdates the values of a session. Under the hood, it uses React Apollo's `useMutation` hook. You can read more about `useMutation` API [here](https://www.apollographql.com/docs/react/api/react/hooks/#usemutation).\n\nUnlike the `useMutation` hook, this one only returns the mutation function (called in the example below as `updateSession`) — it does not return the mutation result. \n\nAfter 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. \n\n```tsx\nimport React from 'react'\nimport { useUpdateSession } from 'vtex.session-client'\n\nfunction MyComponent() {\n  const updateSession = useUpdateSession()\n\n  return (\n    \u003cbutton\n      onClick={() =\u003e\n        updateSession({\n          variables: {\n            fields: { foo: 'bar', baz: 123 },\n          },\n        })\n      }\n    \u003e\n      Update session\n    \u003c/button\u003e\n  )\n}\n\nexport default MyComponent\n```\n\n#### `useUpdateSessionInline` hook\n\nUpdates the values of a session. Under the hood, it uses React Apollo's `useMutation` hook. You can read more about `useMutation` API [here](https://www.apollographql.com/docs/react/api/react/hooks/#usemutation).\n\nDifferently from the [`useUpdateSession`](#useUpdateSession), this hook will not reload the page after calling the mutation function.\n\n```tsx\nimport React from 'react'\nimport { useUpdateSessionInline } from 'vtex.session-client'\n\nfunction MyComponent() {\n  const [updateSession, updatedSession] = useUpdateSessionInline()\n\n  console.log({ updatedSession })\n\n  return (\n    \u003cbutton\n      onClick={() =\u003e\n        updateSession({\n          variables: {\n            fields: { foo: 'bar', baz: 123 },\n          },\n        })\n      }\n    \u003e\n      Update session\n    \u003c/button\u003e\n  )\n}\n\nexport default MyComponent\n```\n\nIt 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.\n\nFor example:\n\n```tsx\nupdateSession({\n  variables: {\n    fields: { foo: 'bar', baz: 123 },\n    items: ['store.channel', 'store.countryCode']\n  }\n})\n```\n\n### GraphQL query and mutation\n\n#### `session` query\n\nGets the current user session.\n\n```graphql\nquery session($items: [String]) {\n  session(items: $items) @context(provider: \"vtex.session-client\") {\n    ... on SessionSuccess {\n      id\n      namespaces\n    }\n    ... on SessionError {\n      type\n      message\n    }\n  }\n}\n```\n\n#### `updateSession` mutation\n\nChanges the current user session using the following variables: `{ \"fields\": { \"foo\": 123, \"baz\": \"abc\" } }`\n\n```graphql\nmutation updateSession($fields: SessionFieldsJSONInput!, $items: [String]) {\n  updateSession(fields: $fields, items: $items)\n    @context(provider: \"vtex.session-client\") {\n    ... on SessionSuccess {\n      id\n      namespaces\n    }\n    ... on SessionError {\n      type\n      message\n    }\n  }\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvtex-apps%2Fsession-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvtex-apps%2Fsession-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvtex-apps%2Fsession-client/lists"}