Skip to content

Commit eaa2b4f

Browse files
author
Philip Mutua
committed
docs: add integration documentation for react,angular & vue
1 parent fff3132 commit eaa2b4f

File tree

3 files changed

+481
-0
lines changed

3 files changed

+481
-0
lines changed

‎docs/angular-integration.md

Lines changed: 175 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,175 @@
1+
# Integration Steps for Native Web Chatbot UI in Angular
2+
3+
## 1. Install the Library
4+
5+
First, you need to install the native-web-chatbot-ui or any external JavaScript library in your Angular project.
6+
7+
If the library is available via npm:
8+
9+
```bash
10+
npm install native-web-chatbot-ui --save
11+
```
12+
13+
If not available through npm, manually add it by downloading the .js file and placing it into your src/assets folder.
14+
15+
## 2. Add External JS Library to Angular's angular.json
16+
17+
Add the library to the angular.json file so Angular includes it in the build process:
18+
19+
```json
20+
"scripts": [
21+
"node_modules/native-web-chatbot-ui/dist/main.js
22+
"
23+
]
24+
```
25+
26+
## 3. Declare the Module and Its Types
27+
28+
Create a declaration file to make TypeScript aware of the library:
29+
30+
```typescript
31+
// src/app/native-web-chatbot-ui.d.ts
32+
declare module 'native-web-chatbot-ui/dist/main.js' {
33+
const content: any;
34+
export default content;
35+
}
36+
```
37+
38+
## 4. Import and Use the Library in Angular Component
39+
40+
```typescript
41+
import { Component, OnInit, OnDestroy, Inject, PLATFORM_ID } from '@angular/core';
42+
import { isPlatformBrowser } from '@angular/common';
43+
44+
declare global {
45+
interface HTMLElement {
46+
config: any;
47+
getBotResponse: (message: string) => Promise<string>;
48+
}
49+
}
50+
51+
@Component({
52+
selector: 'app-chatbot',
53+
standalone: true,
54+
imports: [],
55+
templateUrl: './chatbot.component.html',
56+
styleUrls: ['./chatbot.component.css']
57+
})
58+
export class ChatbotComponent implements OnInit, OnDestroy {
59+
chatbotElement: HTMLElement | null = null;
60+
61+
constructor(@Inject(PLATFORM_ID) private platformId: any) {}
62+
63+
ngOnInit(): void {
64+
if (isPlatformBrowser(this.platformId)) {
65+
// Only run client-side code
66+
this.loadChatbot();
67+
}
68+
}
69+
70+
ngOnDestroy(): void {
71+
// Clean up any dynamic elements if needed
72+
if (this.chatbotElement) {
73+
document.body.removeChild(this.chatbotElement);
74+
}
75+
}
76+
77+
loadChatbot() {
78+
// Dynamically load the chatbot library in the browser
79+
import('native-web-chatbot-ui/dist/main.js').then(() => {
80+
// Dynamically create the chatbot element
81+
this.chatbotElement = document.createElement('chat-bot');
82+
document.body.appendChild(this.chatbotElement);
83+
84+
// Configure chatbot settings
85+
if (this.chatbotElement) {
86+
this.chatbotElement.config = {
87+
apiKey: 'sk-your-openai-key-here',
88+
theme: 'dark',
89+
css: '@org/.css',
90+
initialWidth: 400,
91+
position: 'bottom-right',
92+
bubbleStyle: {
93+
userBackground: '#4CAF50',
94+
botBackground: '#F5F5F5',
95+
borderRadius: '20px'
96+
},
97+
streamingData: true,
98+
delayTime: 50
99+
};
100+
101+
// Define the bot's response behavior
102+
this.chatbotElement.getBotResponse = async (message: string) => {
103+
const longStarWarsResponse = `A long time ago in a galaxy far, far away... The Force will be with you. Always.`;
104+
return new Promise(resolve => {
105+
setTimeout(() => {
106+
resolve(longStarWarsResponse);
107+
}, 1000);
108+
});
109+
};
110+
}
111+
}).catch(error => {
112+
console.error('Error loading the chatbot library:', error);
113+
});
114+
}
115+
}
116+
```
117+
118+
## 5. Add the Chatbot Component to Your App
119+
120+
Add the component to your Angular app's template:
121+
122+
```html
123+
<app-chatbot></app-chatbot>
124+
```
125+
126+
## 6. Style and Customize the Chatbot
127+
128+
Customize the chatbot's appearance through its configuration:
129+
130+
```typescript
131+
this.chatbotElement.config = {
132+
// other config properties...
133+
bubbleStyle: {
134+
userBackground: '#4CAF50',
135+
botBackground: '#F5F5F5',
136+
borderRadius: '20px'
137+
},
138+
// more config properties...
139+
};
140+
```
141+
142+
## 7. Test and Debug
143+
144+
- Check for errors in the console when loading the script and creating the chatbot
145+
- Verify performance to ensure the script doesn't block the main thread
146+
- Test mobile responsiveness across various screen sizes
147+
148+
## 8. Clean Up After Component Destruction
149+
150+
Implement proper cleanup in ngOnDestroy:
151+
152+
```typescript
153+
ngOnDestroy(): void {
154+
if (this.chatbotElement) {
155+
document.body.removeChild(this.chatbotElement);
156+
}
157+
}
158+
```
159+
160+
## 9. Handle API Keys Securely
161+
162+
- Don't hardcode API keys in frontend code
163+
- Use environment variables or backend services to manage sensitive data
164+
165+
<!-- ## Summary of Integration Steps
166+
167+
1. **Install the Library**: Via npm or manual download
168+
2. **Configure angular.json**: Include external scripts
169+
3. **Declare Types**: Create type definitions for TypeScript
170+
4. **Create Component**: Implement dynamic loading and initialization
171+
5. **Add to Template**: Include the component in your app
172+
6. **Style**: Customize appearance through configuration
173+
7. **Cleanup**: Handle proper removal when component is destroyed
174+
8. **Test**: Ensure smooth integration and responsive behavior
175+
9. **Security**: Protect sensitive information like API keys -->

