Integration API
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#
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:
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#
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#
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#
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.0or>=22.12.0. vite6, 7 or 8 as an optional peer dependency.- The
gjddaemon comes as an optional dependency,@guijam/gjd-<os>-<arch>, for macOS and Linux on arm64 and x64, and Windows on x64. - The
guijambinary is the CLI. See the CLI reference.