well-known

A Nuxt.js module to add well-known URIs using middlewares

npm versionnpm downloadsLicenseNuxt

Nuxt Well-Known

Nuxt (v3.x) module to handle .well-known URIs with middlewares

See https://www.iana.org/assignments/well-known-uris/well-known-uris.xhtml

⚠️ Only tested with SSR mode (not SSG and CSR)

Nuxt Well-Known module is integrated with the Nuxt Devtools.

Well-Known URIs Supported

  1. security.txt
  2. change-password
  3. Dynamic routes with content: content-uris

Quick Setup

  1. Add @zadigetvoltaire/nuxt-well-known dependency to your project
# Using pnpm
pnpm add -D @zadigetvoltaire/nuxt-well-known
# Using yarn
yarn add --dev @zadigetvoltaire/nuxt-well-known
# Using npm
npm install --save-dev @zadigetvoltaire/nuxt-well-known
  1. Add @zadigetvoltaire/nuxt-well-known to the modules section of nuxt.config.ts
export default defineNuxtConfig({
modules: [
'@zadigetvoltaire/nuxt-well-known'
],
})
  1. Add configuration in nuxtConfig.wellKnown or in nuxtConfig.runtimeConfig.public.wellKnown

This module supports 2 ways of configuration:

  • Directly in key wellKnown of the Nuxt config
  • In public runtimeConfig: useful to override the config with environment variables and handle multiple environments
export default defineNuxtConfig({
...
wellKnown: {
devtools: true,
securityTxt: {
disabled: false,
contacts: ['me@example.com'],
expires: new Date('2025-02-03')
},
changePassword: {
disabled: false,
redirectTo: 'https://example.com/password-recovery'
}
}
...
runtimeConfig: {
public: {
wellKnown: {
devtools: true,
securityTxt: {
disabled: false,
contacts: ['me@example.com'],
expires: new Date('2025-02-03').toISOString() // ⚠️ in runtime config, `expires` should be a string
},
changePassword: {
disabled: false,
redirectTo: 'https://example.com/password-recovery'
}
}
}
}
})

Module Options

interface ModuleOptions {
/**
* Enable Nuxt Devtools integration
*
* @default true
*/
devtools?: boolean
securityTxt?: SecurityTxtOptions,
changePassword?: ChangePasswordOptions,
contentUris?: ContentUriOptions[],
}

Middlewares

security.txt

This middleware will generate a security.txt file available under /.well-known/security.txt URI.

Model options:

type SecurityTxtOptions = {
disabled?: boolean;
contacts: string[]; // https://www.rfc-editor.org/rfc/rfc9116#section-2.5.3
expires: string | Date; // https://www.rfc-editor.org/rfc/rfc9116#section-2.5.5
encryption?: string[]; // https://www.rfc-editor.org/rfc/rfc9116#section-2.5.4
acknowledgments?: string[]; // https://www.rfc-editor.org/rfc/rfc9116#section-2.5.1
preferredLanguages?: string[]; // https://www.rfc-editor.org/rfc/rfc9116#section-2.5.8
canonical?: string[]; // https://www.rfc-editor.org/rfc/rfc9116#section-2.5.2
policy?: string[]; // https://www.rfc-editor.org/rfc/rfc9116#section-2.5.7
hiring?: string[]; // https://www.rfc-editor.org/rfc/rfc9116#section-2.5.6
}

change-password

This middleware will redirect requests of /.well-known/change-password to the configured target URL.

type ChangePasswordOptions = {
disabled?: boolean;
redirectTo: string;
}

content-uris

With this middleware, you can generate uris with content

type ContentUriOptions = {
disabled?: boolean;
path: string;
content: string;
}

Example:

// nuxt.config.ts
export default defineNuxtConfig({
modules: [
'@zadigetvoltaire/nuxt-well-known',
],
wellKnown: {
contentUris: [
{ path: 'apple-developer-merchantid-domain-association', content: 'merchantid' },
{ path: 'content-uri.txt', content: 'content-uri' }
]
}
})

Will render:

  • https://example.com/.well-known/apple-developer-merchantid-domain-association --> merchantid
  • https://example.com/.well-known/content-uri.txt --> content-uri

That's it! You can now use Nuxt Well-Known in your Nuxt app ✨

Contributing

# Install dependencies, prepare apps & run dev server
make start
# Run dev server
pnpm dev
# Develop with playground, with bundled client ui
pnpm play:prod
# Run ESLint
pnpm lint
# Run Vitest
pnpm test
pnpm test:watch

Release new version

  1. Execute release command

⚠ This command should be executed only on the main branch

This command will:

  • Generate the CHANGELOG.md and push it with a release commit
  • Bump the package version
  • Create and push the new tag
  • Create a GitHub release to trigger the library publish pipeline
pnpm release

© Zadig&Voltaire is a registered trademark of ZV FRANCE