Vop-embed NPM | npm.io

Shoppable experiences from your social media posts

What is Vop Embed?

This is the customer embed widget codebase of Vop. Every single type of widget that is embedded onto a customers website is in this repository.

Inspiration

Most of the embed inspiration comes from a project by Jenya Y. called help-widget. The biggest difference was ditching preact and refactoring to use react. While preact is mostly cross compatible with react this change was to minimise any friction for newcomers.

Using this structure is primarily for the following advantages:

Injection through a target element
Small footprint and solid snippet on hosting website (see usage)
Multi-instance on the same page
Isolation of code execution and CSS
Customisation via configuration injection and API to Widget

Vision

It is obvious with the growth of e-commerce, many stores are trying to drive traffic from their social media content and vice versa... (incomplete)

Roadmap & Issues

We use Jira for the issue tracking and product road map.

Status

Vop Embed has been in full-time development since June 2020.

Codebase

Technologies

Almost all the code in this repository will be JavaScript. The embed widgets mostly communicate with our Vop API which is written in Go.

Notable technologies we use:

webpack
react
typescript
jest

Folder structure

vop-embed/
├── dev      # Demo of the different embed component types
├── dist
├── docs
├── public   # Public files used on the frontend
├── src      # Embed react components and api services
└── test     # Tests (using Jest)

Code Style

We run Prettier on-commit, which means it will be automatically formatted according to the common style when you run git commit. We also have ESLint setup, although we've disabled all stylistic rules since Prettier takes care of those.

Rules

All .js files must be typed using TypeScript so use .ts and .tsx.
Please don't commit any console.logs in any file. We use the debug module across the codebase to log debugging information in development only. The only exceptions are errors, which you can log, but you have to use console.error to be explicit about it.

First time setup

The first step to running Vop Embed locally is downloading the code by cloning the repository:

git clone git@github.com:dreambiglabs/vop-embed.git

If you get Permission denied error using ssh refer here or use https link as a fallback.

git clone https://github.com/dreambiglabs/vop-embed.git

Usage

In order to embed the widget add the following snippet at any location on the hosting page:

<div id="vop-root"></div>
<script>
  (function (w, d, s, o, f, js, fjs) {
    w[o] = w[o] || function () { (w[o].q = w[o].q || []).push(arguments) };
    js = d.createElement(s), fjs = d.getElementsByTagName(s)[0];
    js.id = o; js.src = f; js.async = 1; fjs.parentNode.insertBefore(js, fjs);
  }(window, document, 'script', 'vop', './widget.js'));
  vop('init', { element: document.getElementById('vop-root'), appId: 123, component: 'carousel' });
</script>

During initialization you can pass additional configurations to widget like so:

-vop('init');
+vop('init', { element: document.getElementById('vop-root'), appId: 123, component: 'carousel' });

You can find a full list of configurations in AppConfigurations interface.

Develop

The widget dev setup is similar to regular client application. To get started:

npm i
npm start

This will open browser with "demo" page which hosts the widget.

Notes

You'll need to restart your develop server after every change to your tailwind.config.js to pick up the changes.