EDU-18362: FastStore hooks troubleshooting

[mariana-caetano]

Summary

Provide a concise description of the change introduced by this PR.
Example: “Updates the Checkout overview to include new webhook behavior.”

---

Type of change

• New content — Adds new documentation.
• Content update — Improves existing documentation (clarity, structure, examples, accuracy).
• Bug fix — Fixes markdown issues.
• Editorial fix — Spelling, grammar, or minor copy edits that don’t change meaning.
• Content removal — Deletes deprecated or obsolete content.

---

Checklist

• The content follows the VTEX Style Guide.
• Markdown renders correctly (headings, lists, tables, callouts).
• Links, images, code blocks, and examples are valid.
• Terminology, product names, and API references are consistent.
• Frontmatter (title, description, tags, slug) is correct
• Files follow the expected folder structure and naming conventions.

---

AI review instructions

This repository supports automated AI reviews for Markdown files in the docs folder, except docs/localization.

To run reviews on this PR, add at least one of the following labels:

• AI style review: evaluates tone and adherence to VTEX style guidelines.
• AI grammar review: identifies grammar and spelling issues.

Once at least one label is added, the review(s) will run automatically.

After the review is completed, the corresponding label will be removed and the label AI reviewed will be added to the PR.

Note

To rerun a review, remove and add the desired label again.

[github-actions]

👁️‍🗨️ Preview changes on Developer Portal

You can use the link below to load the Developer Portal in preview mode with the changes from this branch:

👉 Open preview environment

Below is the list of modified pages and their corresponding preview URLs:

File	Preview URL	Sidebar
docs/troubleshooting/storefront/issues-when-using-faststore-hooks.md	https://developers.vtex.com/docs/troubleshooting/issues-when-using-faststore-hooks	⚠️ Missing from navigation.json

[github-actions]

🔍 Documentation feedback for docs/troubleshooting/development/issues-when-using-faststore-hooks.md

This is a review of the Issues when using FastStore hooks Troubleshooting documentation.

1. General Feedback

The document is well-organized and provides clear, actionable steps for various scenarios. However, it deviates from the specific VTEX Troubleshooting rules regarding the title perspective, the number of keywords, and the explicit mention of responsibility for the steps. The structure uses a summary table followed by sections, which is helpful for readability, but the table itself should more closely follow the "Error | Meaning | Action" format defined in rule R1.1.

---

2. Actionable Feedback

• Frontmatter (Title): The title "Issues when using FastStore hooks" is neutral. According to the rules, it must be in the first-person perspective (e.g., "I'm having issues with FastStore hooks") and focus on what the user cannot do.
• Frontmatter (Keywords): You included 6 keywords. The rules specify a limit of up to 3 key terms.
• Body (Responsibility): Rule R1.7 requires indicating who is responsible for the steps. Since FastStore is a developer-focused product, you should explicitly state that the developer/user is responsible for these configurations.
• Body (Table Format): Rule R1.1 suggests that for multiple errors, a table should be used where each row contains the Error message, Meaning, and Required action. Your current table acts more like a navigation menu. I will consolidate the information into a more compliant format or ensure the sections clearly define these three elements.
• Style (Active Voice): Most instructions are in the imperative mood, which is good. Ensure all steps start with a strong verb.

---

3. Suggested Revision

---
title: "I'm having issues with FastStore hooks"
slug: "issues-when-using-faststore-hooks"
hidden: false
createdAt: "2026-05-19T00:00:00.000Z"
updatedAt: "2026-05-19T00:00:00.000Z"
excerpt: "Common issues when using FastStore hooks in your store project, including import errors, context errors, stale data, performance issues, and TypeScript errors."
tags:
    - FastStore
---

Keywords: FastStore, hooks, React

