@rtd/use-suggestions

use-suggestions

A React hook for fetching search suggestions securely through a Next.js proxy. This package includes a custom hook, helper functions for creating proxy routes, types, and constants to simplify integration with your React/TypeScript projects.

Installation

To install the package locally, you can use yarn add or npm install with a local file path:

yarn add @rtd/use-suggestions

or

npm install @rtd/use-suggestions

Setup

Create the Proxy Route in Next.js

To protect your API key, you must create a Next.js API route that acts as a proxy to the external API. Use the provided createSuggestionsProxyHandler helper function for this.

For Next.js 12 (pages/api/suggestions.ts):

import { createSuggestionsProxyHandler } from '@rtd/use-suggestions'

export default createSuggestionsProxyHandler({
  apiKey: process.env.API_KEY || '',
  targetUrl: 'https://api.suggestions.com/endpoint',
})

For Next.js 13 (app/api/suggestions/route.ts):

import { createSuggestionsProxyHandler } from '@rtd/use-suggestions'
import { NextRequest, NextResponse } from 'next/server'

const handler = createSuggestionsProxyHandler({
  apiKey: process.env.API_KEY || '',
  targetUrl: 'https://api.suggestions.com/endpoint',
})

export const GET = (req: NextRequest) => handler(req, new NextResponse())
export const POST = (req: NextRequest) => handler(req, new NextResponse())

Usage

Importing the Hook

Import the useSuggestions hook, types, and constants in your React component:

import React, { useState } from 'react'
import useSuggestions, { SuggestionsOptions } from '@rtd/use-suggestions'

Example Component

Here’s an example of how to use the useSuggestions hook in a React component:

const SuggestionComponent: React.FC = () => {
  const [query, setQuery] = useState('')

  const options: SuggestionsOptions = {
    includeStops: true,
    includeConcerts: true,
    location: { lat: 39.7392, lng: -104.9903 },
    debounceTime: 400,
  }

  const { suggestions, isLoading, error } = useSuggestions(query, options)

  return (
    <div>
      <input
        type="text"
        value={query}
        onChange={(e) => setQuery(e.target.value)}
        placeholder="Search for suggestions"
      />
      {isLoading && <p>Loading...</p>}
      {error && <p>Error: {error.message}</p>}
      <ul>
        {suggestions.map((suggestion) => (
          <li key={suggestion.slug}>{suggestion.name}</li>
        ))}
      </ul>
    </div>
  )
}

export default SuggestionComponent

Hook API

useSuggestions

Fetches search suggestions from the API.

Parameters:

• rawQuery: string - The search query string.
• options: SuggestionsOptions - Configuration options for the suggestions.
• proxyPath?: string - (Optional) Relative path to the proxy route. Defaults to /api/suggestions.

Returns:

• suggestions: SearchableSuggestion[] - An array of suggestions.
• isLoading: boolean - Loading state.
• error: Error | null - Error state.

Types

The package includes several types to help with type safety in your project:

SuggestionsOptions

Configuration options for the suggestions.

interface SuggestionsOptions {
  includeStops?: boolean
  includeRoutes?: boolean
  includeLocations?: boolean
  includeDestinations?: boolean
  includeConcerts?: boolean
  location?: {
    lat: number
    lng: number
  }
  debounceTime?: number
}

SearchableSuggestion

Base interface for a searchable suggestion.

/**
 * Suggestion Types Returned by the Server
 */
export type SuggestionType =
  | 'location'
  | 'concert'
  | 'stop'
  | 'station'
  | 'route'
  | 'destination'

/**
 * Point Coordinates
 */
export interface Point {
  lat: number
  lng: number
}

/**
 * Base Suggestion with Common Fields
 */
export interface BaseSuggestion extends Point {
  suggestionType: SuggestionType
  name: string
  label: string
  slug: string
  score: number
}

Constants

The package includes the following constants:

DEBOUNCE_TIME_IN_MS

Default debounce time for the search query.

export const DEBOUNCE_TIME_IN_MS = 432

Common Errors

1. Proxy Route Not Configured

If you attempt to use the hook without first creating a proxy route, you will see the following error:

Proxy route not found: "/api/suggestions".
Ensure the proxy route exists and is set up using 'createSuggestionsProxyHandler'.

Solution: Follow the Setup section to create the API route.

2. Invalid Proxy Path

If a developer attempts to pass an external API URL instead of a relative path to the hook:

useSuggestions('query', options, 'https://api.suggestions.com');

The hook throws a validation error:

Invalid proxyPath: "https://api.suggestions.com".
The proxyPath must be a relative path starting with "/".

Solution: Use a relative path, such as /api/suggestions.

Building the Package

To build the package, run:

yarn build

This will compile the TypeScript files and output the results in the dist directory.

License

This project is licensed under the MIT License.