How to Create a Next.js Custom Server with TypeScript

Next.js is a popular React framework that simplifies building server-side rendered applications. However, there are scenarios where the built-in server doesn't meet your needs. That's where creating a Next.js custom server with TypeScript comes in handy. Whether you're adding middleware, handling custom routes, or integrating third-party services, a custom server provides flexibility and control.

This blog walks you through the process of setting up a custom server using TypeScript, ensuring a smooth development experience and compatibility with production environments.

Why Use a Custom Server?

By default, Next.js serves pages efficiently with its built-in functionality. However, there are scenarios where a custom server is beneficial:

• Adding custom middlewares

• Handling APIs or routes outside Next.js's built-in capabilities

• Performing custom authentication

• Supporting features not covered by the default server

Prerequisites for Setting Up a Custom Server

Before diving into the implementation, ensure the following tools and knowledge are in place:

1. Node.js installed on your machine

2. Familiarity with TypeScript and JavaScript

3. A basic understanding of Next.js

Step 1: Create Your Project

First, you'll need to initialize a Next.js project. If you haven't already:

Copy
npx create-next-app@latest --typescript custom-server-example
cd custom-server-example

This creates a TypeScript-ready Next.js project.

Step 2: Install Required Dependencies

To set up a custom server, you'll need Express.js as the core server framework. Install it and other required dependencies:

Copy
npm install express
npm install --save-dev @types/express

This ensures TypeScript understands the types used in your server code.

Step 3: Configure a Custom Server Entry Point

Next, define your server entry point. In the root of your project, create a file named server.ts. This will act as the starting point for your custom server.

Copy
import express, { Request, Response } from "express";
import { createServer } from "http";
import next from "next";

const dev = process.env.NODE_ENV !== "production";
const app = next({ dev });
const handle = app.getRequestHandler();

const server = express();

app.prepare().then(() => {
  server.all("*", (req: Request, res: Response) => {
    return handle(req, res);
  });

  const httpServer = createServer(server);
  httpServer.listen(3000, () => {
    console.log("Custom server listening on http://localhost:3000");
  });
});

Key Points:

• We import express and http to build a robust server.

• The next function initializes the Next.js application.

• The handle function processes all requests through Next.js.

Step 4: Update package.json Scripts

Update your scripts to include a command for starting the custom server. In package.json, modify the scripts section:

Copy
"scripts": {
  "dev": "ts-node server.ts",
  "build": "next build",
  "start": "NODE_ENV=production node server.js"
}

Here, the dev script runs the ts-node server, enabling TypeScript support.

Step 5: Compile TypeScript for Production

For production, you need to compile your TypeScript code to JavaScript. Update your tsconfig.json to include the following:

Run:

This generates compiled JavaScript files in the dist directory.

Step 6: Handle Errors and Debugging

To ensure your custom server is robust, include error handling. Wrap your server initialization in a try-catch block to capture potential errors.

This ensures any unexpected errors during the server startup are logged and addressed.

Step 7: Test the Custom Server Locally

Start the server in development mode:

Visit http://localhost:3000 to see your application running on the custom server.

Step 8: Prepare for Production

For production, use the following steps:

1. Build your Next.js application:

2. Start the custom server:

3. Access your app via the URL where the server is deployed.

Troubleshooting Common Errors

1. TypeScript Errors: Ensure your tsconfig.json is properly configured to recognize all server-related types.

2. Deployment Issues: Always test your server code locally before deploying to a production environment.

3. Runtime Errors: Use console.log for debugging during the development phase and ensure your server has comprehensive error handling.

The Bottom Line!

Building a Next.js custom server with TypeScript offers unparalleled flexibility for your applications. By following this guide, you can integrate custom middlewares, manage APIs, and tailor your server to meet specific requirements.

Whether you're running in development or production, this setup ensures a seamless experience for both the client side and the backend. With TypeScript ensuring type safety and ts-node streamlining development, you're equipped to handle any challenge that arises.

Start building your custom server today and take control of your application's server-side capabilities!

{
  "compilerOptions": {
    "outDir": "./dist",
    "module": "commonjs",
    "target": "es6",
    "strict": true
  },
  "include": ["server.ts"]
}

npx tsc

try {
  app.prepare().then(() => {
    server.all("*", (req, res) => handle(req, res));
    httpServer.listen(3000, () => console.log("Server running..."));
  });
} catch (error) {
  console.error("Error starting server:", error);
}

npm run dev

npm run build

npm run start