[FastStore hooks](https://developers.vtex.com/docs/guides/faststore/developer-tools-hooks-overview) give you access to built-in store features and state. During implementation, you may encounter issues such as import errors, context errors, stale data, performance regressions, or type mismatches.

To resolve these issues, the developer must identify the specific error and follow the corresponding actions below.

| Error message / Issue | Meaning | Required action |
| --------------------- | ------- | --------------- |
| Import error or `undefined` return. | The hook is not available in the current scope or package. | 1. Verify the package (`@faststore/components` or `@faststore/core`) is installed.<br>2. Check version compatibility.<br>3. Ensure the app is wrapped with `UIProvider`. |
| `Hook must be used within Provider` | The hook is called outside its required React Context. | 1. Wrap the component tree with the required provider (e.g., `UIProvider`, `SKUMatrixProvider`).<br>2. Move the provider higher in the component tree. |
| Stale or outdated data. | React dependency arrays or subscriptions are not updating correctly. | 1. Add all relevant values to `useEffect` dependency arrays.<br>2. Verify store subscriptions.<br>3. Clear GraphQL cache if using data hooks. |
| Performance regressions / Slow UI. | Unnecessary re-renders or heavy computations on the main thread. | 1. Use `useMemo` for expensive calculations.<br>2. Use `useCallback` for event handlers.<br>3. Implement debouncing for search/filter hooks. |
| TypeScript type mismatches. | Missing type definitions or outdated library versions. | 1. Install missing `@types` packages.<br>2. Import types directly from the FastStore package.<br>3. Update FastStore to the latest version. |

## Solutions

### Hook not available
If you see an import error or the hook returns `undefined`, follow these steps:
1. Verify that the corresponding package is installed in your project (`@faststore/components` for UI hooks or `@faststore/core` for analytics).
2. Check that the installed package version is compatible with your FastStore version.
3. Wrap your app with `UIProvider` if you are using UI hooks like `useUI`.
4. Confirm you are importing the hook from the correct package.

### Context errors
If the error `Hook must be used within Provider` appears, the developer must:
1. Wrap the component tree with the required provider:
   - `UIProvider` for `useUI` and `useSearch`.
   - `SKUMatrixProvider` for `useSKUMatrix`.
   - `ProductComparisonProvider` for `useProductComparison`.
2. Place the provider high enough in the tree to cover all consumer components.
3. Ensure the provider is not rendered conditionally.

### Stale data
If a hook returns outdated information, follow these steps:
1. Review `useEffect` dependencies to ensure they include all values the hook relies on.
2. Verify that store subscriptions are not being unsubscribed unexpectedly.
3. Clear the GraphQL cache to force a fresh data fetch.
4. Check `useMemo` or `useCallback` dependencies for stale references.

### Performance issues
To resolve slow performance or re-renders, the developer must:
1. Wrap expensive computations with `useMemo`.
2. Wrap event handlers with `useCallback`.
3. Apply debouncing to search and filter hooks.
4. Use `useDelayedFacets_unstable` on high-traffic listing pages.
5. Lazy-load content using visibility hooks like `useSlideVisibility`.

### TypeScript errors
To fix type mismatches, follow these steps:
1. Install the corresponding `@types` packages for third-party dependencies.
2. Import required types directly from the FastStore hook package.
3. Use type assertions only as a last resort; prefer runtime type guards.
4. Update your FastStore version to sync with the latest type definitions.

> ⚠️ If the issue continues after following these steps, [open a ticket with VTEX Support](https://help.vtex.com/support).

---

Was this feedback useful?

• Yes
• No

Review made on commit 2a5a0f8

[github-actions]

[link-check] _{reported by reviewdog 🐶}
🚨 Found a broken link in a Markdown Link (Error 404):
https://developers.vtex.com/docs/guides/faststore/developer-tools-hooks-overview

👉 Please review this link before merging your Pull Request.

[mariana-caetano]

The link will work once we merge #2255

[ricardoaerobr]

Apply Symptom filters and Domain filters as indicated on the dev-portal-content README.

[ricardoaerobr]

LGTM!

[github-actions]

[link-check] _{reported by reviewdog 🐶}
🚨 Found a broken link in a Markdown Link (Error 404):
https://developers.vtex.com/docs/guides/faststore/developer-tools-hooks-overview

👉 Please review this link before merging your Pull Request.

[ricardoaerobr]

LGTM!