Architecture - Attributes by Finsweet

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:

The core attributes package is loaded on the page
It scans the DOM for attribute elements
When an attribute is detected, the corresponding package is dynamically imported
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

Development

Documentation Index

​Monorepo Structure

​Package Organization

​Core Packages

​attributes

​utils

​template

​docs

​Attribute Packages

​How It Works

​Development Commands

Build docs developers (and LLMs) love