CLI (chopd)

The tool chopd is a CLI that aids in the development of applications using the Chopin Framework. It provides a reverse proxy with request queueing, callback mechanisms, identity simulation, websocket pass-through, and more—helpful for local development and testing.

Features

Queued Methods

POST, PUT, PATCH, and DELETE requests are queued and executed in sequence, ensuring deterministic behavior under concurrent writes.

x-callback-url Header

For queued requests, the proxy injects an x-callback-url header so the destination server can send interim data ("context") back to the proxy while the request is still active. This data is stored in an ordered list and can be referenced later.

Chopin Identity Simulation

• /_chopin/login[?as="0x..."] sets a dev-address cookie.
• If present, the proxy adds an x-address header, mimicking Chopin Framework's embedded wallet system.
• Simplifies local dev by simulating a "logged in" user's address.

Logging

A log endpoint /_chopin/logs returns a list of all queued requests with their context logs (currently under development).

Websocket Passthrough

Maintains compatibility with dev tools that require websockets (e.g., HMR).

Executable via npx chopd

No global install needed—just run the CLI.

Config File Support

Automatically starts your development server alongside the proxy using chopin.config.json.

Prerequisites

• Node.js (version 20+ recommended).
• npm or another Node package manager.

Usage

Run the following command inside the root directory of you existing codebase:

npx chopd init

This will:

1. Create a chopin.config.json with default settings
2. Create a .chopin directory for internal use
3. Add .chopin to your .gitignore

Then start the proxy and your development server:

npx chopd

This sets up a reverse proxy on 4000 that forwards to 3000 (by default).

To specify custom ports, supply them as arguments:

npx chopd [proxy-port] [target-port]

For example:

npx chopd 4000 3000

…will proxy requests on port 4000 to your app on port 3000.

Configuration

You can create a chopin.config.json file in your project root to configure the proxy and automatically start your development server. The configuration file supports the following options:

{
  "command": "npm run dev",        // Required. Command to start your dev server
  "proxyPort": 4000,              // Optional. Port for the proxy (default: 4000)
  "targetPort": 3000,             // Optional. Port for your dev server (default: 3000)
}

Configuration Options

When you run chopd, it will:

1. Read and validate the config file if it exists
2. Start your development server using the specified command
3. Start the proxy server
4. Handle graceful shutdown of both processes when you exit

The proxy will use the ports specified in the config unless overridden by command line arguments.