@on-sight/dev-tools

@on-sight/dev-tools

Table of Contents

• What is this?
• Who is this for?
• Package Features
  • Dev engine
  • Smart, dynamic file routing
  • Userback widget initializer
  • Barba Transitions
  • Default Configurations
  • jQuery Plugins
  • Utility Functions
• Getting Started
• Examples and Usage
  • Getting Started: Importing
• Default Settings
• Advanced Usage
• Contribution Guidelines

What is this?

This package is a source of truth for many of the repeatedly used utilities, plugins, and features that o/S uses across it's projects. dev-tools intends to organize a large amount of the scaffolding included within each new theme.

Who is this for?

This package is built for Shopify theme developers that want to use a smart JS setup for building and compiling code. This package is very opinionated and will not do anything outside of the Shopify ecosystem. You will still need a JS folder system that uses webpack to make anything run. This package is not meant to be stand-alone.

Getting Started

Setting up the dev-tools is as easy as 1, 2, 3, 4, 5, 6, 7...

1. Install the @on-sight/dev-tools package in your project:

npm install @on-sight/dev-tools

2. Import engine into your main JS entry point:

import engine from '@on-sight/dev-tools'

3. Call the engine function and pass in your preferred configurations:

engine({...config})

Package Features

• Dev engine
• Smart, dynamic file routing
• Userback widget initializer
• Barba Transitions
• Default Configurations
• jQuery Plugins
• Utility Functions

Dev Engine

↑ Jump back to Package Features list

Get yer engine started 🚗. Hassle free set-up. The on/Sight Dev Engine is built to take in a configuration object and sets up a variety of runner tools for you. The engine function is built for flexibilty, scale, and smart configurations.

Smart, Dynamic File Routing

↑ Jump back to Package Features list

Use data attributes on your HTML to automatically watch, import, and run your JS files. You can immediately hook up an HTML element by using one of the two specified categories:

• [data-utility]
• [data-component]

The JS file will run with the specified element being passed in as the wrapper You need to attach a specific file path as the attribute value [data]

Read about how to use the file router

Userback Widget Initializer

↑ Jump back to Package Features list

There's no more need for a snippets/userback.liquid file in your project, with the power of JavaScript you can simply pass in your Userback token and watch your troubles melt away 🫠

Basic Usage

engine({
  userback: {
    // Pass in your real (project-specific) access token here
    accessToken: 'totallyRealAccessTokenExample'
  }
})

Additional Settings

The userback key currently has no additional settings. If you have an idea for one to add, please read through the Contribution Guidelines and start a conversation in Discord!

Barba Transitions

↑ Jump back to Package Features list

Default Configurations

↑ Jump back to Package Features list

JS class object, class prefixing, tailwind breakpoints, and more!

jQuery Plugins

↑ Jump back to Package Features list

watchFor, isInViewport, onClassChange, onDraglessClick, and more!

Read more about the available plugins here

Utility Functions

↑ Jump back to Package Features list

Use our amazing utility functions throughout your JS

Read more about the available utility functions here

Examples and Usage

• Getting Started: Importing
• File Router Usage

Getting Started: Importing

Back to top

• import engine from '@on-sight/dev-tools'
• import defaultEngineConfig from '@on-sight/dev-tools/settings'
• import { formatMoney } from '@on-sight/dev-tools/utils'

File Router Usage

Lorem ipsum dolar sit amet

  <button
    data-utility="link-to"
    data-link="/blog/your-url"
  >
    Click me
  </button>

You can also pass multiple file paths by comma separating them:

<button
  data-utility="link-to,inline-toggle"
  data-link="/blog/your-url"
  data-toggle="#some-query"
>
  Click me
</button>

File paths can also include a subfolder:

<button data-utility="button/atc">
  Click me
</button>

Default Settings

Overview of what settings is and how it gets used by the engine.

• Dev Engine Settings
• File Router Settings
• Userback Settings
• Barba Settings
• Plugins Settings
• Class Settings
• Tailwind Settings
• Debug Settings
• Additional Settings

Dev Engine Settings

File Router Settings

The fileRouter key currently has one customizable setting. You can customize watchForSelectors by supplying an array of objects with keys path, selector, and fileName.

Please be careful when customizing this as it holds a lot of power in the engine setup. Below is the default config object for watchForSelectors.

watchForSelectors: [
  { path: 'utilities', selector: '[data-utility]' },
  { path: 'components', selector: '[data-component]' },
  { path: 'utilities', selector: '[class*="reveal"]', fileName: 'reveal' },
]

Userback Settings

Barba Settings

Plugins Settings

Class Settings

Tailwind Settings

Debug Settings

Additional Settings

If you have an idea for one to add, please read through the Contribution Guidelines and start a conversation in Discord!

Contribution Guidelines