Clusters Feature Integration #2816

ayv8er · 2025-06-27T17:38:29Z

Description and Related Issue(s)

This PR introduces Clusters Universal Name Service integration into the Blockscout explorer. Clusters is a cross-chain identity service that allows users to track multiple wallets across various networks under a single unified name (like vitalik/ or foobar/).

This optional integration adds a new Clusters directory, Clusters leaderboard, individual cluster details page, and search capability. The feature follows established patterns for optional service and includes proper env handling.

Proposed Changes

Environment Variables:

Added two new environment variables:
- NEXT_PUBLIC_CLUSTERS_API_HOST - for Clusters API endpoint
- NEXT_PUBLIC_CLUSTERS_CDN_URL - for Clusters CDN assets
Updated environment preset files in configs/envs/.env.jest and configs/envs/.env.localhost
Added validation schema in deploy/tools/envs-validator/schema.ts
Updated Helm deployment values in review YAML templates - deploy/values/

Documentation and Configuration:

Added Clusters feature documentation to docs/ENVS.md
Updated Jest configuration jest.config.ts and added test mocks jest/mocks/ and jest/setupAfterEnv.ts

API Configuration and Types:

Added clustersApi configuration in configs/app/apis.ts with optional Clusters API integration
Created lib/api/services/clusters.ts for Clusters API service layer
Added Clusters feature configuration in configs/app/features/clusters.ts
Updated API resources and types in lib/api/resources.ts and lib/api/types.ts

TypeScript Types and Stubs:

Created TypeScript type definitions in types/api/clusters.ts
Added test stubs in stubs/clusters.ts
Updated search types in types/api/search.ts

Core Library and Utilities:

Added complete lib/clusters/ directory with utilities for action bar, page utils, and input detection
Created specialized hooks in lib/hooks/:
- useAddressClusters.ts - for address specific cluster data
- useClusterPagination.ts - for cluster pagination logic
- useClusterSearch.ts - for cluster search functionality
- useClustersData.ts - for main clusters data fetching
- useQueryParams.ts - for URL query parameter handling
Updated navigation in lib/hooks/useNavItems.tsx
Updated metadata and analytics mappings for cluster pages in lib/metadata/ and lib/mixpanel/

Testing and QA:

Added comprehensive test coverage for all new utilities and hooks:
- lib/clusters/ utilities - action bar, page utils, input detection
- All custom hooks - useAddressClusters, useClusterPagination, useClusterSearch, useClustersData
- Search integration - useSearchWithClusters
- UI components - ClustersEntity
Updated Jest configuration and added testing infrastructure
Added test mocks for Next.js routes, SVG imports, and React hooks

Pages and Routing:

Added pages/clusters/index.tsx - main clusters directory page
Added pages/clusters/[name].tsx - individual cluster details page
Created corresponding page components:
- ui/pages/Clusters.tsx - clusters directory page component
- ui/pages/Cluster.tsx - individual cluster page component
Updated Next.js routing types in nextjs/nextjs-routes.d.ts

UI Components:

Clusters Directory/Leaderboard - ui/clusters/:
- ClustersActionBar.tsx - search and filter controls
- ClustersDirectoryTable.tsx and ClustersDirectoryTableItem.tsx - directory views
- ClustersDirectoryListItem.tsx - directory list item
- ClustersLeaderboardTable.tsx and ClustersLeaderboardTableItem.tsx - leaderboard views
- ClustersLeaderboardListItem.tsx - leaderboard list items
Individual Cluster Details - ui/cluster/:
- ClusterDetails.tsx - main cluster detail component
Address Integration - ui/address/clusters/:
- AddressClusters.tsx - clusters tab for address pages
Shared Components:
- ui/shared/ClusterIcon.tsx - cluster icon component
- ui/shared/entities/clusters/ClustersEntity.tsx - cluster entity display

Search and Navigation Integration:

