@on-sight/theme-tools

Table of Contents

• What is this?
• Who is this for?
• Package Features
  • Dev engine
  • Smart, dynamic file routing
  • Default Configurations
  • 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 and features that o/S uses across it's projects. theme-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 theme-tools is as easy as 1, 2, 3, 4, 5, 6, 7...

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

npm install @on-sight/theme-tools

2. Import engine into your main JS entry point:

import engine from "@on-sight/theme-tools";

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

engine({ ...config });

Package Features

• Dev engine
• Smart, dynamic file routing
• Default Configurations
• 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

Default Configurations

↑ Jump back to Package Features list

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

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/theme-tools'
• import defaultEngineConfig from '@on-sight/theme-tools/settings'
• import { formatMoney } from '@on-sight/theme-tools/utils'

File Router Usage

The file router automatically imports and initializes JavaScript files based on data-utility and data-component attributes in your HTML. When the engine detects these attributes, it dynamically imports the corresponding file from your project's utilities or components folder and passes the element as the wrapper.

Basic Usage

Add a data-utility or data-component attribute to any HTML element:

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

This will automatically import and run /utilities/link-to.js (or .ts) with the button element as the wrapper.

Multiple File Paths

You can load multiple utilities or components on a single element by comma-separating them:

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

This imports both link-to.js and inline-toggle.js.

Subfolder Paths

Organize your files in subfolders for better structure:

<button data-utility="button/atc">Add to Cart</button>

This imports /utilities/button/atc.js.

Creating Router-Compatible Files

Your utility or component files should export a default function that receives the wrapper element:

// utilities/my-utility.js
export default function (wrapper) {
  // wrapper is the element with data-utility="my-utility"
  const button = wrapper.querySelector("button");

  button.addEventListener("click", () => {
    console.log("Clicked!");
  });
}

Advanced Usage

Complete Engine Configuration Example

Here's a comprehensive example showing how to configure the engine with custom settings:

// main.js - Your webpack entry point
import engine from "@on-sight/theme-tools";
import { formatMoney, debounce } from "@on-sight/theme-tools/utils";

// Configure the engine
engine({
  // Customize file router behavior
  fileRouter: {
    watchForSelectors: [
      { path: "utilities", selector: "[data-utility]" },
      { path: "components", selector: "[data-component]" },
      { path: "utilities", selector: '[class*="reveal"]', fileName: "reveal" },
    ],
  },

  // Use custom class names
  classes: {
    active: "is-active",
    loading: "is-loading",
    hidden: "u-hidden",
  },

  // Match your Tailwind config
  tailwind: {
    screens: {
      sm: 640,
      md: 768,
      lg: 1024,
      xl: 1280,
    },
  },

  // Enable debug mode during development
  debug: {
    debugMode: process.env.NODE_ENV === "development",
  },
});

// Use utility functions anywhere in your code
const price = formatMoney(1999, "${{ amount }}");
console.log(price); // "$19.99"

Using Utilities in Your Code

Create modular, reusable code with utilities:

import { debounce } from "@on-sight/theme-tools/utils";

export default function (wrapper) {
  // Use debounce utility
  window.addEventListener(
    "resize",
    debounce(() => {
      repositionSlides();
    }, 250),
  );

  function repositionSlides() {
    // Your code here
  }
}

Working with the Global Config

Access configuration values anywhere in your code:

export default function (wrapper) {
  const { classes, tailwind } = config;

  // Use class config
  wrapper.classList.add(classes.active);

  // Use tailwind breakpoints
  if (window.innerWidth >= tailwind.screens.lg) {
    // Desktop-specific code
  }
}

Default Settings

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

• Dev Engine Settings
• File Router Settings
• Class Settings
• Tailwind Settings
• Debug Settings
• Additional Settings

Dev Engine Settings

The main engine accepts a configuration object with the following structure:

import engine from "@on-sight/theme-tools";

engine({
  fileRouter: {
    /* file router config */
  },
  classes: {
    /* classes config */
  },
  tailwind: {
    /* tailwind config */
  },
  debug: {
    /* debug config */
  },
});

You can also import and extend the default configuration:

import engine, { defaultEngineConfig } from "@on-sight/theme-tools";

