@original-land/shopify-headless-chatbot
v0.2.5
Published
Shopify Headless Chatbot
Keywords
Readme
Shopify Headless Chatbot
A ready-to-use chat widget component for Shopify Hydrogen storefronts with built-in customer order tracking and context integration.
Installation
npm install @original-land/shopify-headless-chatbotUsage
1. Import the ChatWidget component
In your Hydrogen project, import the ChatWidget component inside the <App /> component in the root.tsx file:
import { ChatWidget } from '@original-land/shopify-headless-chatbot';
export default function App() {
return (
<html>
<head>{/* ... */}</head>
<body>
{/* ... other components ... */}
{/* Add the ChatWidget */}
<ChatWidget />
<Scripts />
</body>
</html>
);
}2. Configure API endpoints
In your Hydrogen project, create the files to re-export the API loaders:
Endpoint for widget data
// app/routes/api.original.widget-data.ts
export { dataLoader as loader } from "@original-land/shopify-headless-chatbot";This will automatically create the /api/original/widget-data endpoint that the ChatWidget component uses to retrieve customer order data.
Endpoint for the Customer Account API URL
// app/routes/api.original.widget-url.ts
export { urlLoader as loader } from "@original-land/shopify-headless-chatbot";This will create the /api/original/widget-url endpoint that returns the URL configured in the PUBLIC_ORIGINAL_URL_WIDGET_SCRIPT environment variable.
3. Configure Content Security Policy
To allow loading the widget script, you must add the script domain to the Content Security Policy in the entry.server.tsx file:
// app/entry.server.tsx
import {createContentSecurityPolicy} from '@shopify/hydrogen';
const {nonce, header, NonceProvider} = createContentSecurityPolicy({
scriptSrc: [
"'self'",
'https://cdn.shopify.com',
// Add the following domain
'https://ai-dashboard.original.land',
],
defaultSrc: [
"'self'",
'https://cdn.shopify.com',
// Add the following domain
'https://static.noku.io',
],
connectSrc: [
"'self'",
'https://cdn.shopify.com',
// Add the following domain
'https://ai-api.original.land',
],
mediaSrc: [
"'self'",
'https://cdn.shopify.com',
// Add the following domain and blob, data
'https://static.noku.io',
'blob:',
'data:',
],
});Note: The ChatWidget component uses the Hydrogen Script component that automatically adds the necessary nonce for Content Security Policy.
Features
- 🚀 TypeScript support with full type definitions
- 📦 ESM and CommonJS module formats
- 🛠 Built for modern JavaScript environments
- 🔌 Easy integration with Shopify headless commerce
- 💬 Ready-to-use chat widget component
- 🛒 Automatic order information display for logged-in customers
Development
Prerequisites
- Node.js (see
.nvmrcfor version) - pnpm
Setup
- Clone the repository
git clone https://github.com/noku-team/shopify-headless-chatbot.git
cd shopify-headless-chatbot- Install dependencies
pnpm installScripts
pnpm build- Build the library for productionpnpm lint- Type-check the code with TypeScriptpnpm release- Build and publish the package
Building
The project uses tsup to bundle the TypeScript code into both CommonJS and ESM formats with TypeScript declarations.
pnpm buildPublishing
This project uses Changesets for version management and automated publishing via GitHub Actions.
Release Process
- Create a changeset:
npx changesetCommit the changeset and merge to
mainThe CI pipeline will automatically:
- Version the package
- Update the CHANGELOG
- Publish to npm
- Create a GitHub release
Project Structure
shopify-headless-chatbot/
├── index.ts # Main entry point
├── package.json # Package configuration
├── tsconfig.json # TypeScript configuration
├── .changeset/ # Changeset configuration
└── .github/
└── workflows/ # CI/CD workflowsContributing
Contributions are welcome! Please feel free to submit a Pull Request.
License
MIT © Original Land SA
Author
Original Land SA
Built with ❤️ for the Shopify ecosystem