Architecture

Understand the monorepo structure and package organization of Attributes

This guide explains the architecture and organization of the Attributes monorepo.

Monorepo Structure

Attributes employs a monorepo setup using pnpm Workspaces. All packages are located in the packages directory at the root of the repository.

The workspace configuration is defined in pnpm-workspace.yaml:

packages:
  - packages/*
  - '!packages/template'

onlyBuiltDependencies:
  - esbuild

This configuration includes all packages in the packages directory, excluding the template package which serves as a starting point for new attributes.

Package Organization

The monorepo contains several types of packages:

Core Packages

These packages form the foundation of the Attributes library:

attributes

The core library package. This is the main entry point and is responsible for:

• Dynamically importing other attribute packages during runtime
• Coordinating the initialization of attributes
• Providing the public API

This is the package that gets published as @finsweet/attributes on npm.

utils

A collection of utility functions used across the library. This package provides:

• Common helper functions
• Shared types and interfaces
• Reusable logic for attribute packages

template

A template for creating new Attributes. It includes:

• Basic structure and boilerplate
• Example code to help you get started
• Best practices for attribute development

Note: The template package is excluded from the workspace to prevent it from being built or published.

docs

Custom code for the Attributes documentation website, which is hosted on Webflow. This package contains:

• Documentation-specific scripts
• Custom integrations for the docs site

Attribute Packages

Each attribute solution has its own package. These are feature-specific implementations that get dynamically loaded by the core library:

• accordion - Accordion functionality
• autovideo - Automatic video controls
• codehighlight - Code syntax highlighting
• combobox - Custom combobox inputs
• copyclip - Copy to clipboard
• displayvalues - Display dynamic values
• favcustom - Custom favicon
• formsubmit - Form submission handling
• inject - Dynamic content injection
• inputactive - Input active states
• inputcounter - Character counter for inputs
• list - List filtering, sorting, and search
• mirrorclick - Mirror click events
• mirrorinput - Mirror input values
• modal - Modal dialogs
• numbercount - Animated number counting
• queryparam - URL query parameter handling
• rangeslider - Custom range sliders
• readtime - Reading time estimation
• removequery - Remove query parameters
• scrolldisable - Disable scrolling
• selectcustom - Custom select dropdowns
• sliderdots - Slider dot navigation
• smartlightbox - Smart lightbox galleries
• socialshare - Social media sharing
• starrating - Star rating inputs
• toc - Table of contents generation
• videohls - HLS video support

How It Works

The architecture follows a dynamic loading pattern:

1. The core attributes package is loaded on the page
2. It scans the DOM for attribute elements
3. When an attribute is detected, the corresponding package is dynamically imported
4. The attribute-specific code initializes only when needed

This approach ensures:

• Small initial bundle size - Only the core is loaded upfront
• Pay-for-what-you-use - Attribute packages load on demand
• Maintainability - Each attribute is isolated in its own package
• Extensibility - New attributes can be added without modifying the core

Development Commands

The root package.json defines workspace-level commands:

{
  "scripts": {
    "dev": "pnpm --filter @finsweet/attributes dev",
    "build": "pnpm --filter @finsweet/attributes --filter @finsweet/attributes-docs build",
    "check": "pnpm -r check",
    "lint": "pnpm -r lint",
    "test": "pnpm --filter @finsweet/attributes test"
  }
}

These commands use pnpm’s workspace features:

• --filter targets specific packages
• -r (recursive) runs commands in all workspace packages