Added cluster search suggestions in ui/snippets/searchBar/SearchBarSuggest/SearchBarSuggestCluster.tsx
Created ui/snippets/searchBar/useSearchWithClusters.tsx
Updated search utilities in ui/shared/search/utils.ts
Updated navigation components in ui/snippets/navigation/NavLinkIcon.tsx
Updated search bar components: SearchBar.tsx, SearchBarInput.tsx, SearchBarSuggest.tsx, SearchBarSuggestItem.tsx

Assets and Icons:

Added icons/clusters.svg for cluster-specific logo use
Updated icon type definitions in public/icons/name.d.ts

Breaking or Incompatible Changes

None. This is an additive feature that introduces optional clusters functionality. Existing installations will continue to work unchanged, and the new feature can be optionally enabled by setting the NEXT_PUBLIC_CLUSTERS_API_HOST environment variable.

Additional Information

5 minute Loom video displaying the Clusters feature - https://www.loom.com/share/6278c920204249b398a6f227b1cb701d?sid=5b7d6a88-b13e-4002-8fab-0c531ac92090

Checklist for PR author

I have tested these changes locally.
I added tests to cover any new functionality, following this guide
Whenever I fix a bug, I include a regression test to ensure that the bug does not reappear silently.
If I have added, changed, renamed, or removed an environment variable
- I updated the list of environment variables in the documentation
- I made the necessary changes to the validator script according to the guide
- I added "ENVs" label to this pull request

…user is searching for a cluster name vs a evm address

tive chain count

…functionality

…nges

…component logic

h tests

…rest of app

…to account

s.isEnabled to top of the function and utilizes select function of useQuery in useAp iQuery

…ays false

…date imports and test

…n addressMetadataSchema sub-schema

ui/pages/Clusters.pw.tsx

ui/cluster/ClusterDetails.tsx

ui/shared/entities/clusters/ClustersEntity.tsx

ui/shared/entities/clusters/ClustersEntity.pw.tsx

tom2drum · 2025-07-11T07:23:15Z

ui/snippets/searchBar/useSearchWithClusters.tsx

