How to configure Jeasx

Environment variables

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.

• .env.[NODE_ENV].local (e.g. .env.development.local or .env.production.local)
• .env.[NODE_ENV] (e.g. .env.development or .env.production)
• .env.local
• .env
• .env.defaults

An existing environment variable will not be overwritten by subsequent environment files.

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.

Fundamental environment variables

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 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.

Configure esbuild and Fastify via jeasx.config.js

The configuration object from jeasx.config.js is imported directly into both the build process and server runtime and provides essential options for esbuild and Fastify, allowing you to use the full power of JavaScript (e.g package imports) to build advanced setups.

export default {
  /** @type {() => import("esbuild").BuildOptions} */
  ESBUILD_BROWSER_OPTIONS: () => ({
    target: ["chrome130", "edge130", "firefox130", "safari18"],
  }),

  /** @type {() => import("fastify").FastifyServerOptions} */
  FASTIFY_SERVER_OPTIONS: () => ({
    logger: { level: process.env.NODE_ENV === "development" ? "error" : "info" },
    bodyLimit: 1024 * 1024,
  }),
};

ESBUILD_SERVER_OPTIONS

Useful to enhance esbuild for compiling server code with existing plugins (Jeasx config at GitHub). The esbuild website provides a detailed explanation of all configuration options.

If you want to use MDX with plugins, you can configure them in jeasx.config.js after installing them to your project:

import mdx from "@mdx-js/esbuild";
import rehypePrismPlus from "rehype-prism-plus";
import rehypeSlug from "rehype-slug";
import remarkGFM from "remark-gfm";

export default {
  /** @type {() => import("esbuild").BuildOptions} */
  ESBUILD_SERVER_OPTIONS: () => ({
    plugins: [
      mdx({
        development: process.env.NODE_ENV === "development",
        jsxImportSource: "jsx-async-runtime",
        elementAttributeNameCase: "html",
        stylePropertyNameCase: "css",
        remarkPlugins: [[remarkGFM, { singleTilde: false }]],
        rehypePlugins: [rehypePrismPlus, [rehypeSlug, { prefix: "jeasx-" }]],
      }),
    ],
  }),
};

ESBUILD_BROWSER_OPTIONS

Useful to configure build options for the browser bundle (Jeasx config at GitHub), e.g. reconfigure the browser target of esbuild. Full documentation at esbuild website.

export default {
  /** @type {() => import("esbuild").BuildOptions} */
  ESBUILD_BROWSER_OPTIONS: () => ({
    target: ["chrome130", "edge130", "firefox130", "safari18"],
  }),
};

FASTIFY_SERVER

This allows you to enhance the functionality of the underlying Fastify server, e.g. registering plugins.

import fastifyCompress from "@fastify/compress";

export default {
  /** @type {(fastify: import("fastify").FastifyInstance) => import("fastify").FastifyInstance} */
  FASTIFY_SERVER: (fastify) => fastify.register(fastifyCompress),
};

FASTIFY_SERVER_OPTIONS

Fastity-Server options reference.

FASTIFY_SEND_OPTIONS

Fastify-Send options reference.

FASTIFY_COOKIE_OPTIONS

Fastify-Cookie options reference.

FASTIFY_FORMBODY_OPTIONS

Fastify-Formbody options reference.

FASTIFY_MULTIPART_OPTIONS

Fastify-Multipart options reference.