Deployment Guide

Relevant source files

The following files were used as context for generating this wiki page:

• apps/web/vite.config.ts
• apps/api/src/index.ts
• README.md
• package.json
• turbo.json
• apps/web/package.json

This guide provides instructions for building and deploying the Adfluens (YouTube Channel Analyzer) application for a production environment. The project is a Turborepo monorepo consisting of a React frontend (web) and an Express backend (api). In production, the api server is responsible for serving both the backend endpoints and the static frontend assets.

The deployment process involves building the frontend application into a static directory and then running the backend server, which is configured to serve these static files when not handling API requests. This creates a self-contained production artifact that can be run in a Node.js environment.

1. Prerequisites

Before deployment, ensure the production environment meets the following requirements:

Requirement	Version/Tool	Source
Node.js	>=20	package.json:30
Package Manager	pnpm	README.md:32, package.json:29

Sources: package.json:29-31, README.md:32-35

2. Build Process

The entire project is built using a single command, which is orchestrated by Turborepo.

pnpm build

Sources: package.json:7, README.md:55-57

This command executes the build task defined in turbo.json. Turborepo analyzes the dependencies between the workspaces (apps and packages) and runs their respective build scripts in the correct order.

Build Orchestration

The root build task depends on the build tasks of its dependencies (^build), caching the output in directories like dist/ and .next/.

// turbo.json
{
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**", "!.next/cache/**"],
      "env": ["NODE_ENV"]
    }
  }
}

Sources: turbo.json:3-9

The following diagram illustrates the build flow initiated by pnpm build.

This diagram shows how the pnpm build command uses Turborepo to build the web application, resulting in a static dist directory.
Sources: package.json:7, turbo.json:4-8, apps/web/package.json:8, apps/web/vite.config.ts:27-30

Frontend Build (@repo/web)

The web application is a Vite-based React app. The build script first runs the TypeScript compiler (tsc) for type-checking and then uses Vite to bundle the application for production.

• Command: tsc && vite build
• Output Directory: The build artifacts are placed in the apps/web/dist directory.

// apps/web/vite.config.ts
export default defineConfig({
  // ...
  build: {
    outDir: "dist",
    sourcemap: true,
  },
});

Sources: apps/web/package.json:8, apps/web/vite.config.ts:27-31

3. Production Environment

In a production environment (NODE_ENV=production), the api server acts as the single entry point, serving both the API and the frontend.

API Server (@repo/api)

The Express server in apps/api/src/index.ts is configured to handle production deployment. When env.NODE_ENV is set to 'production', it enables a static file server.

Key production logic:

1. It defines the path to the frontend's build output: path.join(__dirname, "..", "..", "web", "dist").
2. It uses express.static() to serve files from that directory.
3. A wildcard route app.get("*", ...) is set up to serve index.html for any request that doesn't match an API route or a static file. This enables client-side routing.

// apps/api/src/index.ts
// ...
const isDev = env.NODE_ENV !== "production";
// ...
if (!isDev) {
  const distPath = path.join(__dirname, "..", "..", "web", "dist");
  app.use(express.static(distPath));

  // Handle client-side routing
  app.get("*", (req, res) => {
    res.sendFile(path.join(distPath, "index.html"));
  });
}

Sources: apps/api/src/index.ts:16, apps/api/src/index.ts:47-56

Production Request Flow

The following diagram shows how the API server handles incoming requests in production.

This diagram illustrates that the Express server first attempts to match API routes or static files. If no match is found, it serves the main index.html file to support client-side routing.
Sources: apps/api/src/index.ts:40-56

Environment Variables

The application requires the following environment variables to be set in the production environment. These are necessary for connecting to external services like the YouTube and Gemini APIs.

Variable	Description	Source
YOUTUBE_API_KEY	API key for YouTube Data API v3.	README.md:42
GEMINI_API_KEY	API key for Google Gemini.	README.md:43
PORT	The port for the API server to listen on.	apps/api/src/index.ts:15
NODE_ENV	Must be set to production to enable static file serving.	apps/api/src/index.ts:16

Sources: README.md:39-45, apps/api/src/index.ts:15-16

4. Running in Production

To run the application in a production environment, follow these steps:

1. Install Dependencies:

   pnpm install
   

2. Build the Project:

   pnpm build
   

3. Start the Server:
   Set the required environment variables and start the Node.js server.

   NODE_ENV=production PORT=3001 pnpm --filter @repo/api start
   

   (Note: The start script is not explicitly defined but is a common convention. The server is started by running the output of the api build, likely node dist/index.js within the apps/api directory).

The server will then be running and accessible on the specified port, serving both the frontend application and the backend API.
Sources: README.md:36, README.md:56, apps/api/src/index.ts:58-64

Summary

Deploying the Adfluens application involves a unified build step managed by Turborepo, which produces a static frontend in apps/web/dist. The production architecture relies on the backend api server, which, when NODE_ENV is set to production, serves these static assets alongside its tRPC and authentication endpoints. This creates a simple, cohesive deployment model suitable for any standard Node.js hosting environment.