Overview

How wsignal finds, validates, and resolves its config.

Config File Names

wsignal looks for these files in the current working directory:

• wsignal.config.ts
• wsignal.config.js
• wsignal.config.mjs

You can also pass an explicit file path with --config.

Recommended Authoring Style

You can export a plain object:

export default {
  port: 8787,
  endpoints: [
    {
      name: "github",
      path: "/github",
      method: "POST",
    },
  ],
}

Or use the helper for better editor feedback:

import { defineConfig } from "@wsignal/cli"

export default defineConfig({
  port: 8787,
  endpoints: [
    {
      name: "github",
      path: "/github",
      method: "POST",
    },
  ],
})

Resolution Rules

At runtime, wsignal resolves config values into a normalized internal shape.

Port

• Default: 8787
• Must be an integer between 1 and 65535

Storage

• Default directory: .wsignal
• Default central file: events.jsonl
• Rotation defaults:
  • maxSizeMb: 10
  • maxFiles: 20

Endpoints

• name is required and must be non-empty.
• path is required and must start with /.
• method defaults to POST.
• method may be a string or an array of strings.
• Supported methods are DELETE, GET, HEAD, OPTIONS, PATCH, POST, and PUT.
• logFile, when present, resolves relative to the configured storage directory.

Responses

If you do not specify a response, wsignal uses:

• Status 200
• Content type text/plain; charset=utf-8
• Empty body

If you set response.json, wsignal serializes it and responds with application/json; charset=utf-8.

If you set response.text, wsignal responds with text/plain; charset=utf-8.

Forwarding

If an endpoint has forward, it may be a single target object or an array of target objects. Each target must have a valid http or https url.

Forwarding happens after the event is persisted locally and after the configured local response has been sent back to the original caller. It does not replace local persistence.

Forward targets can use when.headers and when.query filters. Header names are matched case-insensitively. Query parameter names are matched case-sensitively.

Proxying

If an endpoint has proxy.url, it must be a valid http or https URL.

Proxying is synchronous. wsignal sends the incoming request upstream, persists the event with the returned status, and returns the upstream status, headers, and body to the original caller.

An endpoint cannot define both forward and proxy.

Validation Rules

wsignal rejects invalid configs before starting the server.

Validation includes:

• Missing endpoints
• Duplicate endpoint names
• Duplicate route definitions for the same method and path
• Invalid port values
• Invalid rotation values
• Endpoint paths that do not start with /
• Unsupported HTTP methods
• Responses that set both json and text
• Invalid forward URLs
• Duplicate forward target names within one endpoint
• Invalid forward target filters
• Invalid proxy URLs
• Endpoints that define both forward and proxy

For a field-by-field reference, see Configuration Reference.