Skip to content
GUIJam
Please leave a star!11 stars

Integration API

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

ImportFor
guijam/viteVite apps, SvelteKit, React Router, SolidStart, Laravel and other backends
guijam/nextNext.js
guijam/nuxtNuxt
guijam/astroAstro

guijam/vite#

import { guijam } from 'guijam/vite';

guijam(options?: GuijamOptions): Plugin;
OptionTypeDefault
rootstringVite's root
daemonBinarystringGUIJAM_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.

OptionTypeDefault
rootstringprocess.cwd()
daemonBinarystringGUIJAM_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#

nuxt.config.ts
export default defineNuxtConfig({
  modules: ['guijam/nuxt'],
  guijam: { root: './', daemonBinary: '/path/to/gjd' },
});
OptionTypeDefault
rootstringYour Nuxt root directory
daemonBinarystringGUIJAM_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;
OptionTypeDefault
rootstringYour Astro project root
daemonBinarystringGUIJAM_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.
Documentation