fix(date): valid date-fns locale + formats type; useDate() docs (#318, #313, #323) (#374)

Author: AndreyYolkin

docs/guide/features/date.md

@@ -27,3 +27,37 @@ import { adapter, dateConfiguration, i18n } from 'virtual:vuetify-date-configura
 ```
 
 Check out [vuetify-date](https://github.com/vuetifyjs/nuxt-module/blob/main/src/runtime/plugins/vuetify-date.ts) plugin and the [date module](https://github.com/vuetifyjs/nuxt-module/blob/main/src/runtime/plugins/date.ts) for an example of a custom date adapter and how to access to the configuration.
+
+## Troubleshooting
+
+### `useDate()` — call methods on the instance, don't destructure them
+
+`useDate()` returns a Vuetify date adapter instance whose methods rely on `this`.
+Destructuring them detaches `this`, which throws during SSR (e.g.
+`Cannot read properties of undefined (reading 'locale')`). In dev the error is
+swallowed and the page falls back to client rendering, so it only surfaces after
+`nuxt build`/`nuxt generate`.
+
+```ts
+// ❌ loses `this` — crashes on the server
+const { date, format } = useDate()
+format(date(value), 'keyboardDate')
+
+// ✅ keep the instance, call methods on it
+const adapter = useDate()
+adapter.format(adapter.date(value), 'keyboardDate')
+```
+
+### date-fns base locale
+
+With the `date-fns` adapter the locale is resolved from
+`vuetifyOptions.locale.locale` (mapped to the matching `date-fns/locale` export)
+at build time. If it is unset or unknown the module falls back to `enUS` and logs
+a warning. Set `vuetifyOptions.locale.locale` to a supported Vuetify locale to
+choose the base locale.
+
+### Function-valued date formats are not supported
+
+`vuetifyOptions.date.formats` only accepts serializable
+`Intl.DateTimeFormatOptions`. The date configuration is statically serialized, so
+function formats cannot be expressed. Use a `custom` date adapter if you need them.

packages/vuetify-nuxt-module/src/types.ts

@@ -21,8 +21,13 @@ export interface DateOptions {
   adapter?: DateAdapter
   /**
    * Formats.
+   *
+   * Only serializable `Intl.DateTimeFormatOptions` values are supported here:
+   * the date configuration is statically serialized to a virtual module, so
+   * function-valued formats cannot be expressed (see #313, #331). Use a custom
+   * date adapter if you need function formats.
    */
-  formats?: Record<string, string>
+  formats?: Record<string, Intl.DateTimeFormatOptions>
   /**
    * Locales.
    *

packages/vuetify-nuxt-module/src/utils/date-fns-locale.ts

@@ -0,0 +1,47 @@
+/**
+ * Maps Vuetify locale codes to date-fns `locale` export names.
+ *
+ * Only divergent codes are listed; codes whose Vuetify name already equals the
+ * date-fns export name (e.g. `pt`, `de`, `srLatn`) pass through unchanged.
+ * date-fns has no bare `en` export — see #318.
+ */
+const VUETIFY_TO_DATE_FNS: Record<string, string> = {
+  en: 'enUS',
+  fa: 'faIR',
+  no: 'nb',
+  srCyrl: 'sr',
+  zhHans: 'zhCN',
+  zhHant: 'zhTW',
+}
+
+/**
+ * date-fns export names reachable from Vuetify's supported locale codes.
+ * Used to validate the resolved name so we never emit an import for a
+ * non-existent export (which would crash the build).
+ */
+const DATE_FNS_SUPPORTED = new Set<string>([
+  'af', 'ar', 'az', 'bg', 'ca', 'ckb', 'cs', 'da', 'de', 'el', 'enUS', 'es',
+  'et', 'faIR', 'fi', 'fr', 'he', 'hr', 'hu', 'id', 'it', 'ja', 'km', 'ko',
+  'lt', 'lv', 'nb', 'nl', 'pl', 'pt', 'ro', 'ru', 'sk', 'sl', 'sr', 'srLatn',
+  'sv', 'th', 'tr', 'uk', 'vi', 'zhCN', 'zhTW',
+])
+
+export interface ResolvedDateFnsLocale {
+  /** A date-fns `locale` export name guaranteed to exist. */
+  name: string
+  /** True when the input could not be resolved and `enUS` was substituted. */
+  fallback: boolean
+}
+
+export function resolveDateFnsLocaleName (code: string | undefined): ResolvedDateFnsLocale {
+  if (!code) {
+    return { name: 'enUS', fallback: true }
+  }
+
+  const candidate = VUETIFY_TO_DATE_FNS[code] ?? code
+  if (DATE_FNS_SUPPORTED.has(candidate)) {
+    return { name: candidate, fallback: false }
+  }
+
+  return { name: 'enUS', fallback: true }
+}

packages/vuetify-nuxt-module/src/vite/vuetify-date-configuration-plugin.ts

@@ -1,5 +1,6 @@
 import type { Plugin } from 'vite'
 import type { VuetifyNuxtContext } from '../utils/config'
+import { resolveDateFnsLocaleName } from '../utils/date-fns-locale'
 import { RESOLVED_VIRTUAL_VUETIFY_DATE_CONFIGURATION, VIRTUAL_VUETIFY_DATE_CONFIGURATION } from './constants'
 
 export function vuetifyDateConfigurationPlugin (ctx: VuetifyNuxtContext) {
@@ -27,22 +28,31 @@ export function dateConfiguration() {
 
         const { adapter: _adapter, ...newDateOptions } = ctx.vuetifyOptions.date ?? {}
 
-        return `${buildImports()}
+        let dateFnsLocale: string | undefined
+        if (ctx.dateAdapter === 'date-fns') {
+          const resolved = resolveDateFnsLocaleName(ctx.vuetifyOptions.locale?.locale)
+          dateFnsLocale = resolved.name
+          if (resolved.fallback) {
+            ctx.logger.warn(`[vuetify-nuxt-module] date-fns locale for "${ctx.vuetifyOptions.locale?.locale ?? '(unset)'}" not found, falling back to "enUS". Set "vuetifyOptions.locale.locale" to a supported locale.`)
+          }
+        }
+
+        return `${buildImports(dateFnsLocale)}
 export const enabled = true
 export const isDev = ${ctx.isDev}
 export const i18n = ${ctx.i18n}
 export const adapter = '${ctx.dateAdapter}'
 export function dateConfiguration() {
   const options = JSON.parse('${JSON.stringify(newDateOptions)}')
-  ${buildAdapter()}
+  ${buildAdapter(dateFnsLocale)}
   return options
 }
 `
       }
     },
   }
 
