Askrock Components

Embeddable React chat components for Askrock. Add the client-side chat experience to any React application with a full-page component or a floating widget.

Components

ChatComponent

A full-page conversational interface. The user chats with an AI assistant that checks availability and books appointments in real time.

ChatWidget

A floating button + popup chat window that can be anchored to any corner of the viewport. Ideal for landing pages and support portals.

Installation

pnpm add @develrock/askrock-components

npm install @develrock/askrock-components

yarn add @develrock/askrock-components

The package is published to the public npm registry. Consuming projects do not need a custom .npmrc registry mapping.

Peer Dependencies

• react >= 18
• react-dom >= 18

Quick Start

1. Import the stylesheet

The components use Tailwind CSS with pre-defined design tokens. Import the bundled stylesheet once in your app:

// app/layout.tsx or equivalent
import '@develrock/askrock-components/styles.css'

If your app already uses Tailwind with shadcn-compatible CSS variables (e.g. --background, --primary, etc.), the components will inherit your theme automatically. Otherwise, the bundled stylesheet provides sensible defaults with light/dark mode support.

2. Use the components

import { ChatComponent } from '@develrock/askrock-components'

export default function ChatPage() {
	return (
		<div className="h-screen">
			<ChatComponent
				projectKey="sk_your_project_key"
				locale="en"
			/>
		</div>
	)
}

import { ChatWidget } from '@develrock/askrock-components/widget'

export default function Layout({ children }: { children: React.ReactNode }) {
	return (
		<>
			{children}
			<ChatWidget
				projectKey="sk_your_project_key"
				position="bottom-right"
				primaryColor="#2563EB"
			/>
		</>
	)
}

Security note: The projectKey is a server credential (sk_...). In production, pass it via a server-side environment variable — never hard-code it in client bundles. In Next.js, render the component from a Server Component that reads process.env.ASKROCK_PROJECT_KEY.

The widget lazy-loads the chat runtime on first open, so pages that mount only <ChatWidget /> keep their initial client bundle lighter.

When serverUrl is omitted, the package uses the default URL injected at package build time from ASKROCK_DEFAULT_SERVER_URL.

API Reference

ChatComponent

| Prop | Type | Default | Description | | ---------------- | --------------------------- | ---------- | ------------------------------------------------------ | | projectKey | string | required | Project secret key (sk_...) for authentication | | serverUrl | string | ASKROCK_DEFAULT_SERVER_URL | Base URL of the Askrock server | | locale | string | "en" | Locale hint for the AI ("en", "it", or any string) | | translations | Partial<ChatTranslations> | — | Override any default UI string | | className | string | — | CSS class for the outer wrapper | | inputClassName | string | — | CSS class for the text input | | primaryColor | string | — | Accent colour for primary chat controls |

ChatWidget

| Prop | Type | Default | Description | | -------------------- | -------------------------------------------------------------------- | ---------------- | ------------------------------------------------ | | projectKey | string | required | Project secret key (sk_...) for authentication | | serverUrl | string | ASKROCK_DEFAULT_SERVER_URL | Base URL of the Askrock server | | locale | string | "en" | Locale hint for the AI | | chatTranslations | Partial<ChatTranslations> | — | Override chat UI strings | | widgetTranslations | Partial<WidgetTranslations> | — | Override widget UI strings | | position | "bottom-right" | "bottom-left" | "top-right" | "top-left" | "bottom-right" | Screen corner | | primaryColor | string | "#2563EB" | Accent colour (header, toggle button, send icon) | | className | string | — | CSS class for the outer wrapper |

ChatTranslations

All keys have sensible defaults in English and Italian. Pass a partial object to override only the strings you need.

interface ChatTranslations {
	greeting: string // "Hello! How can I help you schedule an appointment?"
	placeholder: string // "Type a message..."
	send: string // "Send"
	thinking: string // "Thinking..."
	checkingAvailability: string // "Checking availability..."
	bookingAppointment: string // "Booking appointment..."
	usingTool: string // "Processing..."
	rateLimitError: string // "You've reached the message limit..."
	genericError: string // "Something went wrong..."
}

