Web Toggle Point

A library providing a means to toggle or branch web application code.

---

Table of Contents

• 🤝 Introduction
  • 🐬 Purpose
  • 🎬 Getting Started
• 📦 Packages
• 🎁 Examples
• 🔜 Future Plans
• 🔗 Links

🤝 Introduction

🐬 Purpose

This library provides a means to toggle or branch application code.

It aims to enable low friction feature toggling aspect/advice¹ in a codebase.

It suggests a convention-based approach to storing variant code, aiming to mitigate boilerplate whilst developing new features, and reduce the friction of accepting or rejecting toggled variations, when appropriate.

Originally developed for experiment toggles / flags, it acts only as a means to implement a toggle point, separating any toggle router concern, so is agnostic of the type of toggle or flag.

For a full introduction, please see some articles on medium.com

🎬 Getting Started

There are a few moving parts, and they can be combined in different combinations, depending on use case.

The bare minimum would be injecting a plugin from the webpack package into a build process, and connecting it with appropriate target modules. The other packages are utilities to support that. To consider what's possible, and how you might set things up, see the examples for inspiration!

Then:

1. Figure out what code modules you'd like to toggle, and see if they are suitable
2. Figure out a filesystem convention to use
   • the default proposes colocating variations of base modules in ./__variants__/<feature name>/<variant name>/ folders, with filename parity for the modules themselves.
3. Implement the webpack package² into your build process, via configuration of appropriate pointcuts, targeting code modules for toggling that meet the criteria:
   • A single, default export, that is a function
   • Side-effect free (or, at least, with harmless import side-effects)
   • Resolvable by Webpack
4. Create a feature toggle state store, utilising the features package, or otherwise, suitable for the dynamism of your toggle type.
   • This needs to get state from an appropriate Toggle Router / runtime state provider.
5. Create a toggle point for the point cuts
   • For a React application, the withTogglePointFactory or withToggledHookFactory from the react pointcuts package can be used, to construct one.
   • Again, use the examples as a guide.

📦 Packages

This repository is made up of four packages:

1. @asos/web-toggle-point-features - Stores for holding feature toggle state.

2. @asos/web-toggle-point-react-pointcuts - React application code for varying a component or hook, based on a given feature toggle state.

3. @asos/web-toggle-point-ssr - Code for serializing JSON as part of a server rendering process, to be deserialized in client code into an appropriate feature toggle state store. Includes additional React-specific exports, for use in React applications.

4. @asos/web-toggle-point-webpack - Detection and insertion of toggle point code during a webpack build process.

🎁 Examples

Please see separate examples documentation.

🔜 Future Plans

Please see issues and please consider contributing!

🔗 Links

• Developer Documentation

Footnotes

1. (ab)using some terminology from aspect-oriented programming ↩

2. Currently, only webpack is supported. See Issue #7 for plans to introduce a Rollup / Vite equivalent. ↩