Nuxt 4

Release Notes v3.0.0

🚀 Major Release: Global Hooks System

We're excited to announce nuxt-lenis v3.0.0, a major release that introduces a powerful global hooks system, enabling developers to tap into Lenis lifecycle events from anywhere in their Nuxt application.

✨ New Features

🎯 Global Hooks System

The biggest addition in v3.0.0 is the introduction of global hooks using Nuxt's native hook system. This allows for powerful integrations and decoupled architecture.

Available Hooks:

• lenis:created - Triggered when a Lenis instance is created
• lenis:initiated - Triggered when a Lenis instance is fully set up and ready
• lenis:scroll - Triggered on every scroll event from any Lenis instance
• lenis:destroy - Triggered before a Lenis instance is destroyed

Usage Example:

<script setup>
import { useNuxtApp } from '#app'

const nuxtApp = useNuxtApp()

onMounted(() => {
  // Listen for Lenis initiation
  nuxtApp.hook('lenis:initiated', (payload) => {
    console.log('🚀 Lenis ready:', payload.id)
    // Your custom initialization logic here
  })

  // Listen for scroll events
  nuxtApp.hook('lenis:scroll', (payload) => {
    console.log('Scroll progress:', payload.state.progress)
  })
})
</script>

📋 Hook Payloads

Each hook provides rich payload data:

// lenis:created
{ lenis: Lenis, id: string, options: LenisOptions }

// lenis:initiated  
{ lenis: Lenis, id: string, isDefault: boolean }

// lenis:scroll
{ lenis: Lenis, id: string, state: ScrollState }

// lenis:destroy
{ lenis: Lenis | undefined, id: string }

🎨 Enhanced TypeScript Support

• Added comprehensive type definitions for all hooks
• Extended Nuxt's RuntimeNuxtHooks interface
• Full IntelliSense support for hook payloads

🛠️ Technical Improvements

Architecture Enhancements

• Decoupled Event System: Components can now react to Lenis events without direct coupling
• Native Nuxt Integration: Uses Nuxt's built-in hook system (nuxtApp.hook() / nuxtApp.callHook())
• Performance Optimized: Efficient event propagation with minimal overhead

Developer Experience

• Rich Debugging: Console logging for all lifecycle events
• Documentation: Comprehensive docs with real-world examples
• Playground Examples: Live examples demonstrating hook usage

🎯 Use Cases

The new hooks system enables powerful integrations:

Analytics & Tracking

<script setup>
nuxtApp.hook('lenis:scroll', (payload) => {
  if (payload.state.progress % 0.25 === 0) {
    gtag('event', 'scroll_progress', {
      progress: Math.round(payload.state.progress * 100)
    })
  }
})
</script>

Custom Animations

<script setup>
nuxtApp.hook('lenis:scroll', (payload) => {
  const { scroll, velocity, direction } = payload.state
  // Create custom scroll-based effects
  updateParallaxElements(scroll)
  updateScrollIndicator(payload.state.progress)
})
</script>

Global State Management

<script setup>
const globalScrollState = reactive({
  isScrolling: false,
  progress: 0,
  velocity: 0
})

nuxtApp.hook('lenis:scroll', (payload) => {
  Object.assign(globalScrollState, {
    isScrolling: payload.state.isScrolling,
    progress: payload.state.progress,
    velocity: payload.state.velocity
  })
})
</script>

📚 Documentation

• Hooks Guide - Comprehensive guide with examples
• Playground Examples - Live demonstrations
• TypeScript Definitions - Full type support

🔄 Migration Guide

From v2.x to v3.0.0

This is a non-breaking release! All existing functionality remains unchanged. The hooks system is an additive feature.

No migration required - your existing code will continue to work exactly as before.

New Projects

For new projects, you can immediately start using the hooks system:

<script setup>
import { useNuxtApp } from '#app'

const nuxtApp = useNuxtApp()

onMounted(() => {
  nuxtApp.hook('lenis:initiated', (payload) => {
    // Your code here
  })
})
</script>

🐛 Bug Fixes

• Fixed TypeScript errors in destroyLenis function
• Improved type safety in getScrollState function
• Enhanced error handling in hook callbacks

📦 Dependencies

• Lenis: ^1.2.3 (unchanged)
• Nuxt: Compatible with ^4.0.0

🚀 Performance

• Zero overhead when hooks are not used
• Minimal impact when hooks are registered
• Efficient propagation of scroll events

🔮 Future Roadmap

• v3.1.0: Additional hooks (lenis:start, lenis:stop, lenis:resize)
• v3.2.0: Hook middleware system for advanced filtering
• v3.3.0: Built-in analytics integrations

💝 Acknowledgments

Special thanks to the community for requesting this feature and providing valuable feedback during development.

📝 Full Changelog

Added

• 🎯 Global hooks system using Nuxt's native hooks
• 📋 Four new lifecycle hooks (created, initiated, scroll, destroy)
• 🎨 Comprehensive TypeScript definitions
• 📚 Documentation and examples
• 🎮 Interactive playground demos

Fixed

• 🐛 TypeScript errors in instance management
• 🔧 Improved type safety across the module

Changed

• 📦 Version bump to 3.0.0 (major feature addition)
• 🏗️ Enhanced internal architecture for hook support

---

Install the latest version:

npm install nuxt-lenis@^3.0.0

Happy scrolling! 🚀

Full Changelog: v2.1.2...v3.0.0