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.

• ✨  Release Notes

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

1npx nuxi@latest module add well-known

2. Add @zadigetvoltaire/nuxt-well-known to the modules section of nuxt.config.ts

1export default defineNuxtConfig({
2  modules: [
3    '@zadigetvoltaire/nuxt-well-known'
4  ],
5})

3. 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

1export default defineNuxtConfig({
2  ...
3  wellKnown: {
4    devtools: true,
5    securityTxt: {
6      disabled: false,
7      contacts: ['me@example.com'],
8      expires: new Date('2025-02-03')
9    },
10    changePassword: {
11      disabled: false,
12      redirectTo: 'https://example.com/password-recovery'
13    }
14  }
15  ...
16  runtimeConfig: {
17    public: {
18      wellKnown: {
19        devtools: true,
20        securityTxt: {
21          disabled: false,
22          contacts: ['me@example.com'],
23          expires: new Date('2025-02-03').toISOString() // ⚠️ in runtime config, `expires` should be a string
24        },
25        changePassword: {
26          disabled: false,
27          redirectTo: 'https://example.com/password-recovery'
28        }
29      }
30    }
31  }
32})

Module Options

1interface ModuleOptions {
2  /**
3   * Enable Nuxt Devtools integration
4   *
5   * @default true
6   */
7  devtools?: boolean
8  securityTxt?: SecurityTxtOptions,
9  changePassword?: ChangePasswordOptions,
10  contentUris?: ContentUriOptions[],
11}

Middlewares

security.txt

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

Model options:

1type SecurityTxtOptions = {
2  disabled?: boolean;
3  contacts: string[]; // https://www.rfc-editor.org/rfc/rfc9116#section-2.5.3
4  expires: string | Date; // https://www.rfc-editor.org/rfc/rfc9116#section-2.5.5
5  encryption?: string[]; // https://www.rfc-editor.org/rfc/rfc9116#section-2.5.4
6  acknowledgments?: string[]; // https://www.rfc-editor.org/rfc/rfc9116#section-2.5.1
7  preferredLanguages?: string[]; // https://www.rfc-editor.org/rfc/rfc9116#section-2.5.8
8  canonical?: string[]; // https://www.rfc-editor.org/rfc/rfc9116#section-2.5.2
9  policy?: string[]; // https://www.rfc-editor.org/rfc/rfc9116#section-2.5.7
10  hiring?: string[]; // https://www.rfc-editor.org/rfc/rfc9116#section-2.5.6
11}

change-password

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

1type ChangePasswordOptions = {
2  disabled?: boolean;
3  redirectTo: string;
4}

content-uris

With this middleware, you can generate uris with content

1type ContentUriOptions = {
2  disabled?: boolean;
3  path: string;
4  content: string;
5}

Example:

1// nuxt.config.ts
2export default defineNuxtConfig({
3  modules: [
4    '@zadigetvoltaire/nuxt-well-known',
5  ],
6  wellKnown: {
7    contentUris: [
8      { path: 'apple-developer-merchantid-domain-association', content: 'merchantid' },
9      { path: 'content-uri.txt', content: 'content-uri' },
10
11      // iOS Universal Links example
12      {
13        path: 'apple-app-site-association',
14        content: {
15          applinks: {
16            apps: [],
17            details: [
18              {
19                appID: 'TEAMID.BUNDLEID',
20                paths: ['*']
21              }
22            ]
23          }
24        }
25      },
26
27      // Android App Links example
28      {
29        path: 'assetlinks.json',
30        content: [
31          {
32            relation: ['delegate_permission/common.handle_all_urls'],
33            target: {
34              namespace: 'android_app',
35              package_name: 'com.netkosoft.beerswift',
36              sha256_cert_fingerprints: ['43:12:D4:27:D7:C4:14...']
37            }
38          }
39        ]
40      },
41    ]
42  }
43})

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

1# Install dependencies, prepare apps & run dev server
2make start
3
4# Run dev server
5pnpm dev
6
7# Develop with playground, with bundled client ui
8pnpm play:prod
9
10# Run ESLint
11pnpm lint
12
13# Run Vitest
14pnpm test
15pnpm 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

1pnpm release

---

© Zadig&Voltaire is a registered trademark of ZV FRANCE