Troubleshooting

Common issues and solutions when working with Finsweet Attributes

This guide covers common issues you might encounter when using Finsweet Attributes and how to resolve them.

Loading Issues

Attribute not initializing

Symptoms: Your Attribute doesn’t seem to be working, even though the script is loaded.

Possible causes:

1. Missing Attribute key in script tag

   Make sure you’ve added the Attribute key to your script tag:

   <!-- ❌ Wrong - no attribute key -->
   <script type="module" src="https://cdn.jsdelivr.net/npm/@finsweet/attributes@2/attributes.js"></script>
   
   <!-- ✅ Correct - includes fs-list -->
   <script type="module" src="https://cdn.jsdelivr.net/npm/@finsweet/attributes@2/attributes.js" fs-list></script>
   

2. Script tag not set to module type

   The script must have type="module":

   <script type="module" src="..."></script>
   

3. Script loaded before elements exist

   Place the script tag before the closing </body> tag to ensure the DOM is ready.

4. Typo in Attribute key

   Verify the Attribute key matches exactly. It’s case-sensitive:

   <!-- ❌ Wrong -->
   <script fs-cmsLoad></script>
   
   <!-- ✅ Correct -->
   <script fs-list></script>
   

window.FinsweetAttributes is undefined

Symptoms: You’re trying to access the API, but window.FinsweetAttributes is undefined.

Solutions:

1. Check script loading order

   Make sure the Attributes script loads before your custom scripts:

   <!-- Attributes library -->
   <script type="module" src="https://cdn.jsdelivr.net/npm/@finsweet/attributes@2/attributes.js" fs-list></script>
   
   <!-- Your custom code -->
   <script>
     window.FinsweetAttributes?.push(['list', callback]);
   </script>
   

2. Initialize the array before using push()

   If you need to use push() before the library loads:

   window.FinsweetAttributes ||= [];
   window.FinsweetAttributes.push(['list', callback]);
   

3. Wait for the library to load

   Use the optional chaining operator (?.) or check if it exists:

   if (window.FinsweetAttributes) {
     window.FinsweetAttributes.load('list');
   }
   

Multiple instances loading

Symptoms: Your Attribute is initializing multiple times.

Cause: You may have included the Attributes script tag multiple times.

Solution: Check your Webflow project settings and custom code for duplicate script tags. The library is designed to handle multiple script tags, but each should define different Attributes:

<!-- ✅ Correct - different Attributes -->
<script type="module" src="..." fs-list></script>
<script type="module" src="..." fs-scrolldisable></script>

<!-- ❌ Avoid - same Attribute twice -->
<script type="module" src="..." fs-list></script>
<script type="module" src="..." fs-list></script>

Development Issues

Local development server not working

Symptoms: Running pnpm dev fails or the server doesn’t start.

Solutions:

1. Ensure pnpm is installed

   pnpm --version
   

   If not installed, install pnpm.

2. Install dependencies

   pnpm install
   

3. Check Node.js version

   Ensure you’re using Node.js v18 or higher:

   node --version
   

4. Clear pnpm cache

   pnpm store prune
   pnpm install
   

TypeScript errors in development

Symptoms: Type errors when building or running type checks.

Solutions:

1. Run type checking

   pnpm check
   

2. Ensure types are exported correctly

   Import types from @finsweet/attributes-utils:

   import type {
     FinsweetAttributeInit,
     AttributeElements,
     AttributeSettings,
   } from '@finsweet/attributes-utils';
   

3. Rebuild the project

   pnpm build
   

Tests failing

Symptoms: Tests fail when running pnpm test.

Solutions:

1. Run tests in watch mode

   pnpm test -- --watch
   

2. Check test file location

   Tests should be in packages/attributes/tests/.

3. Verify test setup

   Ensure your test imports the correct modules and mocks Webflow if needed.

Runtime Issues

Attribute not finding elements

Symptoms: Your Attribute loads but doesn’t detect elements with the correct attributes.

Solutions:

1. Check attribute syntax

   Ensure attributes follow the correct pattern:

   <!-- ✅ Correct -->
   <div fs-list-element="list"></div>
   
   <!-- ❌ Wrong - missing hyphen -->
   <div fs-listelement="list"></div>
   
   <!-- ❌ Wrong - wrong separator -->
   <div fs-list_element="list"></div>
   

2. Verify element exists when Attribute loads

   If elements are added dynamically, you may need to restart the Attribute:

   // After adding new elements to DOM
   await window.FinsweetAttributes.modules.list?.restart();
   

