Easier way to run SSR websites (Node.js) on Windows IIS

Sometimes you have no choice, but to use less-than-ideal tech stack the team familiar with, or perhaps the only tech stack the team knows.

It begins as...

Here, I have a website. While it is a simple website, but does require server-side rendering (SSR) functionality. It may not pose an issue to any modern web developer, but it becomes one when handing off to old-school Windows engineer.

Before it sounds like a complaint, it's worth noting that modern tech stacks and practices are generally cross-platform. There's no reason why I can't run my website under Windows IIS, regardless of how cumbersome it might be to hook up with the JavaScript runtime.

After conducting research and experimenting with FastCGI and URL Rewrite, I discovered another convenient module that seems to be under-discussed.

I'm not an expert in Windows IIS, so I can't speak to the differences under the hood, but from my experience, I find that httpPlatformHandler is easier to setup.

Before I share the walkthrough of IIS setup, we'll need the website running properly under JavaScript runtime (Node.js in this case).

Setup httpPlatformHandler

1. Download and install httpPlatformHandler from Microsoft.

2. Open the site under IIS, and navigate to: Handler Mapping > Add Module Mapping...

3. Enter the follow:

   Key	Value
   Request path	*
   Module	httpPlatformHandler

4. Uncheck the "Request Restrictions..."

5. Navigate to: Configuration Editor > system.webService/httpPlatform

6. Enter the follow:

   Key	Value
   arguments	.\.output\server\index.mjs
   processPath	C:\Program Files\nodejs\node.exe
   starupTimeLimit	20

7. Under the environmentVariables, enter the following:

   Key	Value
   PORT	%HTTP_PLATFORM_PORT%
   NODE_ENV	Production

🎉 Let's it. As of my understanding, all http request will now be handled by Node instead.

The final web.config should looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <system.webServer>
        <handlers>
            <add 
                name="httpPlatformHandler" 
                path="*" 
                verb="*" 
                modules="httpPlatformHandler" 
                resourceType="Unspecified" 
                requireAccess="Script" 
            />
        </handlers>
        <httpPlatform 
            processPath="C:\Program Files\nodejs\node.exe" 
            arguments=".\.output\server\index.mjs" 
            startupTimeLimit="20" 
            stdoutLogEnabled="true" 
            stdoutLogFile=".\node.log"
        >
            <environmentVariables>
                <environmentVariable 
                    name="PORT" 
                    value="%HTTP_PLATFORM_PORT%" 
                />
                <environmentVariable 
                    name="NODE_ENV" 
                    value="Production" 
                />
            </environmentVariables>
        </httpPlatform>
    </system.webServer>
</configuration>