proxy-cat

🚀 Start proxy server on local environment, handle CORS during local development.

Usage

Command Line Interface

Start a proxy server on port 4001 that proxies to https://api-endpoint.com:

npx proxy-cat@latest -p 4001 https://api-endpoint.com

Basic Usage

# Use default port 4000
npx proxy-cat https://api.example.com

# Specify custom port
npx proxy-cat -p 8080 https://api.example.com

# Help
npx proxy-cat --help

# Kill proxy-cat process
npx proxy-cat kill

Features

• ✅ CORS Support: Automatically handles CORS headers for local development
• ✅ Easy CLI: Simple command-line interface
• ✅ Flexible Ports: Use any available port
• ✅ Request Logging: See all proxied requests in real-time
• ✅ Health Check: Built-in health check endpoint at /health
• ✅ Error Handling: Graceful error handling and logging
• ✅ Secure: Supports HTTPS targets with SSL verification

Options

| Option | Short | Description | Default | | ----------- | ----- | -------------------------------- | ------- | | --port | -p | Port number for the proxy server | 4000 | | --help | -h | Show help information | - | | --version | -V | Show version number | - |

Examples

Development API Proxy

# Proxy your local frontend to a remote API
npx proxy-cat -p 4001 https://jsonplaceholder.typicode.com

Then in your frontend code:

// Instead of: https://jsonplaceholder.typicode.com/posts
// Use: http://localhost:4001/posts
fetch("http://localhost:4001/posts")
  .then((response) => response.json())
  .then((data) => console.log(data));

Health Check

The proxy server provides a health check endpoint:

curl http://localhost:4001/health

Response:

{
  "status": "ok",
  "proxy": {
    "port": 4001,
    "target": "https://api-endpoint.com"
  },
  "timestamp": "2025-10-10T10:30:00.000Z"
}

Common Use Cases

1. CORS Issues: When your local frontend can't access a remote API due to CORS
2. API Development: Testing against different API environments
3. Local Development: Proxying requests during development
4. API Mocking: Use with mock servers for testing
5. Cookie/Session Management: Handle authentication cookies across different domains

Requirements

• Node.js >= 20.0.0
• npm or yarn

License

MIT

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Issues

If you encounter any issues, please report them on GitHub Issues.