Skip to content

Added docs on how to use with Nitro (v3) #208

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
MickL wants to merge 3 commits into from
Closed

Added docs on how to use with Nitro (v3) #208

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
79eb185
Added docs on how to use with Nitro (v3)
MickL Mar 28, 2026
1227e24
Updated Nitro example
MickL Mar 28, 2026
10986d9
Main readme should also note Nitro
MickL Mar 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ This repository is monorepo for the below packages:

| Package | Description | NPM |
| ---------------------------------------------- | -------------------------------------------------------- | ----------------------------------------------------------------- |
| [`@intlify/h3`](packages/h3/README.md) | Internationalization for [H3](https://h3.dev/) | [![npm version][npm-version-h3-src]][npm-version-h3-href] |
| [`@intlify/h3`](packages/h3/README.md) | Internationalization for [H3](https://h3.dev/) & [Nitro](https://nitro.build/) | [![npm version][npm-version-h3-src]][npm-version-h3-href] |
| [`@intlify/hono`](packages/hono/README.md) | Internationalization for [Hono](https://hono.dev/) | [![npm version][npm-version-hono-src]][npm-version-hono-href] |
| [`@intlify/elysia`](packages/elysia/README.md) | Internationalization for [Elysia](https://elysiajs.com/) | [![npm version][npm-version-elysia-src]][npm-version-elysia-href] |

Expand Down
39 changes: 39 additions & 0 deletions packages/h3/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -117,6 +117,45 @@ app.get('/', async event => {
createServer(toNodeListener(app)).listen(3000)
```

## Usage with Nitro

For usage with Nitro you need to create a plugin, e.g. `plugins/i18n.ts`:

```ts
import { definePlugin } from 'nitro';
import { defineIntlifyMiddleware } from '@intlify/h3';
import { i18nConfig } from '~/i18n/i18n.config';

export default definePlugin((nitroApp) => {
const { onRequest, onResponse } = defineIntlifyMiddleware({
locale: (event) => event.context.locale, // Grab locale from event context, always set by middleware
// You config,

@coderabbitai coderabbitai Bot Mar 28, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Fix typo in comment.

The comment contains a typo: "You config" should be "Your config".

✏️ Proposed fix 
-    // You config,
+    // Your config
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
// You config,
// Your config
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@packages/h3/README.md` at line 132, Typo in the README comment: replace the
phrase "You config" with "Your config" wherever that exact snippet appears (the
README comment string "You config") so the documentation reads correctly; update
the text in that comment block to "Your config".

});

nitroApp.hooks.hook('request', onRequest);
nitroApp.hooks.hook('response', onResponse);
});
```

In this example we detect the locale in a middleware so it is available in every event context, `middleware/detect-locale.ts`:

```ts
import { defineHandler, getValidatedQuery } from 'nitro/h3';

@coderabbitai coderabbitai Bot Mar 28, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🌐 Web query:

Does Nitro v3 export defineHandler and getValidatedQuery from nitro/h3?

💡 Result:

No, Nitro v3 does not define or export defineHandler and getValidatedQuery from a "nitro/h3" submodule. Nitro v3 exports defineHandler directly from the main "nitro" package for better type inference with H3Event, as shown in official v3 documentation. H3 utilities like getValidatedQuery (from h3 package) are not re-exported by Nitro but can be imported directly from "h3". The package.json exports "./h3" as a minimal proxy (20B file), but this does not include defineHandler or getValidatedQuery. Examples consistently import { defineHandler } from "nitro"; and reference H3 separately for advanced utilities.

Citations:

Correct the import statement for Nitro v3 compatibility.

The imports are incorrect for Nitro v3. defineHandler is not exported from 'nitro/h3' and should be imported from the main 'nitro' package. Similarly, getValidatedQuery should be imported from 'h3' directly, not from 'nitro/h3'.

Update line 143 to:

import { defineHandler } from 'nitro';
import { getValidatedQuery } from 'h3';
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@packages/h3/README.md` at line 143, Update the import to use Nitro v3
exports: replace the current combined import from 'nitro/h3' by importing
defineHandler from 'nitro' and getValidatedQuery from 'h3' so the file uses
defineHandler (from nitro) and getValidatedQuery (from h3) as separate imports.

import * as z from 'zod';

declare module 'nitro/h3' {
interface H3EventContext {
locale: Locale;
}
}
Comment on lines +146 to +150

@coderabbitai coderabbitai Bot Mar 28, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Missing type definition for Locale.

The Locale type is used in the module augmentation but is never imported or defined. This will cause a TypeScript compilation error.

🔧 Proposed fix to define the Locale type 
 import { defineHandler, getValidatedQuery } from 'nitro/h3';
 import * as z from 'zod';
 
+type Locale = 'en' | 'fr' | 'de' | 'es' | 'nl';
+
 declare module 'nitro/h3' {
   interface H3EventContext {
     locale: Locale;
   }
 }
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@packages/h3/README.md` around lines 146 - 150, The module augmentation uses
the type Locale in declare module 'nitro/h3' for interface H3EventContext but
Locale isn't defined or imported; fix by adding a proper type import or
definition for Locale (e.g., import type { Locale } from the module that exports
it) or declare a local type alias before the augmentation so the declaration for
H3EventContext: locale: Locale resolves; update the README snippet around the
declare module block to reference the correct source of Locale and ensure the
import uses "import type" to avoid runtime side-effects.


export default defineHandler(async (event) => {
const { locale } = await getValidatedQuery(event, z.object({ locale: z.enum(['en', 'fr', 'de', 'es', 'nl']).optional().default('en') }));
event.context.locale = locale;
});
```


## 🛠️ Custom locale detection

You can detect locale with your custom logic from current `H3Event`.
Expand Down