WidgetTranslations

interface WidgetTranslations {
	title: string // "Chat with us"
	close: string // "Close chat"
	open: string // "Open chat"
	expand?: string // "Expand chat"
	collapse?: string // "Collapse chat"
}

Customisation

Theming

The components use CSS custom properties that follow the shadcn/ui convention. Override them to match your brand:

:root {
	--primary: oklch(0.55 0.2 260);
	--primary-foreground: oklch(0.98 0 0);
	--background: oklch(1 0 0);
	--muted: oklch(0.96 0 0);
	/* ... etc. */
}

Dark Mode

Add the dark class to your <html> or a parent element. The bundled stylesheet includes dark mode variables out of the box.

Custom Translations

<ChatComponent
	projectKey="sk_..."
	serverUrl="https://..."
	locale="fr"
	translations={{
		greeting: 'Bonjour ! Comment puis-je vous aider ?',
		placeholder: 'Tapez un message...',
		send: 'Envoyer',
		thinking: 'Reflexion en cours...',
	}}
/>

Only override the keys you need — everything else falls back to the English defaults.

Example App

A ready-to-run Next.js demo app is included in the example/ directory.

Running the example

# From the project root
pnpm install          # Install all workspace dependencies
pnpm build            # Build the component library first

cd example
cp .env.example .env  # Configure the server URL
pnpm dev              # Starts on http://localhost:3002

The example app provides two demos:

• /chat — Full-page ChatComponent with a project key input form
• /widget — Floating ChatWidget with a project key input form

Both demos connect to a running Askrock server. Make sure the server is running at the URL specified in example/.env.

Development

Publishing

The package is configured for the public npm registry under the @develrock/askrock-components name. The GitHub repository can stay private; npm package visibility is controlled separately.

Publishing is intentionally explicit:

• Push a version tag matching v*.*.*.
• The workflow builds, type-checks, and then runs npm publish via npm Trusted Publishing/OIDC. No NPM_TOKEN secret is required for publishing.
• The npm package must have a Trusted Publisher configured with these values: GitHub Actions, organization/user develrock, repository dr-agent-scheduler-components, workflow filename publish.yml, and allowed action npm publish.
• The workflow injects the default serverUrl from the GitHub Actions variable ASKROCK_DEFAULT_SERVER_URL.
• Before publishing a new version, update the version field in package.json.

For a local dry run of the package contents:

pnpm pack:dry-run

Building the library

pnpm build

Local builds read ASKROCK_DEFAULT_SERVER_URL from the environment or from a root .env file. Use .env.example as the template.

This runs tsup and outputs to dist/:

• dist/index.js — ESM bundle
• dist/index.cjs — CJS bundle
• dist/index.d.ts — TypeScript declarations

Watch mode

pnpm dev

Rebuilds automatically on file changes.

Type checking

pnpm typecheck

Project Structure

askrock-components/
├── src/
│   ├── components/
│   │   ├── ChatComponent.tsx    # Full-page chat interface
│   │   ├── ChatWidget.tsx       # Floating widget
│   │   └── ui/                  # Minimal shadcn primitives (Button, Input, Card)
│   ├── lib/
│   │   └── utils.ts             # Tailwind class merge helper
│   ├── styles/
│   │   └── globals.css          # Theme variables and Tailwind setup
│   ├── types.ts                 # Prop types and translation interfaces
│   └── index.ts                 # Public API exports
├── example/                     # Next.js demo app (port 3002)
├── tsup.config.ts               # Build configuration
├── tsconfig.json
└── package.json

Requirements

This library requires a running Askrock API server. The components authenticate with the server using the project's secret key and stream chat responses via the /api/chat endpoint.