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