Configuration#

A palinx project is configured by a single palinx.config.ts at its root. Export a config object with defineConfig, which gives you type checking and editor completion over every option.

The config file#

The starter app ships a minimal config:

// palinx.config.ts
import { defineConfig } from "@palinx/core";

export default defineConfig({
  server: {
    port: 2500,
  },
  router: {
    routesDir: "src/routes",
    apiDir: "src/api",
  },
});

Every option is optional and has a sensible default. A config with no fields at all is valid.

Server#

Controls the HTTP server.

server: {
  port: 2500,                        // default 2500; applies in every run mode
  host: "0.0.0.0",                   // address to listen on (see below for defaults)
  allowedHosts: [".preview.test"],   // px dev only: extra host names it answers to
  websocket: {
    maxPayloadLength: 1024 * 1024,   // largest WebSocket message, in bytes (default 16 MB)
  },
  exitOnUncaughtException: false,    // true: exit after an uncaught exception (default false)
}

server.port is honored by dev and by the production server (build writes it into the server as its default). In both, a --port= flag and the PORT environment variable take precedence over it, in that order. See the CLI reference for the full resolution.

server.host is the address to listen on. Without it, dev listens on 127.0.0.1 (this machine only) and the production server on 0.0.0.0 (every interface). Setting it changes both, so host: "0.0.0.0" also opens dev to your network. Like the port, build writes it into the production server, and in both a --host flag and the PALINX_HOST environment variable take precedence over it, in that order.

server.allowedHosts lists extra host names dev answers to; it refuses others with a 403. A leading dot allows a name and its subdomains (".preview.test"), and true turns the check off. localhost, 127.0.0.1, [::1] and the address dev listens on are always allowed. The production server doesn't use it. See Allowed host names in the CLI reference.

server.websocket.maxPayloadLength is the largest message a WebSocket route accepts, in bytes. A client that sends more is disconnected. See WebSockets.

server.exitOnUncaughtException decides what the server does after an uncaught exception, such as a throw inside a timer. By default it logs the error and keeps serving; true makes it stop accepting connections, finish the requests already open, and exit with status 1, for a supervisor to restart. See Deployment.

Router#

Tells palinx where your routes and API endpoints live. Change these if your project doesn't use the default layout.

router: {
  routesDir: "src/routes",
  apiDir: "src/api",
}

Build#

Controls the production build (px build).

build: {
  outDir: "dist",     // build output directory
  sourcemap: false,   // emit source maps
  minify: true,       // minify the client bundle
}

SSR#

Server-side rendering options.

ssr: {
  enabled: true,      // render on the server for first paint
  streaming: false,   // stream the response
}

Security#

Palinx exposes configuration for CORS, CSRF, rate limiting, security headers, and TLS under security. These are opt-in; the shape looks like:

security: {
  cors: { origins: ["https://example.com"], credentials: true },
  csrf: { enabled: true },
  rateLimit: { windowMs: 60_000, max: 100 },
}

security.cors.origins also lists the other sites whose pages may open your WebSocket routes, by name only: a "*" there never applies to WebSockets. security.trustProxy: true lets the server read the X-Forwarded-* headers (and X-Real-IP) from a reverse proxy you control; WebSocket routes then compare a page's origin with X-Forwarded-Host. See WebSockets.

Development and production#

px dev reads palinx.config.ts every time it starts. The production server doesn't: px build reads it once and builds the values into dist/, so a change, including a change to an environment variable the config reads, needs a fresh build. The CSRF secret is the exception; the production server reads PALINX_CSRF_SECRET from its environment when it starts. Deployment has the details.

Next#

With the framework covered end to end, the CLI reference documents each command: scaffold, dev, make, test, build, and serve.