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

> Deploy your Hono.js application to production seamlessly. Follow this guide to build, install dependencies, set environment variables, and run your Hono app or Docker container.

- Repository: [Lucas Zanoni⠀⠀⠀⠀⠀ ⠀╱|、 ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ (˚ˎ 。7 ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ |、˜〵 ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ じしˍ,)ノ/tcc](https://github.com/castrozan/tcc)
- Tags: how-to-guide
- Published: 2026-02-27

---

**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:

```bash
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:

```bash
npm ci --omit=dev

```

3. Compile the TypeScript sources using the build script defined in [`package.json`](https://github.com/castrozan/tcc/blob/main/package.json):

```bash
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:

```text
PORT=3000

```

If connecting to a database, include the connection string:

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

```

In [`src/infrastructure/web/open-api/server.ts`](https://github.com/castrozan/tcc/blob/main/src/infrastructure/web/open-api/server.ts), the application initializes environment loading before starting the Hono server:

```typescript
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:

```bash
NODE_ENV=production node dist/index.js

```

The file [`dist/index.js`](https://github.com/castrozan/tcc/blob/main/dist/index.js) is the compiled output of [`src/index.ts`](https://github.com/castrozan/tcc/blob/main/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:

```bash
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`:

```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:

```bash
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:

```bash
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`](https://github.com/castrozan/tcc/blob/main/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`](https://github.com/castrozan/tcc/blob/main/src/index.ts)**: The application entry point that imports the configured server and calls the listen method on the specified `PORT`.
- **[`package.json`](https://github.com/castrozan/tcc/blob/main/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`](https://github.com/castrozan/tcc/blob/main/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`](https://github.com/castrozan/tcc/blob/main/package.json). This process transpiles all files in `src/` to the `dist/` directory, creating the JavaScript files executed by Node.js in production.