# Deploying TanStack Start (Lovable App) to Namecheap Shared Hosting

This guide outlines the step-by-step process of hosting a Server-Side Rendered (SSR) TanStack Start application (originally built with Lovable) on Namecheap Shared Hosting via cPanel.

---

## Technical Overview
* **Framework:** TanStack Start (Vite + Vinxi + React)
* **Hosting Server Runtime:** Node.js (v20.x or v22.x recommended)
* **Web Server Runner:** Phusion Passenger (managed by cPanel **Setup Node.js App**)
* **Static Assets:** Handled automatically by Passenger by copying client files to a root `public` directory post-build.

---

## Step-by-Step Deployment Guide

### Step 1: Clone the Repository via SSH
1. Log into your server using SSH:
   ```bash
   ssh your_username@your_server_ip -p 21098
   ```
2. In the home user directory (not inside `public_html`), clone your repository:
   ```bash
   git clone https://github.com/justinsteefdev-byte/sks-associates.git
   ```

---

### Step 2: Configure the Node.js App in cPanel
1. Open **cPanel** in your browser and select **Setup Node.js App**.
2. Click **Create Application** and fill out the fields:
   * **Node.js version:** Select `20.x` or `22.x` (Do NOT select older versions like 10).
   * **Application mode:** `Production` (sets `NODE_ENV=production`).
   * **Application root:** `sks-associates`
   * **Application URL:** Select `https://sks-associates.com` (or your subdomain like `new.sks-associates.com`).
   * **Application startup file:** `app.js`
3. Click **Create**.
4. Once created, copy the **"Command for entering to the virtual environment"** shown at the top of the page. It will look like this:
   ```bash
   source /home/your_username/nodevenv/sks-associates/22/bin/activate && cd /home/your_username/sks-associates
   ```

---

### Step 3: Enter the Node Environment and Install Dependencies
1. Paste the virtual environment activation command you copied into your active SSH terminal.
2. Verify you are inside the virtual environment (you should see the Node version/name prefix in your prompt).
3. Install the dependencies and compile the production build:
   ```bash
   npm install
   npm run build
   ```
   * **Note:** The build command is pre-configured to build the app and then copy the compiled static assets from `dist/client/` to a root `public/` folder so the web server can serve them correctly without 404 errors.

---

### Step 4: Verify the Startup Script (`app.js`)
Ensure you have an `app.js` file in your root folder. This file bridges Passenger's Node.js web server with the Web Fetch API handler generated by TanStack Start.

The file contains:
```javascript
import { createServer } from 'node:http';
import { Readable } from 'node:stream';
import serverEntry from './dist/server/server.js';

const port = process.env.PORT || 3000;

const server = createServer(async (req, res) => {
  try {
    const protocol = req.headers['x-forwarded-proto'] || 'http';
    const host = req.headers.host || 'localhost';
    const url = new URL(req.url, `${protocol}://${host}`);

    // Create a Web Request from the Node.js request stream
    const request = new Request(url, {
      method: req.method,
      headers: new Headers(req.headers),
      body: req.method !== 'GET' && req.method !== 'HEAD' ? Readable.toWeb(req) : null,
      duplex: 'half'
    });

    // Invoke the TanStack Start request handler
    const response = await serverEntry.fetch(request);

    // Apply the Web Response back to the Node.js response stream
    res.writeHead(response.status, Object.fromEntries(response.headers));
    if (response.body) {
      for await (const chunk of response.body) {
        res.write(chunk);
      }
    }
    res.end();
  } catch (error) {
    console.error('Server Request Error:', error);
    res.writeHead(500, { 'Content-Type': 'text/plain' });
    res.end('Internal Server Error');
  }
});

server.listen(port, () => {
  console.log(`Server listening on port ${port}`);
});
```

To verify it runs correctly in your SSH terminal, run:
```bash
node app.js
```
*(Press `Ctrl + C` to stop once you see `Server listening on port 3000`)*.

---

### Step 5: Restart the App in cPanel
1. Go back to your browser window on the cPanel Node.js Selector.
2. Click **Restart** at the top.
3. Open your browser and navigate to your website URL. Your updated site is now live!

---

## Future Updates
When you push code changes to GitHub, deploy them by running these commands in your active Node virtual environment inside your SSH terminal:
```bash
git pull
npm install  # (Only if dependencies changed)
npm run build
```
Then click **Restart** on the cPanel Node.js App page.