{"id":21404008,"url":"https://github.com/react-chatbotify-plugins/react-chatbotify-plugin-template","last_synced_at":"2025-10-15T10:21:20.560Z","repository":{"id":261652792,"uuid":"879363775","full_name":"React-ChatBotify-Plugins/react-chatbotify-plugin-template","owner":"React-ChatBotify-Plugins","description":"A template repository to help developers get started with creating React ChatBotify Plugins!","archived":false,"fork":false,"pushed_at":"2024-11-13T18:00:12.000Z","size":258,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-23T03:29:54.917Z","etag":null,"topics":["chatbot","chatbotify","javascript","npm","open-source","open-source-project","react","react-chatbot","reactjs","typescript"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/React-ChatBotify-Plugins.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-10-27T17:54:53.000Z","updated_at":"2024-11-13T18:00:16.000Z","dependencies_parsed_at":"2025-01-23T03:28:54.865Z","dependency_job_id":"5989eea4-73d4-40bf-95e3-62c90c13a35c","html_url":"https://github.com/React-ChatBotify-Plugins/react-chatbotify-plugin-template","commit_stats":null,"previous_names":["react-chatbotify-plugins/react-chatbotify-plugin-template"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/React-ChatBotify-Plugins%2Freact-chatbotify-plugin-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/React-ChatBotify-Plugins%2Freact-chatbotify-plugin-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/React-ChatBotify-Plugins%2Freact-chatbotify-plugin-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/React-ChatBotify-Plugins%2Freact-chatbotify-plugin-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/React-ChatBotify-Plugins","download_url":"https://codeload.github.com/React-ChatBotify-Plugins/react-chatbotify-plugin-template/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243901523,"owners_count":20366252,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chatbot","chatbotify","javascript","npm","open-source","open-source-project","react","react-chatbot","reactjs","typescript"],"created_at":"2024-11-22T16:12:00.862Z","updated_at":"2025-10-15T10:21:15.512Z","avatar_url":"https://github.com/React-ChatBotify-Plugins.png","language":"JavaScript","readme":"\u003cp align=\"center\"\u003e\r\n  \u003cimg width=\"200px\" src=\"https://raw.githubusercontent.com/react-chatbotify-plugins/react-chatbotify-plugin-template/main/src/assets/logo.png\" /\u003e\r\n  \u003ch1 align=\"center\"\u003eReact ChatBotify Plugin Template\u003c/h1\u003e\r\n\u003c/p\u003e\r\n\r\n\u003cp align=\"center\"\u003e\r\n  \u003ca href=\"https://github.com/react-chatbotify-plugins/react-chatbotify-plugin-template/actions/workflows/ci-cd-pipeline.yml\"\u003e \u003cimg src=\"https://github.com/react-chatbotify-plugins/react-chatbotify-plugin-template/actions/workflows/ci-cd-pipeline.yml/badge.svg\" /\u003e \u003c/a\u003e\r\n  \u003ca href=\"https://www.npmjs.com/package/react-chatbotify\"\u003e \u003cimg src=\"https://img.shields.io/badge/react-16--19-orange?logo=react\u0026label=react\" /\u003e \u003c/a\u003e\r\n\u003c/p\u003e\r\n\r\n## Table of Contents\r\n\r\n* [Introduction](#introduction)\r\n* [Navigating this Template](#navigating-this-template)\r\n* [Quickstart](#quickstart)\r\n* [Plugins Feature Overview](#plugins-feature-overview)\r\n* [Plugin Design](#plugin-design)\r\n* [Project Structure](#project-structure)\r\n* [Creating a Plugin](#creating-a-plugin)\r\n* [Small Tips](#small-tips)\r\n* [Examples](#examples)\r\n* [Want to Help?](#want-to-help?)\r\n\r\n## Introduction\r\n\r\n**React ChatBotify Plugin Template** is a skeleton repository created to help developers build **custom plugins**. It includes a **project structure** and **setup** to make plugin development straightforward. Familiarity with the [**core library**](https://github.com/tjtanjin/react-chatbotify) is recommended, in particular for chatbot [**Events**](https://react-chatbotify.com/docs/api/events) and [**Hooks**](https://react-chatbotify.com/docs/api/hooks). As the plugins feature is only introduced in **React ChatBotify v2.0.0**, plugins should be developed against the [**v2 API**](https://react-chatbotify.com).\r\n\r\nThis guide provides all the information needed to create plugins effectively. **Reading through the guide completely is crucial**, especially for first-time developers. Skipping content may lead to confusion and missed details important for successful plugin development.\r\n\r\nFor support, join the plugin community on [**Discord**](https://discord.gg/J6pA4v3AMW) to connect with other developers and get help.\r\n\r\n## Navigating this Template\r\n\r\nBefore diving into the contents, here are some syntaxes used throughout to help with navigation:\r\n\r\n| Syntax              | Description                                    |\r\n| ------------------- | ---------------------------------------------- |\r\n| `Markdown`          | Commands (e.g. `npm install`)                  |\r\n| *Italics*           | Files/Folders (e.g. *services*, *components*)  |\r\n| **Bold**            | Keywords (e.g. **important consideration**)    |\r\n\r\n\u003cdiv  style=\"page-break-after: always;\"\u003e\u003c/div\u003e\r\n\r\n## Quickstart\r\n\r\nThis section is for returning plugin developers who are familiar with the template. If this is your first time, **please read through the other sections first**.\r\n\r\nTo get started quickly:\r\n1. Clone this template repository:\r\n   ```bash\r\n   git clone https://github.com/react-chatbotify-plugins/react-chatbotify-plugin-template.git\r\n   ```\r\n\r\n2. Run the setup script:\r\n   ```bash\r\n   node setup.js\r\n   ```\r\n\r\n3. Modify files in the src folder and update README.md and package.json for your plugin-specific logic.\r\n\r\n4. Test your plugin with:\r\n   ```bash\r\n   npm run start\r\n   ```\r\n\r\n5. When your plugin is ready, package it with:\r\n   ```bash\r\n   npm pack\r\n   ```\r\n\r\n6. Share the generated **.tgz** file and install it in projects using:\r\n   ```\r\n   npm install your-plugin-0.1.0.tgz\r\n   ```\r\n\r\nOptionally, you're also encouraged to release and share your plugin by publishing it on NPM.\r\n\r\n## Plugins Feature Overview\r\n\r\nThe plugins feature, introduced in React ChatBotify v2.0.0, was designed to keep the library **lightweight while offering flexibility** for feature extensions. Rather than adding all features into the core, a plugin-based approach allows developers to only install what they need, simplifying both usage and maintenance.\r\n\r\n### Why Plugins?\r\n\r\n- Extensibility: Provides a convenient means for anyone to extend the features of the chatbot.\r\n- Flexibility: Offers a variety of approaches to solve a problem.\r\n- Simplicity: Avoids the \"bloat\" of unused features, keeping downloads and documentation concise.\r\n- Maintainability: Isolates complexity and minimizes interdependencies, making debugging easier.\r\n\r\nThis plugin approach aligns with the goal of providing an extensible, user-friendly library while allowing for customizations.\r\n\r\n## Plugin Design\r\n\r\nPlugins can be initialized with configurations and interact with the chatbot via [**Events**](https://react-chatbotify.com/docs/api/events) \u0026 [**Hooks**](https://react-chatbotify.com/docs/api/hooks), which are introduced in React ChatBotify v2.0.0. Here’s a high-level overview:\r\n\r\n```mermaid\r\nflowchart TD\r\n  A(\"Example Plugin\")\r\n  B(\"Listens to Chatbot Events\")\r\n  C(\"Uses Hooks for Actions\")\r\n  D(\"Event: Message Sent\")\r\n  E(\"Hook: Toggle Audio\")\r\n  F(\"Plugin Configurations\")\r\n\r\n  F --\u003e A\r\n  A --\u003e B\r\n  A --\u003e C\r\n  B --\u003e D\r\n  C --\u003e E\r\n\r\n  %% Styling\r\n  style A fill:#007bff,stroke:#007bff,color:#ffffff\r\n  style F fill:#007bff,stroke:#007bff,color:#ffffff\r\n```\r\n\r\nIn the diagram above, we see an example plugin taking in configurations for initialization and relying on events and hooks for actions. For developing a plugin, you only need to **focus on implementing the plugin components (blue boxes)** as events and hooks are features **already provided by the core chatbot library**.\r\n\r\n### Plugin Components\r\n\r\n- **Plugin Configurations**: The configurations for initializing a plugin.\r\n- **Hook Factory**: The outer function, where the plugin hook is created (possibly with configurations).\r\n- **Plugin Hook**: The inner function, containing the plugin’s main logic.\r\n- **Plugin MetaData**: The metadata of the plugin, consumed by the core library.\r\n\r\nA plugin uses **Configurations** for initialization, [**Events**](https://react-chatbotify.com/docs/api/events) for awareness of chatbot actions and [**Hooks**](https://react-chatbotify.com/docs/api/hooks) to interact with the chatbot. Here’s a sample flow:\r\n\r\n```mermaid\r\nflowchart TD\r\n  A(\"Plugin Configurations\") --\u003e B(\"Hook Factory\")\r\n\r\n  subgraph ExamplePlugin [\"Example Plugin\"]\r\n    direction TB\r\n    B --\u003e C(\"Plugin Hook\") --\u003e D(\"Plugin MetaData\")\r\n  end\r\n\r\n  %% Styling\r\n  style A fill:#007bff,stroke:#007bff,color:#ffffff\r\n  style B fill:#007bff,stroke:#007bff,color:#ffffff\r\n  style C fill:#007bff,stroke:#007bff,color:#ffffff\r\n  style D fill:#007bff,stroke:#007bff,color:#ffffff\r\n  style ExamplePlugin fill:#f0f8ff,stroke:#007bff,color:#000000\r\n```\r\n\r\nIn practical terms:\r\n- The **Plugin Configurations** are provided by users to initialize the plugin.\r\n- The **Hook Factory** accepts configurations to generate the PluginHook.\r\n- The **Plugin Hook** is passed to the core chatbot library to be initialized and returns PluginMetadata.\r\n- The **Plugin MetaData** is consumed by the core chatbot library for setup \u0026 auto configurations.\r\n\r\nBelow, we take a deeper look into these 4 components that make up a plugin.\r\n\r\n#### Plugin Configurations\r\n\r\nPlugin Configurations are configurable options that users may pass into a plugin when using it. Available options are **entirely up to plugin developers** and are likely to vary across different plugins which serve different use cases. As developers who are driven to provide the best user experience, it is advisable to spend time and effort into curating a plugin configuration that is **easy to use yet highly flexible for users**. For example, having a simple `autoConfig` field to let users decide if they would like the plugin to handle all auto configurations for them. This is shown in the next section with a code snippet for [**consumers of the plugin**](#consumers-of-the-plugin).\r\n\r\n#### Hook Factory\r\n\r\nThe Hook Factory simply generates the plugin hook that will be initialized by the core chatbot library. The logic for creating hooks may be influenced by plugin configurations as well.\r\n\r\n#### Plugin Hook\r\n\r\nThe Plugin Hook contains the core logic of the plugin itself (e.g. listening for events, carrying out actions using hooks). It also returns the Plugin MetaData which is consumed by the core chatbot library during plugin hook initialization.\r\n\r\n#### Plugin MetaData\r\n\r\nThe Plugin MetaData contains data of the plugin which are consumed by the core chatbot library during its initialization. It is essentially an object containing 3 fields:\r\n- name (required): The name of the plugin, should match the npm-package name if published (or at least try to keep it unique among plugins if used privately).\r\n- settings (optional): The [**settings**](https://react-chatbotify.com/docs/api/settings) enforced by the plugin.\r\n- styles (optional): The [**styles**](https://react-chatbotify.com/docs/api/styles) enforced by the plugin.\r\n\r\nNote that settings and styles specified here **have the highest priority and will override even user-specified options**. Plugin developers are advised to enforce these sparingly to avoid poor user experiences. In general, you should only use this for enabling events (e.g. `settings.event.rcbPreInjectMessage: true`)`. A better recommendation is to provide an option within your [**Plugin Configurations**](#plugin-configurations) for users to opt-out of the auto config process if they wish.\r\n\r\n### Code Implementations\r\n\r\nBelow, we take a look at 2 short code implementations. The first snippet shows how consumers/users of a plugin should use a plugin. The second snippet shows how developers can implement a plugin.\r\n\r\n#### Consumers of the Plugin:\r\n```js\r\n/**\r\n * Example component for initializing chatbot with a plugin.\r\n */\r\nconst MyComponent = () =\u003e {\r\n  // user defines plugin configurations (plugin-specific)\r\n  const pluginConfig = {autoConfig: true}\r\n\r\n  // user passes the plugin into the plugins prop of chatbot\r\n  const plugins = [RcbPlugin(pluginConfig)]\r\n  return \u003cChatBot plugins={plugins}/\u003e\r\n}\r\n```\r\n\r\nDevelopers of the Plugin:\r\n```js\r\n/**\r\n * Hook factory for creating plugin hook.\r\n *\r\n * @params pluginConfig configurations for the plugin\r\n */\r\nconst RcbPlugin = (pluginConfig) =\u003e {\r\n  const useRcbPlugin = () =\u003e {\r\n    // plugin logic for doing something\r\n    console.log(\"I'm doing something!\")\r\n\r\n    // hook returns plugin metadata which minimally must have plugin name\r\n    return {\r\n      name: \"rcb-plugin\"\r\n    }\r\n  }\r\n\r\n  // factory returns the plugin hook\r\n  return useRcbPlugin;\r\n}\r\n```\r\n\r\nFor more detailed explanations, review this section thoroughly or visit the example plugins within the [**Examples**](#examples) section. You may also feel free to join the [**Discord Community**](https://discord.gg/J6pA4v3AMW) if you need assistance.\r\n\r\n## Project Structure\r\n\r\nBelow is an overview of the main folders and files in this template:\r\n\r\n```mathematica\r\n├── .github/\r\n│   └── Contains default issue/pull request templates and CI/CD workflows.\r\n├── src/\r\n|   ├── constants/\r\n│   │   └── DefaultPluginConfig.ts - Constants for plugin configurations.\r\n│   ├── core/\r\n│   │   └── useRcbPlugin.ts - Contains core logic for the plugin (plugin hook).\r\n|   ├── factory/\r\n│   │   └── RcbPluginFactory.ts - Contains hook factory that prepares and creates the plugin hook.\r\n|   ├── types/\r\n│   │   └── PluginConfig.ts - Contains type definition for plugin configurations.\r\n│   ├── App.tsx - For initializing and testing the plugin.\r\n│   ├── development.tsx - Entry point during development.\r\n│   └── index.tsx - Export file for your plugin.\r\n├── setup.js - Setup script for quick initialization of the project\r\n└── package.json - Update name and author fields here.\r\n```\r\n\r\n### Key Files\r\n- .github Folder: Contains templates and workflows for CI/CD, automating builds and releases.\r\n- Constants Folder: Contains constants used in the plugin (e.g. _DefaultPluginConfig.ts_).\r\n- Core Folder: Houses the plugin hook, where the core logic for the plugin is developed.\r\n- Factory Folder: Houses the plugin factory, which prepares the plugin hook to be consumed by the core library.\r\n- Types Folder: Specifies the types used in the plugin (e.g. PluginConfig).\r\n- App.tsx File: Initializes the chatbot with your plugin; ideal for quick testing.\r\n- development.tsx File: Used for development setup and testing.\r\n- index.tsx File: Used to export plugin components.\r\n- setup.js: Setup script for quick initialization of the template repository.\r\n- package.json File: Update your plugin’s information here before publishing.\r\n\r\n## Creating a Plugin\r\n\r\nHaving gone through the contents up till this point, you possess at least the foundational knowledge required to create a plugin. With this template repository, the amount of work required to get started has also been made simpler. Once you're done with the rest of this guide, feel free to head over to the [**Quickstart**](#quickstart) section!\r\n\r\n**Note:** Understandably, hands-on tutorials for developing plugins may be very useful. These will soon be available in the form of **Medium articles and YouTube videos**.\r\n\r\n## Small Tips\r\n\r\nHere are some practical tips to improve your plugin development experience:\r\n\r\n- **User-Centered Design**: Design your plugin with users in mind. Think about ease of integration and use.\r\n- **Keep It Simple**: Focus on essential features. A streamlined plugin is easier to maintain and use.\r\n- **Documentation**: Provide clear, detailed instructions and examples to help users integrate the plugin successfully.\r\n- **Seek Feedback**: Engage with users, incorporating their feedback to improve functionality and resolve bugs.\r\n- **Refer to Examples**: Review official plugins as a reference to solve common development challenges.\r\n- **Add Tests**: Though not included by default, adding tests will help maintain your plugin’s reliability.\r\n\r\n## Examples\r\n\r\nHere are some examples of official plugins developed using this template:\r\n- [**Input Validator**](https://github.com/React-ChatBotify-Plugins/input-validator)\r\n- [**Markdown Parser**](https://github.com/React-ChatBotify-Plugins/markdown-parser)\r\n\r\nUse these as references to structure and build your own plugins, but note that a template is ultimately a **recommended way of doing things**. There may be situations where deviations are justifiable, so feel free to **exercise your own discretion**.\r\n\r\n## Want to Help?\r\n\r\nThere're a lot of pieces of work involved in elevating the quality of the chatbot (e.g. plugin development, theme creation) and contributions are always welcome. If you're keen to help, whether it's **creating plugins, developing themes or just improving the core library**, please feel free to open a pull request or even [**reach out**](https://discord.gg/J6pA4v3AMW) directly to me. You may also take a look at some of the other relevant repositories below. Your help will be very much appreciated.\r\n\r\n### Project Repository\r\n- https://github.com/react-chatbotify-plugins/react-chatbotify-plugin-template\r\n\r\n### Other Relevant Repositories\r\n- https://github.com/tjtanjin/react-chatbotify\r\n- https://github.com/tjtanjin/react-chatbotify-docs\r\n- https://github.com/tjtanjin/react-chatbotify-themes\r\n- https://github.com/tjtanjin/react-chatbotify-gallery-website\r\n- https://github.com/tjtanjin/react-chatbotify-gallery-api\r\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freact-chatbotify-plugins%2Freact-chatbotify-plugin-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Freact-chatbotify-plugins%2Freact-chatbotify-plugin-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freact-chatbotify-plugins%2Freact-chatbotify-plugin-template/lists"}