# Connect an application

Canonical: https://auggy.dev/docs/connect-application
Status: Preview
Package: auggy 0.5.0

Advanced preview: generate a typed route client and call an augment route from a Next.js application.

## What you will connect

> **Note: Advanced preview**
>
> This integration is optional. **Auggy** does not replace the application's frontend, database, auth system, or primary backend, and generated client helpers may change before 1.0.

The agent and application remain separate projects. The application calls the GET /services route built in the previous guide through a generated TypeScript client.

**Application path**

```
Next.js filter UI
  -> generated Auggy client
  -> GET /services
  -> catalog augment
  -> searchServices()
```

**Separate repositories**

```
storefront/
  src/lib/auggy-client.ts   # generated
  src/lib/auggy.ts          # application-owned config

my-agent/
  agent.yaml
  augments/catalog/
```

## Inspect the running route

1. Run the agent and open `/console/integrations`.
2. Confirm GET /services appears under App routes with auth none.
3. Confirm the application origin appears under `CORS` origins before testing from a browser.

## Generate the browser client

**Run from the agent project**

```bash
auggy routes my-agent --client ts --target browser \
  --out ../storefront/src/lib/auggy-client.ts
```

The generated file contains typed methods for routes that are safe for browser callers. Regenerate it when a route path, method, schema, or auth mode changes.

## Configure one client

**storefront/.env.local**

```env
NEXT_PUBLIC_AUGGY_BASE_URL=http://localhost:8080
```

**storefront/src/lib/auggy.ts**

```ts
import { createAuggyClient } from "./auggy-client";

export const auggy = createAuggyClient({
  baseUrl: process.env.NEXT_PUBLIC_AUGGY_BASE_URL!,
});
```

> **Warning: The browser URL is public**
>
> Never put creator bearer tokens, signing secrets, provider keys, or agent credentials in NEXT_PUBLIC_ variables.

## Call the capability

**storefront/src/components/service-search.tsx**

```ts
"use client";

import { useState, type FormEvent } from "react";
import { auggy } from "@/lib/auggy";

type Service = {
  id: string;
  name: string;
  summary: string;
  startingAtUsd: number;
};

export function ServiceSearch() {
  const [need, setNeed] = useState("");
  const [services, setServices] = useState<Service[]>([]);
  const [error, setError] = useState<string>();

  async function search(event: FormEvent) {
    event.preventDefault();
    setError(undefined);

    const result = await auggy.get("/services", {
      query: { need },
    });

    if (!result.ok) {
      setError(`Search failed (${result.status})`);
      return;
    }

    setServices(result.data.services);
  }

  return (
    <form onSubmit={search}>
      <input value={need} onChange={(event) => setNeed(event.target.value)} />
      <button type="submit">Search</button>
      {error ? <p>{error}</p> : null}
      <ul>
        {services.map((service) => <li key={service.id}>{service.name}</li>)}
      </ul>
    </form>
  );
}
```

## Allow the application origin

**my-agent/augments/webTransport/augment.yaml**

```yaml
type: webTransport
config:
  port: 8080
  cors:
    origins:
      - http://localhost:3000
```

Restart the agent after changing transport configuration, then confirm the resolved origin in `/console/integrations`.

## Verify the integration

1. Start the agent on port 8080 and the Next.js application on port 3000.
2. Search for gift in the application and confirm Curated Gifting renders.
3. Ask the agent for a gift service under $200 and confirm it reaches the same result through `service_search`.
4. Change the route schema, regenerate the client, and confirm TypeScript reflects the new contract.

## When the capability is protected

| Need | Next step |
| --- | --- |
| Existing app login should authorize **Auggy** | [Add delegated authorization](https://auggy.dev/docs/delegated-authorization/markdown) |
| Production hosting | [Deploy and verify](https://auggy.dev/docs/deploy/markdown) |

## Related

- [Build an augment](https://auggy.dev/docs/build-augment/markdown)
- [Deploy and verify](https://auggy.dev/docs/deploy/markdown)