Installation

Prerequisites

• Vue 3.0+
• Node.js 16+

Package Installation

Install the package using your preferred package manager:

npm

npm install @sprout_ai_labs/sidekick

yarn

yarn add @sprout_ai_labs/sidekick

pnpm

pnpm add @sprout_ai_labs/sidekick

Plugin Setup

Install the plugin globally in your main application file:

// main.ts
import { createApp } from 'vue'
import SproutSidekick from '@sprout_ai_labs/sidekick'
import '@sprout_ai_labs/sidekick/dist/sprout-sidekick.css'
import App from './App.vue'

const app = createApp(App)

// Install the plugin with required configuration
app.use(SproutSidekick, {
  mode: 'PROD', // Required: 'QA' or 'PROD'
  appName: 'My Application', // Required: Your application name (used for analytics)
  skipDesignSystem: true, // Optional: Skip installing the design system if already installed
})

app.mount('#app')

REQUIRED PARAMETERS

Both mode and appName are required parameters. The plugin will throw an error if either is missing:

• mode: Determines which backend environment to use ('QA' or 'PROD')
• appName: Identifies your application in analytics tracking

CSS Import

Don't forget to import the CSS file for proper styling:

import '@sprout_ai_labs/sidekick/dist/sprout-sidekick.css'

Or in your CSS file:

@import '@sprout_ai_labs/sidekick/dist/sprout-sidekick.css';

State Management

The plugin includes built-in state management for chat functionality. No additional setup is required.

TypeScript Support

The plugin includes comprehensive TypeScript definitions. No additional setup is required for TypeScript projects.

Configuration

The plugin can be configured with various options:

app.use(SproutSidekickPlugin, {
  mode: 'PROD', // Required: 'QA' or 'PROD'
  appName: 'My Application', // Required: Your application name
  baseUrl: 'https://custom-backend.com', // Optional: custom URL (takes precedence over mode)
  skipDesignSystem: true, // Optional: Skip installing the design system if already installed
  deviceSource: 'web', // Optional: 'web' or 'mobile' (default: 'web')
})

Configuration Options

Required Parameters

Mode (mode)

Required - Specifies which backend environment to use.

• Type: 'QA' | 'PROD' | 'qa' | 'prod'
• Required: Yes
• Case-insensitive: Accepts 'QA', 'qa', 'PROD', 'prod'
• Uses VITE_CHAT_BE_QA when mode is 'QA'
• Uses VITE_CHAT_BE_PROD when mode is 'PROD'

App Name (appName)

Required - Identifies your application in analytics tracking.

• Type: string
• Required: Yes
• Purpose: Used in analytics to track which application is generating queries
• Example: 'Sprout HR', 'Sprout Payroll', 'My Custom App'

Optional Parameters

Base URL (baseUrl)

Optional custom backend URL (string)

• Type: string
• Required: No
• Takes precedence over mode when provided
• Allows you to specify any backend URL directly
• Useful when you need to connect to a custom backend or override the environment-based selection

Device Source (deviceSource)

Optional device source identifier

• Type: 'mobile' | 'web'
• Required: No
• Default: 'web'
• Used for analytics tracking

Skip Design System (skipDesignSystem)

Optional flag to skip design system installation

• Type: boolean
• Required: No
• Default: false
• Set to true if your application already has the design system installed

Priority Order for Backend URL:

1. baseUrl (if provided) - highest priority
2. mode (uses corresponding environment variable)
3. Throws error if neither is properly configured

Configuration Examples

Minimal configuration (required parameters only):

app.use(SproutSidekickPlugin, {
  mode: 'PROD', // Required
  appName: 'Sprout HR', // Required
})

Full configuration with optional parameters:

app.use(SproutSidekickPlugin, {
  mode: 'PROD', // Required
  appName: 'Sprout Payroll', // Required
  deviceSource: 'mobile', // Optional
  skipDesignSystem: true, // Optional
})

Using custom baseUrl (overrides mode):

app.use(SproutSidekickPlugin, {
  mode: 'QA', // Required (but baseUrl takes precedence)
  appName: 'My Custom App', // Required
  baseUrl: 'https://my-custom-backend.com', // This URL will be used
})

ERROR HANDLING

If you don't provide required parameters, the plugin will throw an error:

app.use(SproutSidekickPlugin, {})
// ❌ Error: SidekickChatOptions.mode is required
// ❌ Error: SidekickChatOptions.appName is required

The plugin works out of the box without additional configuration. All chat state and functionality is managed automatically.

Next Steps

Now that you have the plugin installed, learn how to use it in the Usage Guide.