> ## Documentation Index
> Fetch the complete documentation index at: https://wsignal.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```ts theme={null}
export default {
  port: 8787,
  endpoints: [
    {
      name: "github",
      path: "/github",
      method: "POST",
    },
  ],
}
```

Or use the helper for better editor feedback:

```ts theme={null}
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](/configuration/reference).