Vercel’s Edge Functions to be used with Next.js (v12) announced today at the second Next.js Conference look pretty amazing. Now everyone building on Next.js using Vercel will have access to a super useful middleware.<\/p>\n
I’ll be deleting a bunch of infrastructure code and probably thousands of lines of code that I have now for things like basic auth and purchasing power parity. This is pretty amazing.<\/p>\n
Traditionally there are two ways to serve content, statically from a Content Delivery Network (CDN) close to the user for fast response times, or dynamically, with personalization configured at the server level on each request.<\/p>\n
When deciding on how you want to deliver content to your application visitors, you have to take into consideration the trade-offs that each of these two options offer.<\/p>\n
A static page will deliver the same content to all visitors, no matter where they are in the world, and it will be fast as it’s cached by the CDN. But this approach may not be viable if you want to deliver personalized content, depending on, for example, where a user is located in the world.<\/p>\n
To give your user a personalized experience, you can take advantage of server-side rendering to create dynamic content on each request to your sites pages. This will enable you to offer different content to people based on their location, authenticate them, or configure the language of your site.<\/p>\n
The drawback of this approach is that it can be slower. If the server processing the request is far away from the visitors origin, then the request can take time to complete, and the content may not be available to the user at the speed offered by serving purely static content.<\/p><\/blockquote>\n
What are Edge Functions?#<\/a><\/h3>\n
To achieve both speed and dynamism, you can use Edge Functions. They allow you to deliver content to your sites visitors with speed and personalization, are deployed globally by default on Vercel’s Edge Network, and have zero cold starts. They enable you to move server-side logic to the Edge, close to your visitors origin.<\/p>\n
To use Edge Functions, you can deploy Middleware. Middleware is code that executes before a request is processed. Depending on the incoming request, you can execute custom logic, rewrite, redirect, add headers and more, before returning a response.<\/p><\/blockquote>\n
Middleware (Vercel & Nextjs)#<\/a><\/h2>\n
The middleware function runs code before a request is completed, then based on the request, you can modify the response. It can be used for anything that shares logic between pages.<\/p>\n
It takes two parameters, request, and event. The request parameter is an extension of the native Request interface and has added methods and properties that include accessing cookies, getting geolocation from an IP Address, and user-agent info. You can import its type definition with
\nNextRequest.<\/p>\nIn addition, you can import the NextResponse API, which extends the native Response interface and lets you redirect, rewrite, cookies, and clear cookies.<\/p><\/blockquote>\n
Middleware use-cases#<\/a><\/h3>\n
\n\n\n\n
- Authentication<\/a><\/li>\n
- Bot Protection<\/a><\/li>\n
- Redirects<\/a><\/li>\n
- Browser Support<\/li>\n
- Feature Flags<\/a><\/li>\n
- A\/B Testing<\/a><\/li>\n
- Server-Side Analytics<\/li>\n
- Logging<\/li>\n<\/ul>\n<\/div>\n<\/div>\n<\/div>\n
<\/span>How to use Middleware<\/h3>\n
\nTo start using Middleware in your Next.js project, begin by upgrading to the latest Next.js version. The following steps will guide you through the process. Note that the below example uses TypeScript, though this is not<\/span> a requirement.<\/p>\n<\/blockquote>\n
\n
- \n
Install the latest version of
next<\/code>:<\/p>\nnpm install next@latest \r\n\r\n# or \r\nyarn upgrade next@latest\r\n<\/pre>\n<\/li>\n- \n
Next, create a
_middleware.ts<\/code> file under your\/pages<\/code> directory.<\/p>\n- \/pages\r\n _middleware.ts\r\n- package.json\r\n<\/pre>\n<\/li>\n- \n
Finally, create function in the
_middleware.ts<\/code> file.<\/p>\nexport default function middleware(req, ev) {\r\n return new Response({\r\n body: 'Hello, world!',\r\n });\r\n}<\/pre>\n<\/li>\n<\/ol>\nWhen you deploy your site, your Middleware will work out of the box<\/p>\n
<\/span>API<\/h3>\n
Middleware is created by using a
middleware<\/code> function that lives inside a_middleware<\/code> file. Its API is based upon the nativeFetchEvent<\/code><\/a>,Response<\/code><\/a>, andRequest<\/code><\/a> objects.<\/p>\nThese native Web API objects are extended to give you more control over how you manipulate and configure a response, based on the incoming requests.<\/p>\n
The function signature:<\/p>\n
import type { NextFetchEvent } from 'next\/server';\r\nimport type { NextRequest } from 'next\/server';\r\n\r\nexport type Middleware = (\r\n request: NextRequest,\r\n event: NextFetchEvent,\r\n) => Promise<Response | undefined> | Response | undefined;<\/pre>\nThe function can be a default export and as such, does not<\/span> have to be named
middleware<\/code>. Though this is a convention. Also, note that you only need to make the functionasync<\/code> if you are running asynchronous code.<\/p>\n\n\nWarning: <\/b><\/span>Edge Functions are currently in Beta. The API might change as we look to continually make improvements.<\/p>\n
<\/div>\n<\/div>\n<\/blockquote>\n<\/span>NextFetchEvent<\/h4>\n
The
NextFetchEvent<\/code> object extends the nativeFetchEvent<\/code><\/a> object, and includes thewaitUntil()<\/code><\/a> method.<\/p>\nThe
waitUntil()<\/code> method can be used to prolong the execution of the function, after the response has been sent. In practice this means that you can send a response, then continue the function execution if you have other background work to make.<\/p>\nAn example of why<\/em> you would use
waitUntil()<\/code> is integrations with logging tools such as Sentry<\/a> or DataDog<\/a>. After the response has been sent, you can send logs of response times, errors, API call durations or overall performance metrics.<\/p>\nThe
event<\/code> object is fully typed and can be imported fromnext\/server<\/code>.<\/p>\nimport { NextFetchEvent } from 'next\/server';<\/pre>\n<\/span>NextRequest<\/h4>\n
The
NextRequest<\/code> object is an extension of the nativeRequest<\/code><\/a> interface, with the following added methods and properties:<\/p>\n\n
cookies<\/code> – Has the cookies from theRequest<\/code><\/li>\nnextUrl<\/code> – Includes an extended, parsed, URL object that gives you access to Next.js specific properties such aspathname<\/code>,basePath<\/code>,trailingSlash<\/code> andi18n<\/code><\/li>\ngeo<\/code> – Has the geo location from theRequest<\/code>\n\n
geo.country<\/code> – The country code<\/li>\ngeo.region<\/code> – The region code<\/li>\ngeo.city<\/code> – The city<\/li>\ngeo.latitude<\/code> – The latitude<\/li>\ngeo.longitude<\/code> – The longitude<\/li>\n<\/ul>\n<\/li>\nip<\/code> – Has the IP address of theRequest<\/code><\/li>\nua<\/code> – Has the user agent<\/li>\n<\/ul>\nYou can use the
NextRequest<\/code> object as a direct replacement for the nativeRequest<\/code> interface, giving you more control over how you manipulate the request.<\/p>\n
NextRequest<\/code> is fully typed and can be imported fromnext\/server<\/code>.<\/p>\nimport type { NextRequest } from 'next\/server';<\/pre>\nExample using the
geo<\/code> object to check a requests location and blocking if it does not match an allowlist:<\/p>\nimport type { NextRequest } from 'next\/server';\r\n\r\n\/\/ Block GB, prefer US\r\nconst BLOCKED_COUNTRY = 'GB';\r\n\r\nexport function middleware(req: NextRequest) {\r\n const country = req.geo.country || 'US';\r\n\r\n \/\/ If the request is from the blocked country,\r\n \/\/ send back a response with a status code\r\n if (country === BLOCKED_COUNTRY) {\r\n return new Response('Blocked for legal reasons', { status: 451 });\r\n }\r\n\r\n \/\/ Otherwise, send a response with the country\r\n return new Response(`Greetings from ${country}, where you are not blocked.`);\r\n}<\/pre>\n<\/span>NextResponse<\/a><\/h4>\n
The
NextResponse<\/code> object is an extension of the nativeResponse<\/code><\/a> interface, with the following added methods and properties:<\/p>\n\n
cookies<\/code> – An object with the cookies in theResponse<\/code><\/li>\nredirect()<\/code> – Returns aNextResponse<\/code> with a redirect set<\/li>\nrewrite()<\/code> – Returns aNextResponse<\/code> with a rewrite set<\/li>\nnext()<\/code> – Returns aNextResponse<\/code> that will continue the middleware chain<\/li>\n<\/ul>\nAll methods above return a
NextResponse<\/code> object that only takes effect if it’s returned in the middleware function.<\/p>\n
NextResponse<\/code> is fully typed and can be imported fromnext\/server<\/code>.<\/p>\nimport { NextResponse } from 'next\/server';<\/pre>\nExample using
rewrite()<\/code> to rewrite the response to a different URL based on the request (browser) location:<\/p>\nimport { NextResponse } from 'next\/server';\r\nimport type { NextRequest } from 'next\/server';\r\n\r\nexport function middleware(req: NextRequest) {\r\n const country = req.geo.country?.toLowerCase() || 'us';\r\n\r\n req.nextUrl.pathname = `\/${country}`;\r\n return NextResponse.rewrite(req.nextUrl);\r\n}<\/pre>\n<\/span>Why does redirect() use 307 and 308?<\/h4>\n
\nWhen using
redirect()<\/code> you may notice that the status codes used are307<\/code> for a temporary redirect, and308<\/code> for a permanent redirect. While traditionally a302<\/code> was used for a temporary redirect, and a301<\/code> for a permanent redirect, many browsers changed the request method of the redirect, from aPOST<\/code> toGET<\/code> request when using a302<\/code>, regardless of the origins request method.<\/p>\n<\/blockquote>\nTaking the following example of a redirect from
\/users<\/code> to\/people<\/code>, if you make aPOST<\/code> request to\/users<\/code> to create a new user, and are conforming to a302<\/code> temporary redirect, the request method will be changed from aPOST<\/code> to aGET<\/code> request. This doesn’t make sense, as to create a new user, you should be making aPOST<\/code> request to\/people<\/code>, and not aGET<\/code> request.<\/p>\nThe introduction of the
307<\/code> status code means that the request method is preserved asPOST<\/code>.<\/p>\n\n
302<\/code> – Temporary redirect, will change the request method fromPOST<\/code> toGET<\/code><\/li>\n307<\/code> – Temporary redirect, will preserve the request method asPOST<\/code><\/li>\n<\/ul>\nThe
redirect()<\/code> method uses a307<\/code> by default, instead of a302<\/code> temporary redirect, meaning your requests will always<\/em> be preserved asPOST<\/code> requests.<\/p>\n<\/span>Middleware running order<\/h3>\n
If you do not<\/span> have any sub-directories, the Middleware will run on all routes within the
\/pages<\/code> directory and public files like\/favicon.ico<\/code>. The below example assumes you haveabout.ts<\/code> andteams.ts<\/code> routes.<\/p>\n- \/pages\r\n _middleware.ts # Will run on all routes under \/pages\r\n index.ts\r\n about.ts\r\n teams.ts\r\n- package.json<\/pre>\nIf you do<\/em> have sub-directories with nested routes, the Middleware will run in a top-down fashion. For example, if you have created
\/pages\/about\/_middleware.ts<\/code> and\/pages\/about\/team\/_middleware.ts<\/code>, the Middleware will run first<\/em> on\/pages\/about<\/code>, and then\/pages\/about\/team<\/code>. The below example shows how this works with a nested routing structure.<\/p>\n- \/pages\r\n index.ts\r\n - \/about\r\n _middleware.ts # Will run first\r\n about.ts\r\n - \/teams\r\n _middleware.ts # Will run second\r\n teams.ts\r\n- package.json<\/pre>\n<\/span>Runtime<\/h3>\n
Once the Middleware is deployed, it will run within a V8 Runtime<\/a> with a limited set of APIs. In development, the code will run in a sandbox environment that emulates the production runtime.<\/p>\n
Because of this, there are some restrictions to writing Middleware. These include:<\/p>\n
\n
- Native Node.js APIs are not supported<\/span>. For example, you can’t read or write to the filesystem<\/li>\n
- Node Modules can<\/em> be used, as long as they implement ES Modules and do not<\/span> use any native Node.js APIs. For example, you could use the
path-to-regexp<\/code> package to do path matches<\/li>\n- You can use ES Modules and split your code into reusable files that will then be bundled together when the application is built<\/li>\n
- Calling
require<\/code> directly is not allowed<\/span>. If you do use it, it might work when the import path can be statically resolved, but it is not recommended. Use ES Modules instead<\/li>\n<\/ul>\n<\/span>Runtime APIs<\/h3>\n
The following objects and APIs are available in the runtime:<\/p>\n
<\/span>Globals<\/a><\/h4>\n