feat: per-page configuration (#85)

arg0NNY · web-flow · commit 1f60b656ceb0 · 2025-04-07T17:39:49.000+03:00
diff --git a/README.md b/README.md
@@ -209,6 +209,28 @@ CSS media feature.
 }
 ```
 
+## Per-page configuration
+You can override the global configuration for specific pages using [`definePageMeta`](https://nuxt.com/docs/api/utils/define-page-meta).
+```vue
+<script setup>
+import { definePageMeta } from '#imports'
+
+definePageMeta({
+  viewport: {
+    breakpoints: {
+      desktop: 1024,
+      mobile: 320,
+      tablet: 768
+    },
+    cookie: {
+      name: 'viewport-per-page'
+    }
+    // Other fields will be inherited from the global configuration
+  }
+})
+</script>
+```
+
 ## API
 
 ### `viewport.breakpoint`
diff --git a/playground/components/ViewportState.vue b/playground/components/ViewportState.vue
@@ -0,0 +1,82 @@
+<template>
+  <section>
+    <p>
+      Your value of breakpoint {{ $viewport.breakpoint.value }} is:
+      <b>{{ $viewport.breakpointValue($viewport.breakpoint.value) }}</b>
+    </p>
+    <p>
+      Your current breakpoint is: <b>{{ $viewport.breakpoint }}</b>
+    </p>
+
+    <div v-for="breakpoint in ['mobile', 'tablet', 'desktop']" :key="breakpoint">
+      <hr />
+
+      <h4>{{ breakpoint }}</h4>
+
+      <p>
+        <code>match</code> → <b>{{ $viewport.match(breakpoint) }}</b>
+      </p>
+      <p>
+        <code>isLessThan</code> → <b>{{ $viewport.isLessThan(breakpoint) }}</b>
+      </p>
+      <p>
+        <code>isLessOrEquals</code> → <b>{{ $viewport.isLessOrEquals(breakpoint) }}</b>
+      </p>
+      <p>
+        <code>isGreaterThan</code> → <b>{{ $viewport.isGreaterThan(breakpoint) }}</b>
+      </p>
+      <p>
+        <code>isGreaterOrEquals</code> → <b>{{ $viewport.isGreaterOrEquals(breakpoint) }}</b>
+      </p>
+    </div>
+  </section>
+</template>
+
+<style>
+* {
+  box-sizing: border-box;
+  padding: 0;
+  margin: 0;
+}
+
+html {
+  font-family: sans-serif;
+  font-size: 120%;
+}
+
+body {
+  display: flex;
+  justify-content: center;
+  align-items: center;
+  min-height: 100vh;
+}
+
+section {
+  max-width: calc(100vw - 1rem);
+  background: #eee;
+  padding: 2rem;
+  border-radius: 1rem;
+}
+
+hr {
+  display: block;
+  border: none;
+  border-top: 0.1rem dashed #ccc;
+  margin: 1rem auto;
+}
+
+p {
+  margin: 0.5rem 0;
+}
+
+h4 {
+  text-decoration: underline;
+}
+
+code {
+  display: inline-block;
+  padding: 0.25em 0.35rem;
+  background: #ccc;
+  border-radius: 0.25rem;
+}
+</style>
diff --git a/playground/pages/index.vue b/playground/pages/index.vue
@@ -1,82 +1,3 @@
 <template>
-  <section>
-    <p>
-      Your value of breakpoint {{ $viewport.breakpoint.value }} is:
-      <b>{{ $viewport.breakpointValue($viewport.breakpoint.value) }}</b>
-    </p>
-    <p>
-      Your current breakpoint is: <b>{{ $viewport.breakpoint }}</b>
-    </p>
-
-    <div v-for="breakpoint in ['mobile', 'tablet', 'desktop']" :key="breakpoint">
-      <hr />
-
-      <h4>{{ breakpoint }}</h4>
-
-      <p>
-        <code>match</code> → <b>{{ $viewport.match(breakpoint) }}</b>
-      </p>
-      <p>
-        <code>isLessThan</code> → <b>{{ $viewport.isLessThan(breakpoint) }}</b>
-      </p>
-      <p>
-        <code>isLessOrEquals</code> → <b>{{ $viewport.isLessOrEquals(breakpoint) }}</b>
-      </p>
-      <p>
-        <code>isGreaterThan</code> → <b>{{ $viewport.isGreaterThan(breakpoint) }}</b>
-      </p>
-      <p>
-        <code>isGreaterOrEquals</code> → <b>{{ $viewport.isGreaterOrEquals(breakpoint) }}</b>
-      </p>
-    </div>
-  </section>
+  <ViewportState />
 </template>
-
-<style>
-* {
-  box-sizing: border-box;
-  padding: 0;
-  margin: 0;
-}
-
-html {
-  font-family: sans-serif;
-  font-size: 120%;
-}
-
-body {
-  display: flex;
-  justify-content: center;
-  align-items: center;
-  min-height: 100vh;
-}
-
-section {
-  max-width: calc(100vw - 1rem);
-  background: #eee;
-  padding: 2rem;
-  border-radius: 1rem;
-}
-
-hr {
-  display: block;
-  border: none;
-  border-top: 0.1rem dashed #ccc;
-  margin: 1rem auto;
-}
-
-p {
-  margin: 0.5rem 0;
-}
-
-h4 {
-  text-decoration: underline;
-}
-
-code {
-  display: inline-block;
-  padding: 0.25em 0.35rem;
-  background: #ccc;
-  border-radius: 0.25rem;
-}
-</style>
diff --git a/playground/pages/per-page-config.vue b/playground/pages/per-page-config.vue
@@ -0,0 +1,20 @@
+<template>
+  <ViewportState />
+</template>
+
+<script setup lang="ts">
+import { definePageMeta } from '#imports'
+
+definePageMeta({
+  viewport: {
+    breakpoints: {
+      desktop: 1024,
+      mobile: 320,
+      tablet: 768,
+    },
+    cookie: {
+      name: 'viewport-per-page-config',
+    },
+  },
+})
+</script>
diff --git a/src/module.ts b/src/module.ts
@@ -1,10 +1,10 @@
 import { fileURLToPath } from 'url'
-import { addImports, addPlugin, addTemplate, createResolver, defineNuxtModule } from '@nuxt/kit'
+import { addImports, addPlugin, addTemplate, addTypeTemplate, createResolver, defineNuxtModule } from '@nuxt/kit'
 
 import { name, version } from '../package.json'
 
-import { DEFAULT_OPTIONS } from './constants'
-import type { ViewportOptions } from './types'
+import type { ViewportOptions } from './runtime/types'
+import { extendOptions } from './runtime/utils'
 
 export type ModuleOptions = ViewportOptions
 
@@ -21,15 +21,7 @@ export default defineNuxtModule<ModuleOptions>({
   },
 
   setup(options, nuxt) {
-    options = {
-      ...DEFAULT_OPTIONS,
-      ...options,
-
-      cookie: {
-        ...DEFAULT_OPTIONS.cookie,
-        ...options.cookie,
-      },
-    }
+    options = extendOptions(options)
 
     const { resolve } = createResolver(import.meta.url)
     const runtimeDir = fileURLToPath(new URL('./runtime', import.meta.url))
@@ -45,6 +37,11 @@ export default defineNuxtModule<ModuleOptions>({
       },
     }).dst
 
+    addTypeTemplate({
+      src: resolve(runtimeDir, 'types.d.ts'),
+      filename: 'types/viewport.d.ts',
+    })
+
     addPlugin(resolve(runtimeDir, 'plugin.client'))
     addPlugin(resolve(runtimeDir, 'plugin.server'))
 
diff --git a/src/runtime/composables.ts b/src/runtime/composables.ts
@@ -1,6 +1,14 @@
-import { type ViewportManager } from '../types'
-import { useNuxtApp } from '#imports'
+import { computed, type ComputedRef } from 'vue-demi'
+import type { ViewportManager, ViewportOptions } from './types'
+import { extendOptions } from './utils'
+import { useNuxtApp, useRoute } from '#imports'
+import globalOptions from '#viewport-options'
 
 export function useViewport(): ViewportManager {
   return useNuxtApp().$viewport
 }
+
+export function useViewportOptions(): ComputedRef<ViewportOptions> {
+  const route = useRoute()
+  return computed(() => extendOptions(route.meta.viewport, globalOptions))
+}
diff --git a/src/runtime/constants.ts b/src/runtime/constants.ts
@@ -1,4 +1,4 @@
-import { type ViewportOptions } from './types'
+import type { ViewportOptions } from './types'
 
 export const COOKIE_EXPIRES_IN_DAYS = 365
 
diff --git a/src/runtime/manager.ts b/src/runtime/manager.ts
@@ -1,27 +1,29 @@
 import cookie from 'cookiejs'
-import { computed, type Ref } from 'vue-demi'
+import { computed, type MaybeRefOrGetter, type Ref, toRef, toValue } from 'vue-demi'
 
-import type { ViewportOptions, ViewportQuery } from '../types'
+import type { ViewportOptions, ViewportQuery } from './types'
 
 export const STATE_KEY = 'viewportState'
 
-export function createViewportManager(options: ViewportOptions, state: Ref<string>) {
+export function createViewportManager(options: MaybeRefOrGetter<ViewportOptions>, state: Ref<string>) {
+  options = toRef(options)
+
   const breakpoint = computed<string>({
     get() {
-      return state.value || options.fallbackBreakpoint
+      return state.value || options.value.fallbackBreakpoint
     },
 
     set(newBreakpoint) {
       state.value = newBreakpoint
 
-      if (typeof window !== 'undefined' && options.cookie.name) {
-        cookie.set(options.cookie.name, state.value, options.cookie)
+      if (typeof window !== 'undefined' && options.value.cookie.name) {
+        cookie.set(options.value.cookie.name, state.value, options.value.cookie)
       }
     },
   })
 
   const queries = computed<Record<string, ViewportQuery>>(() => {
-    const breakpoints = options.breakpoints || {}
+    const breakpoints = options.value.breakpoints || {}
     const breakpointsKeys = Object.keys(breakpoints).sort((a, b) => breakpoints[a] - breakpoints[b])
 
     const output: Record<string, ViewportQuery> = {}
@@ -36,7 +38,7 @@ export function createViewportManager(options: ViewportOptions, state: Ref<strin
 
       let mediaQuery = ''
 
-      if (options.feature === 'minWidth') {
+      if (options.value.feature === 'minWidth') {
         if (i > 0) {
           mediaQuery = `(min-width: ${size}px)`
         } else {
@@ -86,7 +88,7 @@ export function createViewportManager(options: ViewportOptions, state: Ref<strin
    * @param searchBreakpoint - Breakpoint to search.
    */
   function breakpointValue(searchBreakpoint: string) {
-    const breakpoints = options.breakpoints || {}
+    const breakpoints = toValue(options).breakpoints || {}
 
     return breakpoints[searchBreakpoint]
   }
diff --git a/src/runtime/plugin.client.ts b/src/runtime/plugin.client.ts
@@ -1,9 +1,10 @@
 import { createViewportManager, STATE_KEY } from './manager'
 
+import { useViewportOptions } from './composables'
 import { defineNuxtPlugin, useState } from '#imports'
-import viewportOptions from '#viewport-options'
 
-export default defineNuxtPlugin(async (nuxtApp) => {
+export default defineNuxtPlugin((nuxtApp) => {
+  const viewportOptions = useViewportOptions()
   const state = useState<string>(STATE_KEY)
   const manager = createViewportManager(viewportOptions, state)
 
diff --git a/src/runtime/plugin.server.ts b/src/runtime/plugin.server.ts
@@ -1,10 +1,11 @@
 import { createViewportManager, STATE_KEY } from './manager'
 import { detectBreakpoint, parseCookie } from './utils'
 
+import { useViewportOptions } from './composables'
 import { defineNuxtPlugin, useState } from '#imports'
-import viewportOptions from '#viewport-options'
 
 export default defineNuxtPlugin(async (nuxtApp) => {
+  const viewportOptions = useViewportOptions()
   const state = useState<string>(STATE_KEY)
   const manager = createViewportManager(viewportOptions, state)
 
@@ -22,8 +23,10 @@ export default defineNuxtPlugin(async (nuxtApp) => {
     cookie = ''
   }
 
-  cookie = parseCookie(cookie)[viewportOptions.cookie?.name]
-  state.value = await detectBreakpoint(viewportOptions, { cookie, headers })
+  state.value = await detectBreakpoint(viewportOptions.value, {
+    cookie: viewportOptions.value.cookie?.name ? parseCookie(cookie)[viewportOptions.value.cookie.name] : undefined,
+    headers,
+  })
 
   return nuxtApp.provide('viewport', manager)
 })
diff --git a/src/runtime/types.d.ts b/src/runtime/types.d.ts
diff --git a/src/runtime/utils.ts b/src/runtime/utils.ts

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-import { type ViewportOptions } from './types'`
	`1`	`+import type { ViewportOptions } from './types'`
`2`	`2`
`3`	`3`	`export const COOKIE_EXPIRES_IN_DAYS = 365`
`4`	`4`