engine({
  ...defaultEngineConfig,
  debug: {
    debugMode: true,
  },
});

Or import individual default configurations:

import engine from "@on-sight/theme-tools";
import {
  defaultClassesConfig,
  defaultTailwindConfig,
} from "@on-sight/theme-tools/settings";

engine({
  classes: {
    ...defaultClassesConfig,
    active: "is-active", // Override specific values
  },
  tailwind: defaultTailwindConfig,
});

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" },
];

Class Settings

Define a centralized set of CSS class names used throughout your theme. This makes it easy to maintain consistent class naming across your project.

Default Configuration

classes: {
  active: 'on',
  loading: 'loading',
  loaded: 'loaded',
  error: 'error',
  unavailable: 'oos',
  animationActive: 'revealing',
  animationComplete: 'revealed',
  hidden: 'hidden',
  activeChild: 'child-on',
  colSpanFull: 'col-span-full'
}

Accessing Classes in Your Code

Classes are available globally via config.classes:

// In your utility or component files
export default function (wrapper) {
  const { classes } = config;

  wrapper.classList.add(classes.active);
  wrapper.classList.remove(classes.loading);
}

Customizing Classes

engine({
  classes: {
    active: "is-active",
    loading: "is-loading",
    hidden: "u-hidden",
  },
});

Tailwind Settings

Define Tailwind breakpoint values for use in your JavaScript. This allows you to write responsive JavaScript that matches your Tailwind CSS breakpoints.

Default Configuration

tailwind: {
  prefix: '',
  screens: {
    sm: 640,
    md: 768,
    lg: 1024,
    xl: 1280,
    '2xl': 1536
  }
}

Accessing Breakpoints in Your Code

Tailwind config is available globally via config.tailwind:

export default function (wrapper) {
  const { tailwind } = config;
  const windowWidth = window.innerWidth;

  if (windowWidth >= tailwind.screens.lg) {
    // Desktop behavior
  } else if (windowWidth >= tailwind.screens.md) {
    // Tablet behavior
  } else {
    // Mobile behavior
  }
}

Customizing Breakpoints

Match your project's Tailwind configuration:

engine({
  tailwind: {
    prefix: "tw-",
    screens: {
      sm: 576,
      md: 768,
      lg: 992,
      xl: 1200,
      "2xl": 1400,
    },
  },
});

Debug Settings

Control debugging features for development.

Default Configuration

debug: {
  debugMode: false;
}

Options

• debugMode (Boolean): When true, logs the engine configuration to the console on initialization. Helpful for troubleshooting. Default: false

Example: Enable Debug Mode

engine({
  debug: {
    debugMode: true,
  },
});

When debugMode is enabled, you'll see the complete engine configuration logged to the console when the engine initializes, which is helpful for verifying your 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

We welcome contributions to @on-sight/theme-tools! Whether you're fixing bugs, adding features, or improving documentation, your help is appreciated.

Getting Started

1. Fork the repository on GitHub
2. Clone your fork locally
3. Create a new branch for your changes: git checkout -b feature/your-feature-name
4. Make your changes following our coding standards
5. Test your changes thoroughly
6. Commit your changes with clear, descriptive commit messages
7. Push to your fork and submit a pull request

Coding Standards

• Follow the existing code style and patterns
• Use ES6+ JavaScript features
• Write clear, self-documenting code
• Add JSDoc comments for functions and complex logic
• Keep functions focused and single-purpose

Adding New Features

When adding new features:

1. Utilities: Add new utility functions to /src/utils/ and export them in /src/utils/index.js
2. Documentation: Update relevant README files with examples and usage instructions
3. Settings: If your feature needs configuration, add default settings to /src/settings/

Documentation

Good documentation is essential! When adding or modifying features:

• Update the main README.md with feature descriptions and examples
• Add or update examples in the relevant documentation files
• Include code examples that are clear and practical
• Explain both what the feature does and why you'd use it

Questions or Ideas?

• Open an issue on GitHub to discuss new features or report bugs
• Join the conversation in our Discord community
• Tag maintainers in your pull requests for faster review

Code Review Process

All contributions go through code review. We'll provide feedback and work with you to get your changes merged. Be patient and open to suggestions!

Thank you for contributing to @on-sight/theme-tools! 🎉