Nuxt Luxon

Integrates the Luxon library with Nuxt 3, providing a simple and powerful way to work with dates and times in your Nuxt application.

• 📚  Docs
• ✨  Release Notes
• 🏀  Online playground

Features

• 🕰️ Easy DateTime formatting & parsing with Luxon
• 🧩 Predefined templates for common date formats
• 🌐 Global date/time utilities via composables
• 🎛️ Fully customizable via module options
• 📝 Fully typed with TypeScript support
• ✅ Fully tested for reliability

Installation

# Using npm
npm install nuxt-luxon

# Using yarn
yarn add nuxt-luxon

# Using pnpm
pnpm add nuxt-luxon

Setup

Add nuxt-luxon to the modules section of your nuxt.config.ts:

export default defineNuxtConfig({
  modules: [
    'nuxt-luxon', // Add the module here
  ],
  // Default options
  luxon: {
    input: {
      zone: 'utc',
      format: 'iso',
    },
    output: {
      format: 'short',
      zone: 'local',
      locale: 'client',
    },
    templates: {
      // Custom templates
    },
  },
})

Basic Usage

<template>
  <div>
    <!-- Format dates with predefined templates -->
    <p>{{ $luxon(new Date()) }}</p>
    <p>{{ $luxon(new Date(), 'full') }}</p>
    
    <!-- Custom format strings -->
    <p>{{ $luxon(new Date(), 'yyyy-MM-dd') }}</p>
  </div>
</template>

<script setup>
// Access utilities via the composable
const { $luxon, $lp } = useLuxon()

// Parse dates
const parsedDate = $lp('2025-05-10')

// Format dates
const formattedDate = $luxon(parsedDate, 'full')
</script>

Custom Templates

Templates can be used for both parsing and formatting dates. This is especially useful when you need consistent date formats across your application or when working with specific regional formats.

export default defineNuxtConfig({
  modules: ['nuxt-luxon'],
  luxon: {
    templates: {
      userDate: {
        zone: 'local',
        format: 'dd MM yyyy',
      },
      serverAMS: {
        zone: 'Europe/Amsterdam',
        format: 'dd-MM-yyyy HH:mm:ss',
      },
      client: {
        zone: 'local',
        format: 'short',
      },
    }
  }
})

Then you can use these templates for both parsing and formatting:

<script setup>
const { $luxon, $lp } = useLuxon()

// Parse a date using a template
const parsedDate = $lp('15 05 2025', 'userDate')

// Format a date using a template
const amsterdamTime = $luxon(new Date(), 'serverAMS')
</script>

API

Composable: useLuxon()

The main composable that provides formatting and parsing utilities:

const { $luxon, $lf, $lp } = useLuxon()

• $luxon / $lf - Format dates and times
• $lp - Parse dates and times

Formatting: $luxon(value, format?, inputFormat?)

Format a date value using the specified format:

// Basic usage with predefined formats
$luxon(new Date(), 'short')       // '5/10/25, 12:00 PM'
$luxon('2025-05-10', 'full')      // 'May 10, 2025 at 12:00 PM UTC'
$luxon(1715270400000, 'date')     // '5/10/2025'

// Custom format
$luxon(new Date(), 'yyyy-MM-dd')  // '2025-05-10'

// With input format
$luxon('05/10/2025', 'full', 'MM/dd/yyyy')

Parsing: $lp(value, format?)

Parse a value into a Luxon DateTime object:

// Parse from various formats
const date = $lp('2025-05-10')            // Parse ISO format
const fromUnix = $lp(1715270400, 'unix')  // Parse Unix timestamp (seconds)
const fromJs = $lp(new Date())            // Parse JS Date object

// Custom parsing
const custom = $lp('05/10/2025', 'MM/dd/yyyy')

Built-in Templates

The module includes several predefined format templates:

Name	Description	Example
full	Full date/time	May 10, 2025, 12:00 PM UTC
fulls	Full with seconds	May 10, 2025, 12:00:00 PM UTC
huge	Huge date/time	Saturday, May 10, 2025, 12:00 PM UTC
med	Medium date/time	May 10, 2025, 12:00 PM
short	Short date/time	5/10/25, 12:00 PM
date_full	Full date	May 10, 2025
date / date_short	Short date	5/10/2025
time	Simple time	12:00 PM
time24	24h time	12:00
And many more...

TypeScript Support

This module includes TypeScript definitions for all features.

License

MIT