Eloquent AI Chat Widget

A small, embeddable React chat widget built with Vite, React, and Tailwind CSS. It provides a customizable chat UI that can be mounted on any website as a UMD/ES module or run locally for development.

Features

• Minimal embeddable widget built as a library (src/widget.tsx).
• Customizable theme and colors via the UI (saved to localStorage).
• Login/demo form for quick testing.
• Built with Vite + React + Tailwind; ready to publish as a package.

Quick start

Requirements:

• Node.js 18+ (the project was tested with Node 22)
• npm or pnpm

Install dependencies:

npm install

Run the dev server:

npm run dev

Open http://localhost:5173 (Vite may choose another port if 5173 is busy).

Build for production:

npm run build

Preview production build:

npm run preview

Usage (development)

The app entry is src/index.tsx (demo) and the library entry is src/widget.tsx (used when building the UMD bundle).

In development the stylesheet is imported from src/index.tsx and src/widget.tsx:

import './styles/index.css'

Make sure Tailwind is processing your CSS. With the included setup we use the @tailwindcss/vite plugin which handles Tailwind v4 processing.

Mounting the widget in a page

When built as UMD / ES, the widget exposes a global EloquentAIChatWidget.mount(selector, props) function.

Example usage in a plain HTML page:

<div id="chat"></div>

<script src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
<script src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>
<script src="../dist/eloquent-widget.iife.js"></script>

<script>
  EloquentAIChatWidget.mount("#chat", {
    apiKey: "YOUR_OPENAI_BROWSER_KEY"
  });
</script>

Configuration & theming

• Theme and config are stored in localStorage under chatTheme and chatConfig.
• You can also programmatically pass apiKey and other config values when mounting the widget.

Tailwind notes & troubleshooting

If you see that Tailwind classes (for example bottom-6, right-6, etc.) are not applied:

1. Ensure your src/styles/index.css contains Tailwind directives (for v4 usage with the plugin we expect):

@tailwind base;
@tailwind components;
@tailwind utilities;

2. Make sure tailwind.config.js content globs include your templates and the demo HTML:

export default {
  content: ['./index.html', './src/**/*.{js,jsx,ts,tsx,html}', './public/**/*.{html,js}'],
}

3. If you use the @tailwindcss/vite plugin (recommended for Tailwind v4), prefer letting the plugin handle PostCSS integration. If you added Tailwind directly to postcss.config.cjs, check compatibility with the plugin and Tailwind version.

4. As a temporary workaround you can add a safelist to tailwind.config.js to force-generation of utilities used by the widget.

Publishing to npm

To publish the package to npm (public):

npm publish --access public

Notes:

• Make sure you are logged in (npm whoami) and have permission to publish the package name in package.json.
• If your account or organisation requires 2FA, you'll be prompted for an OTP during publish. For automated CI publishing create a granular automation token with the appropriate permissions and (if required) the "Bypass 2FA" option enabled.

Troubleshooting publish errors

• 403 Forbidden - You do not have permission to publish "<name>". — you are not the owner of the package name. Choose another name or request access.
• 403 Forbidden - Two-factor authentication ... — create a token with bypass or publish interactively and provide OTP.
• If you accidentally passed a positional argument when running npm publish, npm may have tried to publish the wrong folder (for example public). Use the correct flag spelling: --access public.

Contributing

Contributions welcome. Please open issues or PRs. Keep changes small and add tests where applicable.

License

MIT