‎docs/react-integration.md

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
# Important Notes for React Integration
2+
3+
## 1. `"use client"` Directive
4+
5+
In frameworks like **Next.js** that support **server-side rendering (SSR)** and **static site generation (SSG)**, React hooks like `useEffect` will only work on the client side. By adding the `"use client"` directive at the top of the file, we ensure the component runs only on the client side.
6+
7+
### Example
8+
9+
```tsx
10+
'use client';
11+
```
12+
13+
This is crucial for components that rely on DOM manipulation or when using browser-specific APIs like window, document, etc.
14+
15+
## 2. Custom Web Component (chat-bot)
16+
17+
When using custom web components (e.g., `<chat-bot>`), they don't natively support React-specific props or states. Therefore, we handle the custom properties (config and getBotResponse) directly via JavaScript.
18+
19+
### Example of Creating and Configuring the Chatbot
20+
21+
```tsx
22+
const chatbot = document.createElement('chat-bot') as HTMLElement;
23+
document.body.appendChild(chatbot);
24+
25+
chatbot.config = {
26+
apiKey: 'sk-your-openai-key-here',
27+
theme: 'dark',
28+
css: '@org/.css',
29+
initialWidth: 400,
30+
position: 'bottom-right',
31+
bubbleStyle: {
32+
userBackground: '#4CAF50',
33+
botBackground: '#F5F5F5',
34+
borderRadius: '20px'
35+
},
36+
streamingData: true,
37+
delayTime: 50
38+
};
39+
40+
chatbot.getBotResponse = async (message: string) => {
41+
const longStarWarsResponse = `
42+
A long time ago in a galaxy far, far away...
43+
... The Force will be with you. Always.`;
44+
45+
return new Promise<string>((resolve) => {
46+
setTimeout(() => {
47+
resolve(longStarWarsResponse);
48+
}, 1000);
49+
});
50+
};
51+
```
52+
53+
## 3. TypeScript Type Assertion
54+
55+
Since chat-bot is a custom web component, TypeScript doesn't automatically know about its properties. We use type assertion to tell TypeScript that the element is of type HTMLElement.
56+
57+
### Example
58+
59+
```tsx
60+
const chatbot = document.createElement('chat-bot') as HTMLElement;
61+
```
62+
63+
This is necessary when working with custom elements that extend HTML elements.
64+
65+
## 4. useEffect Hook
66+
67+
The useEffect hook is used to perform side effects, such as adding/removing elements from the DOM. In this case, we append the chatbot to the body when the component mounts and remove it when it unmounts.
68+
69+
### Example
70+
71+
```tsx
72+
useEffect(() => {
73+
// Code for adding the chatbot element
74+
return () => {
75+
// Cleanup - remove chatbot when the component is unmounted
76+
document.body.removeChild(chatbot);
77+
};
78+
}, []);
79+
```
80+
81+
## 5. Global Declaration for Custom Properties
82+
83+
We use declare global to inform TypeScript about the custom properties (config and getBotResponse) on the HTMLElement interface. Without this, TypeScript wouldn't recognize these properties.
84+
85+
### Example
86+
87+
```tsx
88+
declare global {
89+
interface HTMLElement {
90+
config: any;
91+
getBotResponse: (message: string) => Promise<string>;
92+
}
93+
}
94+
```
95+
96+
## 6. SSR Considerations
97+
98+
If you're using SSR (e.g., with Next.js), make sure the component with useEffect runs only on the client side. The "use client" directive ensures this behavior.
99+
100+
### Example
101+
102+
```tsx
103+
'use client'; // Ensures the component is only run on the client side
104+
```
105+
106+
## 7. Custom Element Compatibility
107+
108+
Web components (like `<chat-bot>`) are separate from React components. If you need to use React-specific features (like state or events) with a custom element, you will need to manage interactions manually since React doesn't support these natively.
109+
110+
## 8. Browser Support for Web Components
111+
112+
Ensure that the browser supports web components. Most modern browsers support them, but older browsers might need polyfills.
113+
114+
## 9. CSS Loading
115+
116+
Make sure that the CSS file (@org/.css) is available and properly linked, as the chatbot config includes a custom CSS path.
117+
118+
## Conclusion
119+
120+
- Ensure you use "use client" for client-side rendering when necessary.
121+
- Custom web components need manual management for properties and events in React.
122+
- TypeScript may need type assertions or global declarations for custom elements.

0 commit comments

Comments
 (0)