Configuration

Primate works out of the box with zero configuration. In some cases, you may wish to change the defaults. The most common use case is activating additional modules.

Configuration files are located in config. Anything you configure is merged into the defaults.

app.ts

import config from "primate/config";

export default config({
  /* options */
});

import config from "primate/config";

export default config({
  /* options */
});

App options

build

Options to be passed to the esbuild builder. The following properties are overridden.

http.csp

The Content Security Policy (CSP) to use.

Example of a restrictive policy.

{
// all content must come from own origin, excluding subdomains
"default-src": ["'self'"],
// styles must come from own origin, excluding subdomains
"style-src": ["'self'"],
// disallow <object>, <embed> and <applet> elements
"object-src": ["'none'"],
// disallow embedding
"frame-ancestors": ["'none'"],
// all form submissions must be to own origin
"form-action": ["'self'"],
// allow only own origin in <base>
"base-uri": ["'self'"],
}

http.headers

HTTP headers to use when generating requests using the view handler.

http.host

The HTTP host to use. This value is directly passed to the runtime.

http.port

The HTTP port to use. This value is directly passed to the runtime.

http.ssl.cert

Path to SSL certificate. If this property and http.ssl.key are set and point to a valid key/certificate pair, Primate uses https instead of http.

http.ssl.key

Path to SSL key. If http.ssl.cert and this property are set and point to a valid key/certificate pair, Primate uses https instead of http.

http.static.root

The path at which to serve static assets (those located in the static directory). Static assets take precedence over routes. This option allows you to have all static assets served at a subpath, like /public.

modules

Additional modules to load at runtime.

request.body.parse

Whether the request body should be parsed according to the content type. Turning this off is useful if you're using Primate as a programmable reverse proxy and forwarding the requests to another app.

Even if this is turned off, headers, query string and cookies are still parsed and available to request, and request.original then contains the untouched original request.

Reference

import type Module from "@primate/core/Module";
import type FileRef from "@rcompat/fs/FileRef";
import type { BuildOptions } from "esbuild";

interface Config {
  build?: BuildOptions;
  http?: {
    csp?: Record<string, string>;
    headers?: Record<string, string>;
    host?: string; // "localhost"
    port?: number; // 6161
    ssl?: {
      cert?: FileRef | string;
      key?: FileRef | string;
    };
    static?: {
      root?: string; // "/"
    };
  };
  modules?: Module[];
  pages?: {
    app?: string; // "app.html"
    error?: string; // "error.html"
  };
  request?: {
    body?: {
      parse?: boolean; // true
    };
  };
};

session.ts

import session from "primate/config/session";

export default session/*<SessionShape>*/({
  /* options */
});

import session from "primate/config/session";

export default session({
  /* options */
});

Session options

cookie.httpOnly

Whether the session cookie should be set as and not be readable in JavaScript.

cookie.name

The name of the session cookie.

cookie.path

The session cookie path (paths on which the cookie is loaded).

cookie.sameSIte

The level of security to use in sending the session cookies when browsing between websites.

manager

The session cookie manager. By default, we use an in-memory session manager that resets when the app restarts.

i18n.ts

import i18n from "primate/config/i18n";

export default i18n({
  /* options */
});

import i18n from "primate/config/i18n";

export default i18n({
  /* options */
});

i18n options

defaultLocale

The default locale to use, must one one from the locales list.

locales

List of locales to use, must have at least one locale.

currency

Currency to use in localization.

persist

Locale persistance mode.

database/*.ts

import sqlite from "@primate/sqlite";

export default sqlite();

import sqlite from "@primate/sqlite";

export default sqlite();