Installation

Requirements

• Node.js 18+
• React 18 or 19
• Tailwind CSS (v3). The components ship with Tailwind class names, so your build has to generate them.
• A server runtime: Next.js 14+ (App Router) or Express 4+

Install the packages

npm

npm install @gnomondigital/nebulas-kit-react @gnomondigital/nebulas-kit-core

pnpm

pnpm add @gnomondigital/nebulas-kit-react @gnomondigital/nebulas-kit-core

yarn

yarn add @gnomondigital/nebulas-kit-react @gnomondigital/nebulas-kit-core

Note

To use charts inside widgets (Chart components or fenced ```vega blocks in answers), also install the optional peer vega-embed. Without it, charts render as nothing and everything else still works.

Set up Tailwind

1. Scan the kit’s files for class names. Add the package’s dist folder to content in tailwind.config.ts, and map the color tokens the components use:

   tailwind.config.ts

   import type { Config } from "tailwindcss";
   
   const config: Config = {
     content: [
       "./src/**/*.{js,ts,jsx,tsx,mdx}",
       // Required: the components' class names live here
       "./node_modules/@gnomondigital/nebulas-kit-react/dist/**/*.js",
     ],
     theme: {
       extend: {
         colors: {
           background: "hsl(var(--background))",
           foreground: "hsl(var(--foreground))",
           primary: {
             DEFAULT: "hsl(var(--primary))",
             foreground: "hsl(var(--primary-foreground))",
           },
           muted: {
             DEFAULT: "hsl(var(--muted))",
             foreground: "hsl(var(--muted-foreground))",
           },
           border: "hsl(var(--border))",
           input: "hsl(var(--input))",
           ring: "hsl(var(--ring))",
         },
       },
     },
     plugins: [],
   };
   
   export default config;

2. Define the tokens in your global stylesheet. The values are HSL channels (no hsl() around them). Change them to match your site:

   globals.css

   @tailwind base;
   @tailwind components;
   @tailwind utilities;
   
   :root {
     --background: 0 0% 100%;
     --foreground: 224 71% 4%;
     --primary: 221 83% 53%;
     --primary-foreground: 0 0% 100%;
     --muted: 220 14% 96%;
     --muted-foreground: 220 9% 46%;
     --border: 220 13% 91%;
     --input: 220 13% 91%;
     --ring: 221 83% 53%;
   }
   
   body {
     background-color: hsl(var(--background));
     color: hsl(var(--foreground));
   }

Unstyled chat?

If the chat button shows up as plain text or the panel has no layout, Tailwind isn’t scanning the kit. Check the node_modules/@gnomondigital/nebulas-kit-react/dist line in content. In a monorepo, the path is relative to the app folder.

Which import path?

nebulas-kit-core has several entry points. Import from the one that matches where the code runs, so you don’t bundle code you don’t need:

Import	Use it in
@gnomondigital/nebulas-kit-core	Shared server code: configureNebulasServer, getAuthHeaders, and the Express routers.
@gnomondigital/nebulas-kit-core/nextjs	Next.js route handlers (app/api/**/route.ts).
@gnomondigital/nebulas-kit-core/express	Express servers. Next.js isn’t loaded.
@gnomondigital/nebulas-kit-core/client	Browser code (React, Vite). next/server is never bundled.
@gnomondigital/nebulas-kit-core/a2ui	Low-level surface protocol, if you want to render surfaces without React.

Next: configure the server.