Jeasx – JSX with Ease

Config & Environments

How to configure Jeasx

Jeasx provides sensible defaults to get you started quickly, but it also allows you to override important settings with environment variables. This makes it easy to adapt the framework to your needs.

To facilitate managing multiple configurations, Jeasx leverages layers of .env-files. This enables the use of different .env-files based on the NODE_ENV value, such as .env.development to override values from .env for development. The order of loading .env-files is the same as it is used by the well-known dotenv-flow library. To load the env-files into process.env, Jeasx makes use of the native implementation provided by Node.js via process.loadEnvFile via a custom utility function. An existing environment variable will not be overwritten by subsequent files.

  1. .env.[NODE_ENV].local (e.g. .env.development.local or .env.production.local)
  2. .env.[NODE_ENV] (e.g. .env.development or .env.production)
  3. .env.local
  4. .env
  5. .env.defaults

Please note: Jeasx only sets NODE_ENV=development automatically when running jeasx dev. For production or testing environments, you'll need to set the NODE_ENV environment variable to the desired value (e.g. production or test) depending on your requirements and workflows.

Environment variables for client code

For security reasons, only environment variables prefixed with BROWSER_PUBLIC_ are accessible in client-side JavaScript (src/browser) to prevent accidental exposure of sensitive data. The values are only updated at build time, so changes to environment variables will require a rebuild to take effect.

Environment Variables

NameDescription
HOST

The hostname or IP address that the server should listen on. Defaults to :: which allows the server to listen on any interface (IPv4 or IPv6).

PORT

The port number that the server should listen on. Defaults to 3000.

BUILD_​TIME

A read-only value set at build time and encoded as base36 (lower case alphabet and digits). Use it to create a cache busting parameter for loading JavaScript and CSS files.

ESBUILD_​BROWSER_​TARGET

Defaults to chrome126, edge126, firefox128, safari17, full documentation at esbuild website.

FASTIFY_​BODY_​LIMIT

The default maximum body size for incoming requests is 1048576 bytes. Adjust this value only if you need to accommodate large file uploads.

FASTIFY_​DISABLE_​REQUEST_​LOGGING

Set this to true to disable request logging.

FASTIFY_​REWRITE_​URL

If you want to rewrite incoming URLs (e.g. running behind a proxy server or when you want to fake non-existing URLs), you can provide a function which takes a request object and returns an URL as string. To ignore a leading segment like /proxy/, use (req) => req.url.replace(/^\/proxy/,""). Please have a look at the Fastify docs for more information.

FASTIFY_​STATIC_​HEADERS

Custom headers for static files, such as JavaScript, CSS, and assets from the public directory. Use these headers to configure cache settings for static content.

{
  "": {
    "Cache-Control":
      "public, max-age=31536000"
  },
  "robots.txt": {
    "Cache-Control":
      "public, max-age=86400"
  },
  ".html": {
    "Cache-Control":
      "public, max-age=0"
  },
}

The keys of the mapping are compared via .endsWith() with the current path, so an empty string matches all paths and can be used as fallback.

Please note: If you set caching headers in global .env, you should clear them in .env.development (e.g. via FASTIFY_STATIC_HEADERS=) to avoid caching issues in development.

FASTIFY_​TRUST_​PROXY

By enabling the trustProxy option, Fastify will know that it is sitting behind a proxy and that the X-Forwarded-* header fields may be trusted, which otherwise may be easily spoofed. Please note: the option only supports boolean or string values.