# Integration API

> The options for guijam() from guijam/vite and guijam/astro, withGuijam() from guijam/next, the guijam/nuxt module, and the plugin API for plugin authors.

The `guijam` package has one entry point per framework. All of them run only in development.

| Import         | For                                                                        |
| -------------- | -------------------------------------------------------------------------- |
| `guijam/vite`  | Vite apps, SvelteKit, React Router, SolidStart, Laravel and other backends |
| `guijam/next`  | Next.js                                                                    |
| `guijam/nuxt`  | Nuxt                                                                       |
| `guijam/astro` | Astro                                                                      |

## guijam/vite

```ts
import { guijam } from 'guijam/vite';

guijam(options?: GuijamOptions): Plugin;
```

| Option         | Type     | Default                                                      |
| -------------- | -------- | ------------------------------------------------------------ |
| `root`         | `string` | Vite's `root`                                                |
| `daemonBinary` | `string` | `GUIJAM_GJD_BIN`, else the `gjd` installed for your platform |

Put it first in `plugins`. The plugin:

- Applies only to the dev server, and runs before other plugins.
- Ignores `.guijam/` in the file watcher.
- Serves the widget at `/@guijam/widget.js`, loaded the first time you pick a tool.
- Points Tailwind at `.guijam/run/candidates/`, so classes that only exist in a preview get their CSS.

Types exported: `GuijamOptions`, `GuijamApi`, `GuijamMessage`, `OverlayOptions` and `UpdateResult`.

### Plugin API

For plugin authors, the plugin exposes an `api` object:

```ts
interface GuijamApi {
  setOverlay(file: string, content: string, options?: OverlayOptions): Promise<UpdateResult>;
  clearOverlay(file: string, options?: OverlayOptions): Promise<UpdateResult>;
  request(message: unknown): Promise<GuijamMessage>;
}

interface OverlayOptions {
  pageReload?: boolean;
}
```

`setOverlay` serves `content` in place of `file` without writing it, and resolves with the hot-update result. `clearOverlay` goes back to the file on disk. `pageReload` defaults to `true` for `.astro` files.

## guijam/next

```ts
import { withGuijam } from 'guijam/next';

withGuijam(
  config?: NextConfigInput,
  options?: GuijamNextOptions,
): (phase: string, context: unknown) => Promise<NextConfigObject>;
```

`config` is your Next.js config, as an object or as a `(phase, context) => config` function. `withGuijam` always returns a config function, which Next.js accepts as the default export.

| Option         | Type     | Default                                                      |
| -------------- | -------- | ------------------------------------------------------------ |
| `root`         | `string` | `process.cwd()`                                              |
| `daemonBinary` | `string` | `GUIJAM_GJD_BIN`, else the `gjd` installed for your platform |

Under `next dev` with Next.js 16.3 or newer, it adds the loader for Turbopack and webpack, loads the toolbar through `instrumentationClientInject`, and starts the localhost relay. In every other phase, it returns your config unchanged.

## guijam/nuxt

```ts title="nuxt.config.ts"
export default defineNuxtConfig({
  modules: ['guijam/nuxt'],
  guijam: { root: './', daemonBinary: '/path/to/gjd' },
});
```

| Option         | Type     | Default                                                      |
| -------------- | -------- | ------------------------------------------------------------ |
| `root`         | `string` | Your Nuxt root directory                                     |
| `daemonBinary` | `string` | `GUIJAM_GJD_BIN`, else the `gjd` installed for your platform |

The module only runs in development.

## guijam/astro

```js
import guijam from 'guijam/astro';

guijam(options?: GuijamOptions): AstroIntegrationLike;
```

| Option         | Type     | Default                                                      |
| -------------- | -------- | ------------------------------------------------------------ |
| `root`         | `string` | Your Astro project root                                      |
| `daemonBinary` | `string` | `GUIJAM_GJD_BIN`, else the `gjd` installed for your platform |

The integration only runs under `astro dev`.

## Package details

- Node `^20.19.0` or `>=22.12.0`.
- `vite` 6, 7 or 8 as an optional peer dependency.
- The `gjd` daemon comes as an optional dependency, `@guijam/gjd-<os>-<arch>`, for macOS and Linux on arm64 and x64, and Windows on x64.
- The `guijam` binary is the CLI. See the [CLI reference](https://guijam.francistinao.com/docs/reference/cli).
