📦 nuxt-version-checker

A minimal Nuxt 3 module that detects if a new version of your app is available and fetches a remote changelog in Markdown format.

Headless – no UI, just reactive composables.

---

✨ Features

• ✅ Version polling from /version.json
• ✅ Loads Markdown changelog from remote URL
• ✅ Exposes useLatestChangelog() composable for easy version checking and changelog loading
• ✅ Extensible with forceUpdate, releasedAt, etc.
• ✅ No dependencies, TypeScript native

---

🚀 Quick Setup

Install the module to your Nuxt application with one command:

npx nuxi module add nuxt-version-checker

That's it! You can now use nuxt-version-check in your Nuxt app ✨

🚀 Configuration

Check or add the module configuration in your nuxt.config.ts:

export default defineNuxtConfig({
  modules: ['~/modules/nuxt-version-checker'],
  versionChecker: {
    currentVersion: '1.2.3',
    versionUrl: '/version.json',
    intervalMs: 5 * 60 * 1000,
  },
})

---

📄 version.json Format

{
  "version": "1.2.4",
  "changelogUrl": "/changelog/1.2.4.md",
  "forceUpdate": false,
  "releasedAt": "2025-06-25T08:00:00Z"
}

Field	Type	Description
version	string	Required. New version string
changelogUrl	string	Optional. URL to Markdown changelog
forceUpdate	boolean	Optional. Set to true to enforce update
releasedAt	string	Optional. ISO date string

---

🧠 Usage

useLatestChangelog()

const {
  changelog,
  hasNewChangelog,
  loadChangelog,
  changelogUrl,
  seenUrl,
} = useLatestChangelog()

The useLatestChangelog() composable automatically:

• Detects when a new version is available
• Checks if the user has seen the latest changelog
• Loads the changelog content when a new unseen version is detected

Example

const { changelog, hasNewChangelog } = useLatestChangelog()

// The changelog is automatically loaded when a new version is available
// and the user hasn't seen it yet

// You can use the hasNewChangelog flag to show a notification
watchEffect(() => {
  if (hasNewChangelog.value) {
    // Show notification or modal with changelog.value
  }
})

Advanced Usage

The original composables are still available if you need more control:

useVersionCheck()

const {
  newVersionAvailable,
  latestVersion,
  changelogUrl,
  forceUpdate,
  releasedAt,
} = useVersionCheck()

useChangelog()

const {
  changelog,
  loadChangelog,
  seenUrl,
  loadedUrl,
} = useChangelog()

await loadChangelog('/changelog/1.2.4.md')

---

📦 Suggested use cases

• Show update banner when new version is deployed
• Display changelog after page reload
• Force update flow with forceUpdate: true

---

🛡️ License

MIT