{"id":22614039,"url":"https://github.com/labrodev/vuejs-embedded-widget","last_synced_at":"2025-04-11T11:03:34.445Z","repository":{"id":211754120,"uuid":"729863042","full_name":"labrodev/vuejs-embedded-widget","owner":"labrodev","description":"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.","archived":false,"fork":false,"pushed_at":"2024-06-06T12:32:36.000Z","size":41,"stargazers_count":14,"open_issues_count":1,"forks_count":5,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-25T07:23:46.373Z","etag":null,"topics":["custom-elements","embedded-js","javascript","shadowroot","tailwindcss","vite","vuejs","widgets"],"latest_commit_sha":null,"homepage":"","language":"Vue","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/labrodev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2023-12-10T15:35:38.000Z","updated_at":"2025-03-06T16:12:48.000Z","dependencies_parsed_at":"2023-12-10T17:51:24.921Z","dependency_job_id":null,"html_url":"https://github.com/labrodev/vuejs-embedded-widget","commit_stats":null,"previous_names":["labrodev/vuejs-embedded-widget"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/labrodev%2Fvuejs-embedded-widget","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/labrodev%2Fvuejs-embedded-widget/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/labrodev%2Fvuejs-embedded-widget/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/labrodev%2Fvuejs-embedded-widget/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/labrodev","download_url":"https://codeload.github.com/labrodev/vuejs-embedded-widget/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248381758,"owners_count":21094525,"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":["custom-elements","embedded-js","javascript","shadowroot","tailwindcss","vite","vuejs","widgets"],"created_at":"2024-12-08T18:07:34.871Z","updated_at":"2025-04-11T11:03:34.408Z","avatar_url":"https://github.com/labrodev.png","language":"Vue","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Vue.js 3 Embedded Widget\n\n## Overview\n\nIn 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.\n\n## Features\n\n- **Versatility:** The widget is designed to be easily integrated into any website, maintaining visual aesthetics and workflow while remaining self-contained.\n  \n- **Isolation:** The embedded widget ensures it remains isolated to prevent interference with the styling of the parent site or disruption of external site functions.\n\n## Technologies Used\n\n- [Vue.js 3](https://vuejs.org/): Application framework\n- [Vite](https://vitejs.dev/): Build and compilation tool\n- [Tailwind CSS](https://tailwindcss.com/): Styling\n- [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\n- [Shadow Root](https://developer.mozilla.org/en-US/docs/Web/API/ShadowRoot?retiredLocale=uk): Part of Custom Elements API to encapsulate widget DOM element\n\n## Example Use Case\n\nThis 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.\n\nIt should be use like this in external site: \n\n- include widget.js script in \u003chead\u003e\u003c/head\u003e section of external site\n- include \u003ccountdown-widget\u003e\u003c/countdown-widget\u003e tag in \u003cbody\u003e\u003c/body\u003e section of external site with required attributes that apply countdown logic.\n\nLike this:\n\n\u003ccountdown-widget \n   date=\"2024-06-14\" \n   title=\"Euro 2024 will start in\"\n   end=\"Euro 2024 is started!\"\n   color=\"#FF0000\"\u003e\n\u003c/countdown-widget\u003e\n\nSo at the end you need to configure your web server virtual host to reach the widget.js (like http://yourhost.com/widget.js)\n\n## Installation\n\n1. Clone (or fork) this project \n\n```bash\ngit clone git@github.com:labrodev/vuejs-widget-embedded.git\n```\n\n2. Install packages \n\n```bash\nnpm install\n```\n\n3. Build widget.js \n\n```bash\nnpx vite build\n```\n\nIn /dist folder you may find compiled widget.js and styles.css files. \n\n4. Configure virtual host \n\nNginx example:\n\n```text\nserver {\n     listen 80;\n\n     root /var/www/vuejs-embedded-widget/dist;\n\n     server_name yourhost;\n\n     location / {\n        try_files $uri $uri/ /index.html?$query_string;\n     }\n}\n```\n\nMake sure that virtual host works and yourhost/widget.js is reachable. \n\n## Development and preview mode\n\nIf you need to check the application in preview or development mode, it needs to be considered as a traditional Vue.js single-page application.\n\nThe problem is that we cannot use the same entry point (main.js) for both the embedded-widget mode and the standard Vue.js application.\n\nThat's why another entry point (dev.js) and another root component (Dev.vue) were added.\n\nIn vite.config.js, the defined entry point for \"server\" and \"preview\" is dev.js instead of main.js.\n\nThis 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.\n\nTo run it in development mode, simply use the following command:\n\n```bash\nnpx vite\n```\nor \n\n```bash\nnpm run dev\n```\n\n## Usage\n\nImplement embedded widget in your desired external site to check results. \n\n### Head Section:\n\n```html\n\u003cscript src=\"http://yourhost.com/widget.js\" defer\u003e\u003c/script\u003e\n```\n\n### Body Section:\n\n```html\n\u003ccountdown-widget \n   date=\"2024-06-14\" \n   title=\"Euro 2024 will start in\"\n   end=\"Euro 2024 is started!\"\n   color=\"#FF0000\"\u003e\n\u003c/countdown-widget\u003e\n```\n\n## Additional information \n\nYou 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\u0026utm_campaign=post\u0026utm_medium=web) (don't forget to subscribe!)\n\nEnjoy and thanks for your attention! \n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flabrodev%2Fvuejs-embedded-widget","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flabrodev%2Fvuejs-embedded-widget","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flabrodev%2Fvuejs-embedded-widget/lists"}