-  function buildAdapter () {
+  function buildAdapter (dateFnsLocale?: string) {
     if (ctx.dateAdapter === 'custom' || (ctx.dateAdapter === 'vuetify' && ctx.vuetifyGte('3.4.0'))) {
       return ''
     }
@@ -51,15 +61,14 @@ export function dateConfiguration() {
       return 'options.adapter = VuetifyDateAdapter'
     }
 
-    const locale = ctx.vuetifyOptions.locale?.locale ?? 'en'
     if (ctx.dateAdapter === 'date-fns') {
-      return `options.adapter = new Adapter({ locale: ${locale} })`
+      return `options.adapter = new Adapter({ locale: ${dateFnsLocale} })`
     }
 
     return 'options.adapter = Adapter'
   }
 
-  function buildImports () {
+  function buildImports (dateFnsLocale?: string) {
     if (ctx.dateAdapter === 'custom' || (ctx.dateAdapter === 'vuetify' && ctx.vuetifyGte('3.4.0'))) {
       return ''
     }
@@ -70,7 +79,7 @@ export function dateConfiguration() {
 
     const imports = [`import Adapter from '@date-io/${ctx.dateAdapter}'`]
     if (ctx.dateAdapter === 'date-fns') {
-      imports.push(`import { ${ctx.vuetifyOptions.locale?.locale ?? 'en'} } from 'date-fns/locale'`)
+      imports.push(`import { ${dateFnsLocale} } from 'date-fns/locale'`)
     }
 
     return imports.join('\n')

packages/vuetify-nuxt-module/test/date-configuration-plugin.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, it, vi } from 'vitest'
+import { RESOLVED_VIRTUAL_VUETIFY_DATE_CONFIGURATION } from '../src/vite/constants'
+import { vuetifyDateConfigurationPlugin } from '../src/vite/vuetify-date-configuration-plugin'
+
+function makeCtx (localeCode: string | undefined) {
+  return {
+    dateAdapter: 'date-fns',
+    isDev: false,
+    i18n: false,
+    vuetifyGte: () => true,
+    logger: { warn: vi.fn() },
+    vuetifyOptions: {
+      date: { adapter: 'date-fns' },
+      locale: localeCode === undefined ? {} : { locale: localeCode },
+    },
+  } as any
+}
+
+async function loadModule (ctx: any) {
+  const plugin = vuetifyDateConfigurationPlugin(ctx) as any
+  return (await plugin.load(RESOLVED_VIRTUAL_VUETIFY_DATE_CONFIGURATION)) as string
+}
+
+describe('vuetifyDateConfigurationPlugin date-fns locale', () => {
+  it('imports a valid date-fns export for a Vuetify code', async () => {
+    const ctx = makeCtx('en')
+    const code = await loadModule(ctx)
+    expect(code).toContain('import { enUS } from \'date-fns/locale\'')
+    expect(code).toContain('new Adapter({ locale: enUS })')
+    expect(code).not.toContain('import { en } from \'date-fns/locale\'')
+    expect(ctx.logger.warn).not.toHaveBeenCalled()
+  })
+
+  it('maps divergent codes (zhHans -> zhCN)', async () => {
+    const code = await loadModule(makeCtx('zhHans'))
+    expect(code).toContain('import { zhCN } from \'date-fns/locale\'')
+    expect(code).toContain('new Adapter({ locale: zhCN })')
+  })
+
+  it('passes through a locale that matches a date-fns export (de)', async () => {
+    const ctx = makeCtx('de')
+    const code = await loadModule(ctx)
+    expect(code).toContain('import { de } from \'date-fns/locale\'')
+    expect(code).toContain('new Adapter({ locale: de })')
+    expect(ctx.logger.warn).not.toHaveBeenCalled()
+  })
+
+  it('falls back to enUS and warns for an unset locale', async () => {
+    const ctx = makeCtx(undefined)
+    const code = await loadModule(ctx)
+    expect(code).toContain('import { enUS } from \'date-fns/locale\'')
+    expect(code).toContain('new Adapter({ locale: enUS })')
+    expect(ctx.logger.warn).toHaveBeenCalledExactlyOnceWith(expect.stringContaining('(unset)'))
+  })
+})

packages/vuetify-nuxt-module/test/date-fns-locale.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from 'vitest'
+import { resolveDateFnsLocaleName } from '../src/utils/date-fns-locale'
+
+describe('resolveDateFnsLocaleName', () => {
+  it('maps divergent Vuetify codes to date-fns export names', () => {
+    expect(resolveDateFnsLocaleName('en')).toEqual({ name: 'enUS', fallback: false })
+    expect(resolveDateFnsLocaleName('zhHans')).toEqual({ name: 'zhCN', fallback: false })
+    expect(resolveDateFnsLocaleName('zhHant')).toEqual({ name: 'zhTW', fallback: false })
+    expect(resolveDateFnsLocaleName('srCyrl')).toEqual({ name: 'sr', fallback: false })
+    expect(resolveDateFnsLocaleName('fa')).toEqual({ name: 'faIR', fallback: false })
+    expect(resolveDateFnsLocaleName('no')).toEqual({ name: 'nb', fallback: false })
+  })
+
+  it('passes through codes that already match a date-fns export', () => {
+    expect(resolveDateFnsLocaleName('pt')).toEqual({ name: 'pt', fallback: false })
+    expect(resolveDateFnsLocaleName('de')).toEqual({ name: 'de', fallback: false })
+    expect(resolveDateFnsLocaleName('srLatn')).toEqual({ name: 'srLatn', fallback: false })
+    expect(resolveDateFnsLocaleName('ar')).toEqual({ name: 'ar', fallback: false })
+    expect(resolveDateFnsLocaleName('da')).toEqual({ name: 'da', fallback: false })
+    expect(resolveDateFnsLocaleName('km')).toEqual({ name: 'km', fallback: false })
+  })
+
+  it('falls back to enUS for undefined or unknown codes', () => {
+    expect(resolveDateFnsLocaleName(undefined)).toEqual({ name: 'enUS', fallback: true })
+    expect(resolveDateFnsLocaleName('')).toEqual({ name: 'enUS', fallback: true })
+    expect(resolveDateFnsLocaleName('klingon')).toEqual({ name: 'enUS', fallback: true })
+  })
+})