jeffersonsimaogoncalves / 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.

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: Application framework
• Vite: Build and compilation tool
• Tailwind CSS: Styling
• Custom Elements API: Define and use custom HTML element as the widget
• Shadow Root: 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

git clone [email protected]:labrodev/vuejs-widget-embedded.git

2. Install packages

npm install

3. Build widget.js

npx vite build

In /dist folder you may find compiled widget.js and styles.css files.

4. Configure virtual host

Nginx example:

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.

Usage

Implement embedded widget in your desired external site to check results.

Head Section:

<script src="http://yourhost.com/widget.js" defer></script>

Body Section:

<countdown-widget 
   date="2024-06-14" 
   title="Euro 2024 will start in"
   end="Euro 2024 is started!"
   color="#FF0000">
</countdown-widget>

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 (don't forget to subscribe!)

Enjoy and thanks for your attention!