Nuxt Visitors 👀

Add live visitor counting to your Nuxt website in seconds. WebSocket-based, type-safe, and completely automatic.

Features ⚡️

• 🔄 Real-time updates via WebSocket
• 🪄 Zero configuration needed
• 🛠 Automatic connection management
• 📊 Type-safe composable
• 🧹 Auto cleanup on unmount
• 🌐 Leverages Nitro WebSocket with Pub/Sub

New (Experimental): Anonymous tracking of visitors' locations!

When enabled, the module tracks visitor locations. The useVisitors composable will additionally provide:

• A locations array: lists locations of all visitors.
• A myLocation object: contains the specific geolocation data for the current visitor.

Note: This feature is experimental and may be subject to future changes.

Installation

Install the module to your Nuxt application with one command:

npx nuxi module add nuxt-visitors

As Nitro WebSocket support is experimental, you need to enable it in your nuxt.config.ts:

export default defineNuxtConfig({
  modules: ['nuxt-visitors'],
  nitro: {
    experimental: {
      websocket: true
    }
  }
})

Configuration

The module accepts an optional configuration to enable location tracking. In your nuxt.config.ts, you can enable it as follows:

export default defineNuxtConfig({
  modules: ['nuxt-visitors'],
  visitors: {
    // Set to true to enable tracking of visitor locations
    locations: true
  },
  nitro: {
    experimental: {
      websocket: true
    }
  }
})

This will enable the locations and myLocation properties in the composable, as well as the locations property in the composable's return object.

Usage

<script setup lang="ts">
const { visitors } = useVisitors()
</script>

<template>
  <div>Active users: {{ visitors }}</div>
</template>

That's it! The module handles everything else automatically:

• WebSocket connection management
• Real-time updates
• Reconnection logic
• Error handling

Advanced usage

The composable provides additional features:

const {
  visitors,     // Ref<number> - Current visitor count
  locations,    // Ref<Location[]> - Array of geolocation objects for all visitors (if `locations: true`)
  myLocation,   // Ref<Location | null> - Geolocation of the current visitor (if `locations: true`)
  isConnected,  // Ref<boolean> - Connection status
  isLoading,    // Ref<boolean> - Loading state
  error,        // Ref<string | null> - Error message if any
  reconnect     // () => void - Manual reconnection
} = useVisitors()

Contributing

To start contributing, you can follow these steps:

1. First raise an issue to discuss the changes you would like to make.
2. Fork the repository.
3. Create a branch using conventional commits and the issue number as the branch name. For example, feat/123 or fix/456.
4. Make changes following the local development steps.
5. Commit your changes following the Conventional Commits specification.
6. If your changes affect the code, run tests using bun run test.
7. Create a pull request following the Pull Request Template.
   • To be merged, the pull request must pass the tests/workflow and have at least one approval.
   • If your changes affect the documentation, make sure to update it.
   • If your changes affect the code, make sure to update the tests.
8. Wait for the maintainers to review your pull request.
9. Once approved, the pull request will be merged in the next release !

Sponsors

Contributors

Published under the APACHE license. Made by @HugoRCD and community 💛

---

🤖 auto updated with automd (last updated: Tue Apr 15 2025)