Unverified Commit cd2324c8 authored by Rich Haines's avatar Rich Haines Committed by GitHub

Adds new userAgent docs to the next/server docs page (#37613)



This PR adds a new section for the `userAgent` helper in `next/server`.

## Bug

- [ ] Related issues linked using `fixes #number`
- [ ] Integration tests added
- [ ] Errors have helpful link attached, see `contributing.md`

## Feature

- [ ] Implements an existing feature request or RFC. Make sure the feature request has been accepted for implementation before opening a PR.
- [ ] Related issues linked using `fixes #number`
- [ ] Integration tests added
- [x] Documentation added
- [ ] Telemetry added. In case of a feature if it's used or not.
- [ ] Errors have helpful link attached, see `contributing.md`

## Documentation / Examples

- [ ] Make sure the linting passes by running `pnpm lint`
- [ ] The examples guidelines are followed from [our contributing doc](https://github.com/vercel/next.js/blob/canary/contributing.md#adding-examples)
parent b8c61a9c
...@@ -14,7 +14,7 @@ These native Web API objects are extended to give you more control over how you ...@@ -14,7 +14,7 @@ These native Web API objects are extended to give you more control over how you
The function signature is defined as follows: The function signature is defined as follows:
```ts ```typescript
type NextMiddlewareResult = NextResponse | Response | null | undefined type NextMiddlewareResult = NextResponse | Response | null | undefined
type NextMiddleware = ( type NextMiddleware = (
...@@ -25,7 +25,7 @@ type NextMiddleware = ( ...@@ -25,7 +25,7 @@ type NextMiddleware = (
It can be imported from `next/server` with the following: It can be imported from `next/server` with the following:
```ts ```typescript
import type { NextMiddleware } from 'next/server' import type { NextMiddleware } from 'next/server'
``` ```
...@@ -38,14 +38,13 @@ The `NextRequest` object is an extension of the native [`Request`](https://devel ...@@ -38,14 +38,13 @@ The `NextRequest` object is an extension of the native [`Request`](https://devel
- `cookies` - A [Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) with cookies from the `Request` - `cookies` - A [Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) with cookies from the `Request`
- `nextUrl` - Includes an extended, parsed, URL object that gives you access to Next.js specific properties such as `pathname`, `basePath`, `trailingSlash` and `i18n` - `nextUrl` - Includes an extended, parsed, URL object that gives you access to Next.js specific properties such as `pathname`, `basePath`, `trailingSlash` and `i18n`
- `ip` - Has the IP address of the `Request` - `ip` - Has the IP address of the `Request`
- `ua` - Has the user agent
- `geo` - (Optional) Has the geo location from the `Request`, provided by your hosting platform - `geo` - (Optional) Has the geo location from the `Request`, provided by your hosting platform
You can use the `NextRequest` object as a direct replacement for the native `Request` interface, giving you more control over how you manipulate the request. You can use the `NextRequest` object as a direct replacement for the native `Request` interface, giving you more control over how you manipulate the request.
`NextRequest` is fully typed and can be imported from `next/server`. `NextRequest` is fully typed and can be imported from `next/server`.
```ts ```typescript
import type { NextRequest } from 'next/server' import type { NextRequest } from 'next/server'
``` ```
...@@ -57,7 +56,7 @@ The `waitUntil()` method can be used to prolong the execution of the function, a ...@@ -57,7 +56,7 @@ The `waitUntil()` method can be used to prolong the execution of the function, a
The `event` object is fully typed and can be imported from `next/server`. The `event` object is fully typed and can be imported from `next/server`.
```ts ```typescript
import type { NextFetchEvent } from 'next/server' import type { NextFetchEvent } from 'next/server'
``` ```
...@@ -69,32 +68,23 @@ The `NextResponse` class extends the native [`Response`](https://developer.mozil ...@@ -69,32 +68,23 @@ The `NextResponse` class extends the native [`Response`](https://developer.mozil
Public methods are available on an instance of the `NextResponse` class. Depending on your use case, you can create an instance and assign to a variable, then access the following public methods: Public methods are available on an instance of the `NextResponse` class. Depending on your use case, you can create an instance and assign to a variable, then access the following public methods:
- `cookies` - A [Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) with the cookies in the `Response` - `cookies` - The `Cookies` API extends [Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map), including methods like [entries](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map/entries) and [values](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map/entries).
```ts ```typescript
import { NextResponse } from 'next/server' export function middleware() {
import type { NextRequest } from 'next/server' const response = new NextResponse()
// set a cookie
export function middleware(request: NextRequest) { response.cookies.set('vercel', 'fast')
// create an instance of the class to access the public methods. This uses `next()`, // set another cookie with options
// you could use `redirect()` or `rewrite()` as well response.cookies.set('nextjs', 'awesome', { path: '/test' })
let response = NextResponse.next() // get all the details of a cookie
// get the cookies from the request const { value, options } = response.cookies.getWithOptions('vercel')
let cookieFromRequest = request.cookies.get('my-cookie') console.log(value) // => 'fast'
// set the `cookie` console.log(options) // => { Path: '/test' }
response.cookies.set('hello', 'world') // deleting a cookie will mark it as expired
// set the `cookie` with options response.cookies.delete('vercel')
const cookieWithOptions = response.cookies.set('hello', 'world', { // clear all cookies means mark all of them as expired
path: '/', response.cookies.clear()
maxAge: 60 * 60 * 24 * 7,
httpOnly: true,
sameSite: 'strict',
domain: 'example.com',
})
// clear the `cookie`
response.clearCookie('hello')
return response
} }
``` ```
...@@ -106,7 +96,7 @@ The following static methods are available on the `NextResponse` class directly: ...@@ -106,7 +96,7 @@ The following static methods are available on the `NextResponse` class directly:
- `rewrite()` - Returns a `NextResponse` with a rewrite set - `rewrite()` - Returns a `NextResponse` with a rewrite set
- `next()` - Returns a `NextResponse` that will continue the middleware chain - `next()` - Returns a `NextResponse` that will continue the middleware chain
```ts ```typescript
import { NextResponse } from 'next/server' import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server' import type { NextRequest } from 'next/server'
...@@ -127,7 +117,7 @@ All methods above return a `NextResponse` object that only takes effect if it's ...@@ -127,7 +117,7 @@ All methods above return a `NextResponse` object that only takes effect if it's
`NextResponse` is fully typed and can be imported from `next/server`. `NextResponse` is fully typed and can be imported from `next/server`.
```ts ```typescript
import { NextResponse } from 'next/server' import { NextResponse } from 'next/server'
``` ```
...@@ -137,7 +127,7 @@ In order to set the `cookie` _before_ a redirect, you can create an instance of ...@@ -137,7 +127,7 @@ In order to set the `cookie` _before_ a redirect, you can create an instance of
Note that there is a [Chrome bug](https://bugs.chromium.org/p/chromium/issues/detail?id=696204) which means the entire redirect chain **must** be from the same origin, if they are from different origins, then the `cookie` might be missing until a refresh. Note that there is a [Chrome bug](https://bugs.chromium.org/p/chromium/issues/detail?id=696204) which means the entire redirect chain **must** be from the same origin, if they are from different origins, then the `cookie` might be missing until a refresh.
```ts ```typescript
import { NextResponse } from 'next/server' import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server' import type { NextRequest } from 'next/server'
...@@ -148,6 +138,45 @@ export function middleware(req: NextRequest) { ...@@ -148,6 +138,45 @@ export function middleware(req: NextRequest) {
} }
``` ```
## userAgent
The `userAgent` helper allows you to interact with the user agent object from the request. It is abstracted from the native `Request` object, and is an opt in feature. It has the following properties:
- `isBot`: Whether the request comes from a known bot
- `browser`
- `name`: The name of the browser, or `undefined`
- `version`: The version of the browser, determined dynamically, or `undefined`
- `device`
- `model`: The model of the device, determined dynamically, or `undefined`
- `type`: The type of the browser, can be one of the following values: `console`, `mobile`, `tablet`, `smarttv`, `wearable`, `embedded`, or `undefined`
- `vendor`: The vendor of the device, determined dynamically, or `undefined`
- `engine`
- `name`: The name of the browser engine, could be one of the following values: `Amaya`, `Blink`, `EdgeHTML`, `Flow`, `Gecko`, `Goanna`, `iCab`, `KHTML`, `Links`, `Lynx`, `NetFront`, `NetSurf`, `Presto`, `Tasman`, `Trident`, `w3m`, `WebKit` or `undefined`
- `version`: The version of the browser engine, determined dynamically, or `undefined`
- `os`
- `name`: The name of the OS, could be `undefined`
- `version`: The version of the OS, determined dynamically, or `undefined`
- `cpu`
- `architecture`: The architecture of the CPU, could be one of the following values: `68k`, `amd64`, `arm`, `arm64`, `armhf`, `avr`, `ia32`, `ia64`, `irix`, `irix64`, `mips`, `mips64`, `pa-risc`, `ppc`, `sparc`, `sparc64` or `undefined`
`userAgent` is fully typed and can be imported from `next/server`:
```typescript
import { userAgent } from 'next/server'
```
```typescript
import { NextRequest, NextResponse, userAgent } from 'next/server'
export function middleware(request: NextRequest) {
const url = request.nextUrl
const { device } = userAgent(request)
const viewport = device.type === 'mobile' ? 'mobile' : 'desktop'
url.searchParams.set('viewport', viewport)
return NextResponse.rewrites(url)
}
```
### Why does redirect use 307 and 308? ### Why does redirect use 307 and 308?
When using `redirect()` you may notice that the status codes used are `307` for a temporary redirect, and `308` for a permanent redirect. While traditionally a `302` was used for a temporary redirect, and a `301` for a permanent redirect, many browsers changed the request method of the redirect, from a `POST` to `GET` request when using a `302`, regardless of the origins request method. When using `redirect()` you may notice that the status codes used are `307` for a temporary redirect, and `308` for a permanent redirect. While traditionally a `302` was used for a temporary redirect, and a `301` for a permanent redirect, many browsers changed the request method of the redirect, from a `POST` to `GET` request when using a `302`, regardless of the origins request method.
...@@ -171,7 +200,7 @@ If you want to cause a `GET` response to a `POST` request, use `303`. ...@@ -171,7 +200,7 @@ If you want to cause a `GET` response to a `POST` request, use `303`.
Any variables in `process.env` must be accessed directly, and **cannot** be destructured: Any variables in `process.env` must be accessed directly, and **cannot** be destructured:
```ts ```typescript
// Accessed directly, and not destructured works. process.env.NODE_ENV is `"development"` or `"production"` // Accessed directly, and not destructured works. process.env.NODE_ENV is `"development"` or `"production"`
console.log(process.env.NODE_ENV) console.log(process.env.NODE_ENV)
// This will not work // This will not work
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment