Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/labrodev/vuejs-embedded-widget
In certain scenarios, integrating a Single Page Application as an embedded widget into external websites becomes necessary. This project addresses the challenges associated with creating a versatile Vue.js 3 widget that seamlessly integrates into any website without imposing specific conditions.
https://github.com/labrodev/vuejs-embedded-widget
custom-elements embedded-js javascript shadowroot tailwindcss vite vuejs widgets
Last synced: about 1 month ago
JSON representation
In certain scenarios, integrating a Single Page Application as an embedded widget into external websites becomes necessary. This project addresses the challenges associated with creating a versatile Vue.js 3 widget that seamlessly integrates into any website without imposing specific conditions.
- Host: GitHub
- URL: https://github.com/labrodev/vuejs-embedded-widget
- Owner: labrodev
- License: mit
- Created: 2023-12-10T15:35:38.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2024-06-06T12:32:36.000Z (7 months ago)
- Last Synced: 2024-06-06T13:43:02.626Z (7 months ago)
- Topics: custom-elements, embedded-js, javascript, shadowroot, tailwindcss, vite, vuejs, widgets
- Language: Vue
- Homepage:
- Size: 40 KB
- Stars: 6
- Watchers: 1
- Forks: 2
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Vue.js 3 Embedded Widget
## Overview
In certain scenarios, integrating a Single Page Application as an embedded widget into external websites becomes necessary. This project addresses the challenges associated with creating a versatile Vue.js 3 widget that seamlessly integrates into any website without imposing specific conditions.
## Features
- **Versatility:** The widget is designed to be easily integrated into any website, maintaining visual aesthetics and workflow while remaining self-contained.
- **Isolation:** The embedded widget ensures it remains isolated to prevent interference with the styling of the parent site or disruption of external site functions.
## Technologies Used
- [Vue.js 3](https://vuejs.org/): Application framework
- [Vite](https://vitejs.dev/): Build and compilation tool
- [Tailwind CSS](https://tailwindcss.com/): Styling
- [Custom Elements API](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements): Define and use custom HTML element as the widget
- [Shadow Root](https://developer.mozilla.org/en-US/docs/Web/API/ShadowRoot?retiredLocale=uk): Part of Custom Elements API to encapsulate widget DOM element
## Example Use Case
This project serves as a comprehensive example of transforming a Vue.js 3 Single Page Application into a fully functional embedded widget. The practical example demonstrates creating a countdown widget for tracking the time remaining until a specific date or event, such as the start of the New Year or the end of discount campaigns.
It should be use like this in external site:
- include widget.js script in section of external site
- include tag in section of external site with required attributes that apply countdown logic.
Like this:
So at the end you need to configure your web server virtual host to reach the widget.js (like http://yourhost.com/widget.js)
## Installation
1. Clone (or fork) this project
```bash
git clone [email protected]:labrodev/vuejs-widget-embedded.git
```
2. Install packages
```bash
npm install
```
3. Build widget.js
```bash
npx vite build
```
In /dist folder you may find compiled widget.js and styles.css files.
4. Configure virtual host
Nginx example:
```text
server {
listen 80;
root /var/www/vuejs-embedded-widget/dist;
server_name yourhost;
location / {
try_files $uri $uri/ /index.html?$query_string;
}
}
```
Make sure that virtual host works and yourhost/widget.js is reachable.
## Development and preview mode
If you need to check the application in preview or development mode, it needs to be considered as a traditional Vue.js single-page application.
The problem is that we cannot use the same entry point (main.js) for both the embedded-widget mode and the standard Vue.js application.
That's why another entry point (dev.js) and another root component (Dev.vue) were added.
In vite.config.js, the defined entry point for "server" and "preview" is dev.js instead of main.js.
This way, you can enjoy the same behavior and functionality with both solutions. Use "preview" and "development" mode for testing and development, and build it as a compiled embedded widget script for external usage when needed.
To run it in development mode, simply use the following command:
```bash
npx vite
```
or
```bash
npm run dev
```
## Usage
Implement embedded widget in your desired external site to check results.
### Head Section:
```html
```
### Body Section:
```html
```
## Additional information
You may find detailed step-by-step guide how to turn Vue.js 3 application to embedded widget in [our blog on Substack](https://labrodev.substack.com/p/turn-vuejs-30-spa-to-embedded-widget?r=2zv4d4&utm_campaign=post&utm_medium=web) (don't forget to subscribe!)
Enjoy and thanks for your attention!