3. Check for typos in element names

   Element names must match exactly what the Attribute expects.

Conflicts with other scripts

Symptoms: Attributes work when tested alone but fail when other scripts are present.

Solutions:

1. Check for JavaScript errors

   Open browser DevTools (F12) and check the Console for errors.

2. Load Attributes before other scripts

   Place the Attributes script tag higher in your HTML.

3. Use destroy() before reinitializing

   If you’re dynamically loading content:

   // Destroy old instance
   window.FinsweetAttributes.modules.list?.destroy();
   
   // Load new content
   // ...
   
   // Restart Attribute
   await window.FinsweetAttributes.modules.list?.restart();
   

Webflow interactions conflicting

Symptoms: Webflow IX2 interactions don’t work properly with Attributes.

Cause: Attributes that manipulate the DOM may interfere with Webflow’s interaction engine.

Solution: In your custom Attribute, wait for Webflow to be ready:

import { waitWebflowReady } from '@finsweet/attributes-utils';

export const init = async () => {
  await waitWebflowReady();
  // Your code here
};

Performance Issues

Slow page load with multiple Attributes

Symptoms: Page takes a long time to load when using several Attributes.

Solutions:

1. Use dynamic loading

   Instead of loading all Attributes upfront, load them on-demand:

   // Load only when needed
   document.querySelector('#trigger').addEventListener('click', async () => {
     await window.FinsweetAttributes.load('accordion');
   });
   

2. Enable auto-loading only for used Attributes

   Instead of fs-attributes-auto, explicitly list the Attributes you need:

   <script type="module" src="..." fs-list fs-scrolldisable></script>
   

3. Check for redundant initializations

   Ensure you’re not reloading Attributes unnecessarily.

Memory leaks

Symptoms: Browser memory usage keeps increasing.

Cause: Event listeners or observers not being cleaned up.

Solutions:

1. Always implement destroy()

   When creating custom Attributes, return a destroy function:

   export const init = async () => {
     const handleClick = () => { /* ... */ };
     button.addEventListener('click', handleClick);
   
     return {
       destroy: () => {
         button.removeEventListener('click', handleClick);
       }
     };
   };
   

2. Use AbortController for event listeners

   const controller = new AbortController();
   
   button.addEventListener('click', handler, {
     signal: controller.signal
   });
   
   return {
     destroy: () => controller.abort()
   };
   

3. Disconnect observers

   const observer = new MutationObserver(callback);
   observer.observe(element, options);
   
   return {
     destroy: () => observer.disconnect()
   };
   

Debugging Tips

Enable Verbose Logging

Add console logs to track Attribute lifecycle:

export const init = async () => {
  console.log('[MyAttr] Initializing...');
  
  await waitWebflowReady();
  console.log('[MyAttr] Webflow ready');
  
  // Your code...
  
  console.log('[MyAttr] Initialization complete');
  
  return {
    destroy: () => {
      console.log('[MyAttr] Destroying...');
    }
  };
};

Check Attribute Status

Inspect the current state of Attributes:

// Check which Attributes are loaded
console.log('Loaded:', Array.from(window.FinsweetAttributes.process));

// Check available modules
console.log('Modules:', Object.keys(window.FinsweetAttributes.modules));

// Check library version
console.log('Version:', window.FinsweetAttributes.version);

Verify DOM Attributes

Use browser DevTools to inspect elements:

1. Right-click element → Inspect
2. Check that attributes are spelled correctly
3. Verify attribute values match expected format

Test in Isolation

Create a minimal test page with just the Attribute and essential code:

<!DOCTYPE html>
<html>
<head>
  <title>Test</title>
</head>
<body>
  <div fs-list-element="list"></div>
  
  <script type="module" src="https://cdn.jsdelivr.net/npm/@finsweet/attributes@2/attributes.js" fs-list></script>
</body>
</html>

Getting Help

If you’re still experiencing issues:

GitHub Issues

Report bugs or request features

Finsweet Forum

Ask questions and get community support

API Reference

Review the complete API documentation

Custom Attributes

Learn about creating custom solutions

Common Error Messages

'FinsweetAttributes' is not defined

The Attributes library hasn’t loaded yet. Use optional chaining:

window.FinsweetAttributes?.load('list');

Module not found

The Attribute package may not be published or the key is incorrect. Verify the Attribute key matches an existing package.

Cannot read property 'destroy' of undefined

The Attribute module hasn’t been loaded. Check that the Attribute initialized successfully:

if (window.FinsweetAttributes?.modules.list) {
  window.FinsweetAttributes.modules.list.destroy();
}