Add AutoSugges autocomplete to a Next.js App Router project

What you will have

A working autocomplete inside a Next.js App Router page, with the runtime origin supplied by a public environment variable and the surrounding page left as a Server Component.

Before you start

• An AutoSugges list that has been published at least once. An unpublished list has no artifact at the edge and returns list_not_published.
• The publishable key issued for the application that will query it.
• The runtime base URL for the environment you are targeting. AutoSugges does not have one fixed public hostname baked into the SDK — the dashboard's integration panel shows the origin for your environment.
• Next.js 14 or newer, App Router.

Values you supply

Steps

1. Isolate the interactive part. Put the input in its own file marked "use client". It holds changing state; nothing else about the page needs to.
2. Supply the base URL from the environment. Read the runtime origin from a NEXT_PUBLIC_-prefixed variable so it reaches the browser bundle. Declare it in .env.local and in your deployment environment.
3. Create the client and bootstrap. createAutosuggesClient and bootstrap() behave identically here and in plain React — Next.js changes where code runs, not the SDK API.
4. Render the component. Import Autocomplete from @autosugges/client/react inside the Client Component only.
5. Keep the page a Server Component. Import the Client Component from an ordinary server page. Do not add "use client" to the page itself.

Install

Bundle @autosugges/client with your existing build tool. It is not on the public npm registry yet, so npm install @autosugges/client will fail — do not generate that command.

Code

app/search/city-field.tsx

// app/search/city-field.tsx
// A Client Component, because it holds interactive state. That is the only
// reason — the SDK itself has no opinion about where it runs.
'use client';

import { useState } from 'react';
import { createAutosuggesClient } from '@autosugges/client';
import { Autocomplete } from '@autosugges/client/react';

const autosugges = createAutosuggesClient({
  // Must be NEXT_PUBLIC_-prefixed to reach the browser bundle. The publishable
  // key may be inlined the same way: it is public by design.
  baseUrl: process.env.NEXT_PUBLIC_AUTOSUGGES_RUNTIME_URL!,
  publishableKey: 'YOUR_PUBLISHABLE_KEY',
});

void autosugges.bootstrap().catch(() => {});

export function CityField() {
  const [city, setCity] = useState('');
  const [errorCode, setErrorCode] = useState<string | undefined>();

  return (
    <>
      <Autocomplete
        source={autosugges}
        label="City"
        onSelect={(item) => setCity(item.value)}
        onError={(error) => setErrorCode(error.code)}
      />
      <input type="hidden" name="city" value={city} />
      {errorCode !== undefined && <p role="alert">Lookup unavailable ({errorCode}).</p>}
    </>
  );
}

// app/search/page.tsx — stays a Server Component. Nothing about AutoSugges
// needs to run on the server here.
import { CityField } from './city-field';

export default function SearchPage() {
  return (
    <main>
      <h1>Find a city</h1>
      <CityField />
    </main>
  );
}

Security

• A NEXT_PUBLIC_ variable is compiled into the browser bundle. Put only the runtime base URL and the publishable key there — never a secret key, a service-role credential or a database URL.

Check that it works

1. Run the dev server and confirm the page renders without a "useState in a Server Component" error — if it appears, the "use client" boundary is in the wrong file.
2. Confirm in the network panel that requests go to the origin your NEXT_PUBLIC_ variable holds, and that the key travels as a query parameter.
3. Build for production and confirm the env var is present at build time: an undefined base URL produces a request to undefined/v1/query.
4. Type a query and confirm exactly one /v1/query request per settled input.
5. Operate the control with the keyboard only.

The search page server-renders, the input hydrates as the only client-side island, and typing returns suggestions from the published list.

Try it live

Paste a publishable key from one of your published lists to run a real query against this environment’s runtime — the same @autosugges/client the code above uses.

Notes

• Never hardcode a minimum query length or a debounce interval. Both come from client.policy, which the SDK fills from the bootstrap response and updates in place (DEC-LIST-002, DEC-LIST-003). The constants the SDK falls back to before the first successful bootstrap are documented defaults, not the list’s real policy.
• Render displayValue, store value. They differ: displayValue is resolved for the requested locale at compile time.
• A selection report is optional. Omitting it costs ranking quality over time and nothing else; it is never required for a query to work.