Skip to content

[EDU-17906] feat: implement Hybrid Search API integration#456

Open
barbara-celi wants to merge 3 commits intomainfrom
EDU-17906
Open

[EDU-17906] feat: implement Hybrid Search API integration#456
barbara-celi wants to merge 3 commits intomainfrom
EDU-17906

Conversation

@barbara-celi
Copy link
Copy Markdown
Contributor

@barbara-celi barbara-celi commented May 5, 2026

What is the purpose of this pull request?

This PR implements a new /api/search endpoint in the Help Center that proxies requests to the VTEX Docs Hybrid Search API.
The implementation includes:

  • A Next.js API route (/api/search) that validates input, handles errors, and applies CDN caching.
  • A reusable, framework-agnostic hybrid search client (hybrid-search-client.ts) designed to be shared between Help Center and Dev Portal.

What problem is this solving?

EDU-17906 - Implement hybrid search: Help Center implementation

The Help Center currently relies entirely on Algolia for search. This implementation:

  • Creates the backend infrastructure needed to consume the new hybrid search API.
  • Ensures only Help Center content is returned (hardcoded source=help-center).
  • Provides a secure server-side proxy so the hybrid search API key never reaches the browser.
  • Establishes a reusable pattern that can be lifted to @vtexdocs/components and shared with the Dev Portal.

How should this be manually tested?

  1. Update the components dependency (temporary, do not commit): In package.json, ensure @vtexdocs/components points to the branch with hybrid search support. For this task, I'm working on the feat/hybrid-search branch. Important: This change is only needed for testing until the vtexdocs/components PR merges to main. Revert this before committing your final changes.
"@vtexdocs/components": "https://github.com/vtexdocs/components.git#feat/hybrid-search"
  1. Run yarn install to fetch the updated components.
  2. Add environment variables to Netlify:
# Hybrid Search (VTEX Docs API)
NEXT_PUBLIC_HYBRID_SEARCH_ENABLED=true
HS_API_ENDPOINT=https://vtexdocs-edge.vtex.com
HS_API_KEY=(obtain from the hybrid search API credentials)
  1. Run yarn dev.

Screenshots or example usage

image

Types of changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change)
  • Requires change to documentation, which has been updated accordingly.

- Added a new API endpoint `/api/search` that proxies requests to the VTEX Docs Hybrid Search API.
- Implemented query parameter handling, including validation and default limits.
- Introduced caching for successful responses at the CDN edge.
- Created a reusable Hybrid Search client for API interactions.
- Added comprehensive unit tests for the API handler and client functionality.
- Documented the setup and usage in a new `hybrid-search-setup.md` file.
@netlify
Copy link
Copy Markdown

netlify Bot commented May 5, 2026

Deploy Preview for leafy-mooncake-7c2e5e ready!

Name Link
🔨 Latest commit 4a5ce19
🔍 Latest deploy log https://app.netlify.com/projects/leafy-mooncake-7c2e5e/deploys/69fcdcf6e11dc80008bbd951
😎 Deploy Preview https://deploy-preview-456--leafy-mooncake-7c2e5e.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

@barbara-celi barbara-celi self-assigned this May 5, 2026
Copy link
Copy Markdown

@github-actions github-actions Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This pull request does not contain a valid label. Please add one of the following labels: ['release-no', 'release-auto', 'release-patch', 'release-minor', 'release-major']

@barbara-celi barbara-celi added the release-auto Automatic version bump label May 5, 2026
github-actions[bot]
github-actions Bot previously approved these changes May 5, 2026
@barbara-celi barbara-celi added release-minor Minor version bump and removed release-auto Automatic version bump labels May 5, 2026
- Clarified the purpose of the `NEXT_PUBLIC_HYBRID_SEARCH_ENABLED` variable.
- Added detailed steps for enabling hybrid search in local development and Netlify deployment.
- Included a note about the need for a rebuild when using the `NEXT_PUBLIC_` prefix.
@PedroAntunesCosta
Copy link
Copy Markdown
Contributor

PedroAntunesCosta commented May 7, 2026

O deploy preview ainda roda algolia. Notei que a flag NEXT_PUBLIC_HYBRID_SEARCH_ENABLED aparece na documentação mas não aparece no código.

No local aqui também roda algolia, mesmo depois de instalar a dependência da branch feat/hybrid-search

/**
* Reusable client for the VTEX Docs Hybrid Search API.
*
* This module is intentionally framework-agnostic (no Next.js / React
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Acho que esse cliente deveria ser implementado no components. Mas o Cursor falou que isso pode abrir uma vulnerabilidade. Então acho que podemos estudar essa migração com mais calma durante o rollout.

O que acha @brunoamui ?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

release-minor Minor version bump

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants