Migrating from NLUX v1 to v2
Overview
NLUX v1.x was released in January 2024, and NLUX v2.x was released in May 2024, with several major improvements and
new features. The new version of NLUX introduces breaking changes to the theming system, TypeScript types, and the
AiChat UI component's config options.
If you're a user of NLUX v1.x looking to migrate to v2.x, this guide is for you.
Scope of the breaking changes:
- Theming system and default theme
- TypeScript types
- Config options
- Custom adapters API
Theming System
NLUX v2.x comes with a new default theme called Nova.
When you set up NLUX as per documentation and guides, you are expected to load the Nova theme's CSS into your
web page, as following:
import '@nlux/themes/nova.css';
We recommend using the default Nova theme, as it's a more user-friendly and accessible theme, that supports both
dark and light modes. But if you would like to keep the old legacy theme, you have that option.
Keeping the v1.x theme
The NLUX v1.x's default theme is called Luna and it's still included as part of the v2.x release, but not as a
default theme. If you're interested in keeping the Luna theme while using NLUX v2.x, you can that by providing
themeId prop to the AiChat component's displayOptions, as following:
- React JS ⚛️
- JavaScript 🟨
import {AiChat} from '@nlux/react';
<AiChat displayOptions={{ themeId: 'luna' }} />
import {createAiChat} from '@nlux/core';
const aiChat = createAiChat().withDisplayOptions({themeId: 'luna'});
In addition to that, you will also need to import the Luna theme's CSS into your web page.
If your project bundler supports CSS imports, you can do that as following:
import '@nlux/themes/luna.css';
Otherwise, you can download the Luna theme's CSS file
from @nlux/themes NPM and include it in your HTML file.
Type Changes
NLUX v2.x has updated the name and value of certain types. Here's a list of the updated types:
Participant Role
This value is used in the ChatItem type to define the role of the participant in the conversation.
Old value:
type ParticipantRole = 'user' | 'system' | 'ai';
New value:
type ParticipantRole = 'user' | 'system' | 'assistant';
The ai role has been renamed to assistant to better reflect the role of the AI in the conversation,
and to match the naming convention of OpenAI APIs that are considered as an industry standard.
AiChat Config Options
AiChat UI component's config options have been updated in NLUX v2.x.
If you're using AiChat component in your project, you will need to update the config options as per the new API.
Here's a list of the updated config options:
| Old Config Option | New Config Option | Change Description |
|---|---|---|
themeId | displayOptions.themeId | themeId prop has been moved to displayOptions object. |
personaOptions.bot | personaOptions.assistant | personaOptions.bot has been renamed to personaOptions.assistant. |
personaOptions.bot.picture | personaOptions.assistant.avatar | personaOptions.bot.picture has been renamed to personaOptions.assistant.avatar. |
personaOptions.user.picture | personaOptions.user.avatar | personaOptions.user.picture has been renamed to personaOptions.user.avatar. |
conversationOptions.scrollWhenGenerating | conversationOptions.autoScroll | conversationOptions.scrollWhenGenerating has been renamed to conversationOptions.autoScroll. |
conversationOptions.streamingAnimationSpeed | messageOptions.streamingAnimationSpeed | conversationOptions.streamingAnimationSpeed has been moved to messageOptions. |
conversationOptions.historyPayloadSize | - | The type of conversationOptions.historyPayloadSize has been changed from number | 'none' | 'max' to number | 'max'. |
layoutOptions.width | displayOptions.width | layoutOptions.width has been moved to displayOptions. |
layoutOptions.height | displayOptions.height | layoutOptions.height has been moved to displayOptions. |
layoutOptions.maxWidth | - | layoutOptions.maxWidth has been removed. The default width is now 100%. |
layoutOptions.maxHeight | - | layoutOptions.maxHeight has been removed. The default height is now 100%. |
promptBoxOptions.autoFocus | componentOptions.autoFocus | promptOptions.autoFocus has been moved to componentOptions. |
promptBoxOptions.placeholder | componentOptions.placeholder | promptOptions.placeholder has been moved to componentOptions. |
syntaxHighlightingOptions | messageOptions.syntaxHighlighting | syntaxHighlightingOptions has been moved to messageOptions. |
Please note that this is not an exhaustive list of changes, and you should refer to the
NLUX v2.x AI Chat component documentation for a complete list of changes.
Custom Adapters
If you have implemented custom adapters in your project, you will need to update them to work with NLUX v2.x.
The new version of NLUX has updated the adapter API to provide better flexibility and more control over the
conversation flow.
The most important change in the adapter API is the introduction of generic types for the ChatAdapter interface.
Please refer to the NLUX v2.x custom adapters documentation for more information on how to
update your custom adapters.