Running Next.js Web Apps on IIS with HttpPlatformHandler

When Microsoft developed HttpPlatformHandler more than a decade ago to enable non-Microsoft web technologies on Windows/IIS, they didn’t know that one day

• Microsoft can embrace Linux in Azure
• Some Microsoft users stick to IIS with their Java/Python/Node.js/Go applications.

Thus, HttpPlatformHandler still plays an important role in the ecosystem and won’t go away easily. However, the landscape keeps evolving so this post tries to capture some latest changes on Next.js and show you how to proper set up everything needed and more critically how to troubleshoot if issues occur.

Prerequisites

To follow this post, you need to have the following software installed,

• Windows 10 or Windows Server 2016 or later (IIS 10 or later)
• HttpPlatformHandler v1.2 (from Microsoft) or v2.0 (from LeXtudio)

Basic Next.js Setup

First, use create-next-app to create a new Next.js project,

cd C:\
mkdir test-nextjs
cd test-nextjs
npx create-next-app@latest

If you choose every option by default, you get a simple Next.js web app in my-app folder.

Then to run this Next.js web apps locally, you know you can use npm run start command.

$ cd my-app
$ npm install
$ npm run build
$ npm run start

> [email protected] start
> next start

   ▲ Next.js 14.1.4
   - Local:        http://localhost:3000

 ✓ Ready in 749ms

Note that npm run start actually called next start, and by default the development server starts on port 3000.

HttpPlatformHandler Setup

When you want to host the web app on IIS, you just need to create a c:\test-nextjs\my-app\web.config as below and invoke next start properly,

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <system.webServer>
        <handlers>
            <add name="httpPlatformHandler" path="*" verb="*" modules="httpPlatformHandler" resourceType="Unspecified" requireAccess="Script" />
        </handlers>
        <httpPlatform stdoutLogEnabled="true" stdoutLogFile=".\node.log" startupTimeLimit="20" processPath="C:\Users\<user name>\AppData\Roaming\nvm\v18.20.1\node.exe" arguments=".\node_modules\next\dist\bin\next start">
            <environmentVariables>
                <environmentVariable name="PORT" value="%HTTP_PLATFORM_PORT%" />
                <environmentVariable name="NODE_ENV" value="Production" />
            </environmentVariables>
        </httpPlatform>
    </system.webServer>
</configuration>

Here I assume you use nvm to manage your Node.js versions and the active version is v18.20.1.

Now go to IIS Manager and create a new site to point to C:\test-nextjs\my-app folder with site binding on localhost port 8015. Then you can browse the site and see the Next.js web app running.

Troubleshooting

If you encounter any issues, you can check the troubleshooting tips I wrote in my previous post on Node.js.

Side Notes

You must run npm run build (wrapper over next build) to generate the artifacts before deploying to IIS. Besides, you can delete source files and only leave .next, node_modules and web.config in the deployment folder.

It is possible to delete more bits from node_modules to reduce the deployment size, but that’s another topic.

Dynamic Routes

IIS and HttpPlatformHandler support dynamic routes out of the box. You don’t need to do anything special to make them work.

Next.js as IIS Application under a Site

If you plan to host such a web app under a site as an IIS application (or subfolder, a term often used), you need to modify the basePath in your next.config.mjs file as below,

/** @type {import('next').NextConfig} */
const nextConfig = {
  basePath: '/AppWithNode1',
};

export default nextConfig;

where AppWithNode1 is the name of the IIS application.

Next.js on IIS Express

You can take a look at the new open source HttpPlatformHandler v2.0 from LeXtudio.

Other Languages on IIS?

If you want to learn more about HttpPlatformHandler and how to host other languages (Go/Python/Java) or frameworks (Nuxt.js), you can read this post.