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.

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:

npx vite

or

npm run dev

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!