Fixing 404 Errors on Vercel: How to Deploy a TypeScript Express.js Node.js App

Vercel is widely popular for deploying applications, and while it's quite simple to deploy frontend apps or basic Node.js applications, deploying backend apps with TypeScript and Express.js can be a bit tricky. During a recent deployment of a TypeScript Express.js app on Vercel, I encountered a 404 error that I couldn't find a proper solution for—especially since I was using module aliases for the backend. However, after considerable effort, I managed to resolve the issue, and in this article, I will guide you on how to seamlessly deploy your TypeScript Express.js app on Vercel.

Common Issue: 404 Errors on Deployment

Sometimes, even after deploying your app on Vercel, you may still encounter a 404 error. This could happen due to several reasons such as incorrect configurations, API routes not being recognized, or module alias issues. Let’s walk through how to avoid these issues and deploy your app smoothly.

---

Step 1: Initialize a TypeScript Express.js Project

First, you need to initialize your TypeScript Express.js project.

1. Initialize the project:

    npm init -y
   

2. Install dependencies for TypeScript and Express:

    npm install express
    npm install typescript @types/node @types/express --save-dev
   

3. Set up tsconfig.json:
   This file will configure how TypeScript compiles your project.

   Create a tsconfig.json file:

    {
      "compilerOptions": {
        "target": "ES2020",
        "module": "commonjs",
        "esModuleInterop": true,
        "allowSyntheticDefaultImports": true,
        "noImplicitAny": true,
        "moduleResolution": "node",
        "sourceMap": true,
        "outDir": "dist",
        "baseUrl": ".",
        "paths": {
          "*": [
            "node_modules/*",
            "src/types/*"
          ]
        }
      }
    }
   

4. Add mandatory scripts in package.json: In your package.json, you’ll need to add the following scripts:

    {
      "scripts": {
        "start": "node dist/server.js",
        "build": "tsc",
        "dev": "nodemon src/server.ts"
      }
    }
   

---

Step 2: Set Up the Vercel Configuration

Now, let's configure the Vercel deployment.

1. Create a vercel.json file:
   This configuration file tells Vercel how to build and route your app. Here's an example configuration:

    {
      "version": 2,
      "builds": [
        {
          "src": "dist/server.js",
          "use": "@vercel/node"
        }
      ],
      "routes": [
        {
          "src": "/(.*)",
          "dest": "dist/server.js"
        }
      ],
      "buildCommand": "npm run build",
      "outputDirectory": "dist"
    }
   

   Explanation:

   • builds: Defines the build process and points to the dist/server.js file.

   • routes: Routes incoming requests to dist/server.js.

   • buildCommand: The command that Vercel uses to build the app (npm run build).

   • outputDirectory: Specifies that Vercel should look in the dist directory for the final build output.

---

Step 3: Handle Module Aliases

//package.json
{
    ...,
    "_moduleAliases": {
        "@": "dist"
    },
    ...
}

If you're using module aliases, especially with paths like "@": "dist", Vercel may not recognize them during the build process. To resolve this:

1. Install tsc-alias: This tool helps decouple the aliases during the build process.

    npm install tsc-alias --save-dev
   

2. Update the build script in package.json to use tsc-alias:

    {
      "scripts": {
        "build": "tsc && tsc-alias"
      }
    }
   

   This ensures that after TypeScript compiles your project, tsc-alias will replace any aliases with the correct paths.

---

Step 4: Deploying to Vercel

Once your project is set up, it's time to deploy it to Vercel.

1. Push your code to GitHub:
   Make sure your project is pushed to a GitHub repository.

2. Link your GitHub project with Vercel:

   • Go to the Vercel dashboard.

   • Click on “New Project” and import your GitHub repository.

   • Set “Framework Preset” to “Other”.

3. Deployment:

   • After linking your project, Vercel will begin the build process and deploy the app.

   • If everything is configured correctly, you should be able to access your app at the provided Vercel URL.

---

Step 5: Troubleshooting 404 Errors

Sometimes, you may still encounter 404 errors after deployment. Here are a few things to check:

1. Incorrect File Paths:
   Ensure that the file paths are correctly specified in your vercel.json file, especially the entry point (dist/server.js).

2. Missing API Endpoints:
   Verify that all your API routes are properly defined and exported from your server.ts file.

3. Serverless Function Issues:
   Vercel treats each API endpoint as a serverless function. Ensure that the structure of your app matches the expected serverless function format (i.e., files in the /api directory).

4. TypeScript Build Errors:
   If you made any changes to the TypeScript configuration, run npm run build locally to check for any errors before deploying.

---

Conclusion

Deploying a TypeScript Express.js app on Vercel can be a smooth experience once you understand the configuration and handling of module aliases. In this article, we covered the essential steps to set up your TypeScript Express.js app, handle build issues, and deploy it to Vercel while fixing common 404 errors. By following this guide, you should be able to deploy your app seamlessly to Vercel and ensure that it works as expected.

Happy deploying!