How to Deploy a Hono.js Application to Production: Complete Guide for the castrozan/tcc Repository

To deploy a Hono.js application to production, compile TypeScript to the dist/ directory using npm run build, install only production dependencies with npm ci --omit=dev, configure required environment variables in a .env file, and execute the compiled server with node dist/index.js or run it inside a Docker container.

The castrozan/tcc repository provides two example services—Professionals Dummy App and Equipments Dummy App—built with TypeScript, hono, and chanfana. Deploying these Hono.js applications to production involves building the source code, setting runtime configuration, and serving the compiled output through Node.js or a containerized environment.

Build the TypeScript Application

Before deploying, you must compile the TypeScript source into JavaScript and install only the dependencies required for runtime.

1. Clone the repository and navigate to the target application directory:

git clone https://github.com/castrozan/tcc.git
cd tcc/professionals-dummy-app

# Or: cd tcc/equipments-dummy-app

2. Install production dependencies exclusively to reduce the deployment footprint:

npm ci --omit=dev

3. Compile the TypeScript sources using the build script defined in package.json:

npm run build

This command executes tsc and emits the compiled JavaScript to the dist/ folder, creating the executable artifacts needed for production.

Configure Production Environment Variables

The applications rely on environment variables loaded via dotenv. Create a .env file in the project root (ensure this file is excluded from version control) to define runtime settings.

The minimal required variable is the listening port:

PORT=3000

If connecting to a database, include the connection string:

DATABASE_URL=postgres://user:pass@host:5432/dbname

In src/infrastructure/web/open-api/server.ts, the application initializes environment loading before starting the Hono server:

import { config } from 'dotenv';
config(); // Loads .env and populates process.env

Run the Production Server

Once built and configured, launch the application using one of the following methods.

Direct Node.js Execution

Execute the compiled entry point directly with Node.js, setting NODE_ENV to production:

NODE_ENV=production node dist/index.js

The file dist/index.js is the compiled output of src/index.ts, which initializes and starts the HTTP server.

Process Manager Deployment with PM2

For long-running production services, use PM2 to manage the process:

npm i -g pm2
pm2 start dist/index.js --name professionals-app --env production
pm2 save

This configuration persists the process across system reboots and provides logging and monitoring capabilities.

Containerized Deployment with Docker

For immutable deployments, adapt the multi-stage Dockerfile pattern found in mcp-openapi-server/Dockerfile:

FROM node:22-alpine AS builder

WORKDIR /app
COPY package*.json tsconfig.json ./
COPY src ./src

RUN npm ci --omit=dev
RUN npm run build

FROM node:22-alpine AS runtime
WORKDIR /app

COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY .env.example ./.env

EXPOSE 3000
ENV NODE_ENV=production
CMD ["node", "dist/index.js"]

Build and run the container:

docker build -t professionals-app .
docker run -d -p 3000:3000 --env-file .env professionals-app

Verify the Production Deployment

Confirm successful deployment by accessing the OpenAPI documentation endpoint. The Hono server automatically serves the Swagger UI at the root path:

curl http://localhost:3000/

A successful response returns the Swagger UI HTML, indicating the server is listening and routing requests correctly.

Key Source Files in the Repository

Understanding these specific files clarifies how the deployment artifacts function:

• src/infrastructure/web/open-api/server.ts: Configures the Hono server instance, registers OpenAPI routes, and executes dotenv.config() to load environment variables.
• src/index.ts: The application entry point that imports the configured server and calls the listen method on the specified PORT.
• package.json: Defines the build script (executing tsc) and lists runtime dependencies including hono and chanfana.
• mcp-openapi-server/Dockerfile: Provides the reference implementation for containerizing TypeScript services from this repository.

Summary

• Compile TypeScript sources using npm run build to generate the dist/ directory.
• Install only production dependencies with npm ci --omit=dev to minimize the deployment size.
• Define PORT and database credentials in a .env file loaded by the application at startup.
• Launch the server using node dist/index.js, a process manager like PM2, or a Docker container based on the provided Dockerfile pattern.
• Validate the deployment by requesting the root endpoint to receive the Swagger UI documentation.

Frequently Asked Questions

What Node.js version does the castrozan/tcc repository target for production?

The provided Dockerfile examples use node:22-alpine as the base image, indicating Node.js 22 is the recommended runtime. The TypeScript compilation targets compatible ECMAScript versions supported by this Node.js release.

How does the Hono application handle environment variable loading?

According to the source code in src/infrastructure/web/open-api/server.ts, the application imports config from the dotenv package and invokes it immediately. This executes before the Hono server starts, ensuring process.env contains the variables defined in the .env file.

Can both dummy applications run on the same server simultaneously?

Yes, but you must deploy professionals-dummy-app and equipments-dummy-app as separate processes with distinct PORT values assigned in their respective .env files. Each application maintains its own dependency tree and build artifacts.

What command compiles the TypeScript code for production?

The npm run build command executes the TypeScript compiler (tsc) as defined in the scripts section of package.json. This process transpiles all files in src/ to the dist/ directory, creating the JavaScript files executed by Node.js in production.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}