+    return {
+      ...clusterQuery,
+      data: clusterQuery.data || [],
+      isError: false,


Could you explain the reasoning behind why the isError flag should always be false?

Cloning the entire query object here doesn't seem like a good idea to me in terms of memory usage. I just want to ensure that it is truly necessary.

isError: false UI reason
In SearchBarSuggest, when query.isError is true, it displays "Something went wrong. Try refreshing the page or come back later."

For better UX where cluster service outages don't break the search experience, cluster search failures show "No results found" while regular search failures show the error message. This behavior is tested and intentional (see test line 415 in useSearchWithClusters.test.tsx).

query object cloning
The UseQueryResult interface has many properties (data, isError, isFetching, refetch, etc.) and needs to return an object matching useQuickSearchQuery's interface since SearchBar.tsx uses them interchangeably.

The cloning preserves all other properties the UI depends on while overriding specific ones for cluster behavior. Memory impact should be minimal since it's a shallow spread of lightweight React Query metadata objects, only for cluster searches.

ui/snippets/searchBar/useSearchWithClusters.tsx

ui/pages/Cluster.pw.tsx

…while keeping search optimization

…ra ui

… and updates vie wport to narrow test case

ayv8er added 30 commits June 22, 2025 14:40

adds clusters api configs

09aff98

adds clusters api configs

18eeee5

adds api types

3e8c016

adds props routes and titles for cluster pages

073ff24

adds query param enum for clusters api

98c2ac4

adds clusters svg

ebc3b21

adds dynamic page routes

416e1ac

adds clusters entity ui in ui/shared/entities

489f650

adds functions to detect input type; will be used to check whether a …

3c78b55

…user is searching for a cluster name vs a evm address

adds stubs for loading skeleton view

bcc9f55

adds pagination hook

ba2481a

adds query param hooks for clusters trpc endpoints

6e82802

adds query param hooks for clusters trpc endpoints

e3176db

adds components that make up the /clusters ui

f51fb65

adds components for /cluster ui

7abf89a

adds clusters api endpoint to query by cluster id

283ca0a

implements call to cluster id endpoint to get ac

31d0ae5

tive chain count

adds clusters search types and in api category

7603627

creates clusters search hook and wraps useQuickSearchQuery hook

0f30607

replaces useQuickSearchQuery for useSearchWithClusters hook for both …

c5698ff

…functionality

add search suggestion ui

a2e02f1

adds optional chaining to handle react re-render when search type cha…

b75739b

…nges

adds cluster ui to ui/pages/address on address details

f50021c

prevents clicking on cluster suggestion if address is non EVM

912538f

adds util functions for testability along with tests, for action bar …

5c66c45

…component logic

refactor - extract clusters display logic wit

d74ebe0

h tests

refactor: extract page utilities from Clusters.tsx with tests

370a674

adds jest testing infra for react components

9a11dc3

adds hook testing coverage

265788d

adds component and integration tests

5176607

ayv8er added 22 commits July 2, 2025 22:49

sets correct action bar height using ACTION_BAR_HEIGHT_DESKTOP constant

1afccf2

implements TimeFormatToggle to Joined column

6a99480

simplifies conditionals and removes unnecessary Box component wrapper

83c2b62

displays standard 404 error screen on erroneous ClusterDetails query

08fca04

standardizes details page to display ETH value and time in line with …

bfbf904

…rest of app

removes redundant debouncing

09b634a

moves useQueryParams hook to lib/router and updates imports and test …

8212d88

…to account

moves config.features.cluster

0c4fbb9

s.isEnabled to top of the function and utilizes select function of useQuery in useAp iQuery

removes unnecessary 3rd column and isContractVerified since it is alw…

861ac38

…ays false

checks clusters enable for placeholder

8111308

makes isClusterClickable condition more generic for future repurpose

ebcdc8e

splits isEvmAddress out to general purpose utility in lib/address, up…

7ad3305

…date imports and test

moves all cluster hooks and tests to lib/clusters folder

5582662

wraps action bar with standard button wrapper

0c4f0a0

makes nextjs-routes mock condition stricter

a63f526

removes NEXT_PUBLIC_METADATA_API_HOST from main schema as it is now i…

de99aa9

…n addressMetadataSchema sub-schema

adds mock clusters api data

d7960c9

adds pw tests for cluster detail page

b1956a3

adds pw tests for clusters directory page

321b12a

adds pw tests for clustersentity ui component

34e4d0f

adds mock envs for pw tests

88646c1

adds clusters api host and cdn url to env.pw

c668ad9

tom2drum requested changes Jul 11, 2025

View reviewed changes

ayv8er added 7 commits July 14, 2025 10:47

fixes resolve react-hooks/rules-of-hooks violation in cluster search …

93cec58

…while keeping search optimization

throws error instead of using app error component

7b76822

uses semantic token to reference color as per standard method in chak…

854441e

…ra ui

removes empty or loading state pw tests

3c8239f

pw tests - uses mockAssetResponse for icons, removes redundant tests,…

4fb6d7c

… and updates vie wport to narrow test case

migrates all clusters pw tests from page.route to mockApiResponse

f1763cd

updates docker generated pw screenshots

a928634

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Clusters Feature Integration #2816

Clusters Feature Integration #2816

ayv8er commented Jun 27, 2025 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tom2drum Jul 11, 2025

Uh oh!

tom2drum Jul 11, 2025

Uh oh!

ayv8er Jul 14, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clusters Feature Integration #2816

Are you sure you want to change the base?

Clusters Feature Integration #2816

Conversation

ayv8er commented Jun 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description and Related Issue(s)

Proposed Changes

Breaking or Incompatible Changes

Additional Information

Checklist for PR author

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tom2drum Jul 11, 2025

Choose a reason for hiding this comment

Uh oh!

tom2drum Jul 11, 2025

Choose a reason for hiding this comment

Uh oh!

ayv8er Jul 14, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ayv8er commented Jun 27, 2025 •

edited

Loading