med-plan-assistant/docs/README.dev-notes.md

Development Notes

Current Tech Stack (2025-11-26)

• React 19.1.1 with TypeScript 5.9.3
• shadcn/ui component library (Radix UI + Tailwind)
• Tailwind CSS 3.4.18 for styling
• Recharts 3.3.0 for data visualization
• Create React App 5.0.1 as build tool

Initial Setup (Fresh Clone)

# Install all dependencies
npm install

# Run development server
npm start

# Build for production
npm run build

shadcn/ui Setup (Already Done)

The project was set up with shadcn/ui components. If you need to add more components:

# Add new shadcn/ui components
npx shadcn@latest add [component-name]

# Example:
npx shadcn@latest add dialog

TypeScript Configuration

TypeScript is configured with:

• Strict mode enabled
• Path aliases: @/* → ./src/*
• Target: ES5
• Module: ESNext
• JSX: react-jsx

Tailwind CSS Configuration

Content paths in tailwind.config.js:

module.exports = {
  content: [
    "./src/**/*.{js,jsx,ts,tsx}",
  ],
  theme: {
    extend: {
      colors: {
        // HSL-based color system for shadcn/ui
      },
    },
  },
  plugins: [require("tailwindcss-animate")],
}

Global styles in ./src/styles/global.css:

@tailwind base;
@tailwind components;
@tailwind utilities;

@layer base {
  :root {
    --background: 0 0% 98%;
    --foreground: 222 47% 11%;
    /* ... more CSS variables for shadcn/ui theme */
  }
}

WSL Networking Issues

If access to http://localhost:3000 dose not work from Windows host, when running the React development server in WSL, look at the following troubleshooting steps.

Note that not all steps may be necessary, depending on your specific WSL and Windows setup.

In my case Option 1 (NAT, WSL default), cross-env host binding to HOST=0.0.0.0, port forwarding, and firewall rules were necessary to access the dev server from Windows host via http://172.20.39.187:3000 (my WSL IP address).

In my case the npm start terminal output shows:

  Local:            http://localhost:3000
  On Your Network:  http://172.20.39.187:3000

WSL Networking Modes

Check and potentially change the network mode of WSL.

Option 1: NAT Networking Mode (Default)

This is the default mode used if Option 2 is not specifically set. Unless the settings described in Option 2 are applied, this mode is active.

Option 2: Mirrored Networking Mode (Windows 11 22H2+)

In %USERPROFILE%\.wslconfig add:

[wsl2]
networkingMode=mirrored

Then stop WSL and start it again so the changes take effect:

wsl --shutdown
wsl

Dev Server Host Binding

To ensure that the React development server binds to all interfaces in WSL, install the cross-env package:

npm install cross-env --save-dev

And modify the start script in package.json as follows.

"scripts": {
  // "start": "react-scripts start"  // Original line, basic start command
  "start": "cross-env HOST=0.0.0.0 react-scripts start"
}

Note that when I tried it with only HOST=0.0.0.0 but without cross-env, even though some things may have changed, the server was still bound to 127.0.1.1 and not to all interfaces.

Port Forwarding

If you want to access the React dev server via http://localhost:3000 on Windows host, you need to set up port forwarding from Windows localhost to the WSL IP address.

First get the WSL IP address by running the following command in WSL:

hostname -I

# Or from Windows Command Prompt / PowerShell:
wsl hostname -I

Then use the WSL IP address (in my case 172.20.39.187) in the following command to set up permanent port forwarding.

# Add port forwarding rule
netsh interface portproxy add v4tov4 listenport=3000 listenaddress=127.0.0.1 connectport=3000 connectaddress=172.20.39.187

# Just in case you need to delete the rule later, use:
#netsh interface portproxy delete v4tov4 listenport=3000 listenaddress=127.0.0.1

You should now be able to access the React dev server via http://localhost:3000 on Windows host, instead of having to use the WSL IP address.

Open Firewall Ports

In case you have trouble with your Windows Firewall blocking access to the forwarded port, or you want to allow access from other devices on your network, you may need to open the port in the firewall.

Run the following PowerShell commands to open the necessary port (just an example, ensure that the settings fit your security requirements):

# Open port 3000 for inbound TCP traffic on WSL virtual network interface
New-NetFirewallRule -DisplayName "Allow WSL Inbound Port 3000" `
    -Direction Inbound -Action Allow -Protocol TCP -LocalPort 3000 `
    -InterfaceAlias "vEthernet (WSL (Hyper-V firewall))"

In case the above does not resolve your issues, just to rule out potential firewall issues, it is always an option to temporarily disable the firewall all together.

WARNING: IF YOU DO THIS, DO NOT FORGET TO RE-ENABLE THE FIREWALL AFTER TESTING!

VS Code Dev Container Port Forwarding

When running the React dev server in a VS Code dev container (WSL2 + Podman/Docker), VS Code automatically forwards ports from the container to the Windows host. However, you may encounter:

1. Port remapping: If port 3000 is busy on Windows, VS Code may forward to 3001 or another available port
2. WebSocket errors: The React dev server's WebSocket may try to connect to the original port instead of the forwarded one

