npm:@we-make-websites/frame-beacon

README

Beacon

Beacon is a package for Frame that enables an improved level of visual logging, it:

🌎 -- Displays store context
🚎 -- Catch bus events
🤖 -- Log relevant data

It will output relevant data into the browsers console in a consistent, formatted and clean manner.

Beacon is currently set up to exclude any logs from Production themes.

Beacon doesn't (and shouldn't) rely on any modifications to the existing Frame boilerplate - this means that Beacon is backwards compatible with existing Frame 3 projects.

🔧 Installing

Beacon is available as an NPM package:

npm install --save-dev @we-make-websites/frame-beacon

💪 Enabling

Open up your themes main JS file, which is usually src/scripts/layout/theme.js, and import Beacon and define the Beacon global object:

import Beacon from '@we-make-websites/frame-beacon';
window.Frame.Beacon = Beacon();

💻 Using

Beacon has 3 main pieces of functionality:

🛒 Displaying context

Frame.Beacon.context();

For usage within your theme.js, this will add a group at the top of the console with useful groups of information:

Theme name and theme ID
Current Page Type & template name
Strings from theme-strings.liquid
Global Frame and Shopify objects.

🛰 Event Tracking:

Frame.Beacon.track();

For usage within an individual component, this should be added to the init() of a component and will automatically catch any Frame.EventBus events that are emitted, along with the relevant data that was received.

It allows an optional (but encouraged) parameter of the current component:

Frame.Beacon.track('productForm');

Any event within the component that uses the EventBus will be caught and displayed in the browsers console, along with the components namespace, the EventBus event, and any relevant data.

📊 Data Logging

Frame.Beacon.log(dataObject);

For usage within an individual component, this is intended to output useful segments of data after certain functions are run.

This allows for two optional parameters:

Log Context: Title of where the log was sent from (e.g. template, component nameSpace)
Brief description: What is the log achieving?

Frame.Beacon.log(dataObject, 'Log Context', 'Custom Message');

A simple example would be outputting a components nodeSelectors during a components init():

function init() {
    // code...
    Frame.Beacon.log(nodeSelectors, 'productForm', 'PDP Selectors enabled');
 }

This can be expanded across functions:

let a = 'hello';

function myFunction() {
  Frame.Beacon.log(a, 'myFunction', 'Checking variable');
  if (condition) {
    a = 'hey'
  }
  myNextFunction();
}

function myNextFunction() {
  Frame.Beacon.log(a, 'myNextFunction', 'Confirming variable');
}

🦠 Known bugs/issues

Currently requires manual installation, ideally npm package
Needs to check if browser supports coloured console outputs and provide fallback
Options for foolproof method of disabling this on production sites.
Beacon.track displays duplicate EventBus events when component is initialised twice (e.g. Quickview PDP on PDP)

🛣 Roadmap & future ideas

Pass arguments to functions (e.g. exclude EventBus event from tracking)
Seamless Liquid integration
MultiStore & Currency overview

Usage no npm install needed!