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.
-
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.
- 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
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)
- Clone (or fork) this project
git clone git@github.com:labrodev/vuejs-widget-embedded.git
- Install packages
npm install
- Build widget.js
npx vite build
In /dist folder you may find compiled widget.js and styles.css files.
- 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.
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
Implement embedded widget in your desired external site to check results.
<script src="http://yourhost.com/widget.js" defer></script>
<countdown-widget
date="2024-06-14"
title="Euro 2024 will start in"
end="Euro 2024 is started!"
color="#FF0000">
</countdown-widget>
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!