Fix WebSocket Connection Issues

Create a .env.development file in the project root:

# WebSocket configuration for dev server
# This ensures hot-reloading works correctly when accessing via VS Code port forwarding
WDS_SOCKET_PORT=0

Setting WDS_SOCKET_PORT=0 tells webpack dev server to use the same port as the page URL, automatically adapting to VS Code's port forwarding.

Dev Container vs Direct WSL2 Configuration Differences

In VS Code Dev Containers:

• HOST=0.0.0.0 is not needed - VS Code handles port forwarding from container's localhost
• CHOKIDAR_USEPOLLING=true is usually not needed - container filesystem is typically better than WSL2's
• React Fast Refresh works well - keep it enabled

In Direct WSL2 (no container):

• HOST=0.0.0.0 is required - to bind to WSL2's network interface
• CHOKIDAR_USEPOLLING=true may be needed - WSL2 filesystem watch can be unreliable
• Manual port forwarding with netsh interface portproxy may be needed

Project Scripts:

The project includes separate scripts for different environments:

# In VS Code Dev Container (default, optimized)
npm start

# In direct WSL2 (without container)
npm run start:wsl2

Configured in package.json:

"scripts": {
  "start": "cross-env BROWSER=none react-scripts start",
  "start:wsl2": "cross-env HOST=0.0.0.0 BROWSER=none CHOKIDAR_USEPOLLING=true react-scripts start"
}

This way you don't need to modify scripts when switching between environments.

Configure Port Forwarding Behavior

In .devcontainer/devcontainer.json, you can configure port forwarding:

{
  "forwardPorts": [3000],
  "portsAttributes": {
    "3000": {
      "label": "React Dev Server",
      "onAutoForward": "notify"
    }
  }
}

Check Which Port is Actually Forwarded

In VS Code, check the PORTS tab (usually in the bottom panel) to see:

• Which container ports are forwarded
• Which Windows host ports they map to
• You can manually change the forwarded port by right-clicking the port entry

Note: If port 3000 is busy on Windows, VS Code may automatically forward to 3001 or another available port. This is normal - just use whatever port VS Code assigns in the PORTS tab.

Kill Stuck Dev Server

If you need to free port 3000 (e.g., stuck dev server process):

npm run kill

This script uses lsof to find and terminate any process using port 3000. Note: lsof must be installed in the container (already configured in Dockerfile).

Important: No Manual Port Proxy Needed

When using VS Code dev containers, you do not need netsh interface portproxy rules. VS Code handles all port forwarding automatically. Remove any existing rules:

netsh interface portproxy delete v4tov4 listenport=3000 listenaddress=127.0.0.1

Development Server

(Prevent) Auto Open in Browser

Per default, the React development server does automatically open the app in the browser when started. If this is not desired, add BROWSER=none to the start script in package.json as follows. Note that this also requires the cross-env package as described above.

"scripts": {
  "start": "cross-env HOST=0.0.0.0 BROWSER=none react-scripts start"
}

Alternatively (not verified) a .env file can be created in the project root with the following content, so no changes to package.json are necessary.

BROWSER=none

Hot Reloading File System Issues (in WSL)

Install development dependency nodemon to monitor file changes and restart the server automatically.

npm install -D nodemon

Modify the start script in package.json to use nodemon with polling enabled. This helps in environments like WSL where file system events may not be detected properly.

"scripts": {
  "start": "cross-env HOST=0.0.0.0 BROWSER=none CHOKIDAR_USEPOLLING=true react-scripts start"
}

Alternatively, add CHOKIDAR_USEPOLLING=true to a .env file in the project root:

echo CHOKIDAR_USEPOLLING=true >> .env

Then the start script can remain as:

npm start

Webhint

Setup webhint in Project

Check local config:

# Install hint locally in the project
npm install hint --save-dev

# Optionally use the web-recommended config
#npm install @hint/configuration-web-recommended --save-dev
#npm create hintrc

# Or create .hintrc manually with a basic config
```sh
cat > .hintrc <<EOL
{
  "extends": ["web-recommended"]
}
EOL

Add webhint script to package.json:

"scripts": {
  "webhint": "hint"
}

Optionally install puppeteer if you want to run webhint with headless Chrome:

npm install puppeteer --save-dev

Run webhint

Ensure that the React development server is running when you run webhint against http://localhost:3000.

npm start

Run webhint:

npm run webhint -- http://localhost:3000

Open ./hint-report/http-localhost-3000.html in a browser to see the report.

VS Code: Problems with "Microsoft Edge Tools for VS Code" Extension

Error message:

Unable to start webhint. Ensure you are using the latest version of the hint package.

Solution:

Install webhint locally in the project as shown above, or update to the latest version:

npm install hint@latest --save-dev

In doubt check the global installation and remove it if necessary:

# Global config
npm list -g hint

# Uninstall global version if necessary
npm uninstall -g hint

External Resources

• https://github.com/webhintio/hint
• https://webhint.io/docs/user-guide/configuring-webhint/summary/