How to configure Jeasx

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
• .env.js

An existing environment variable will not be overwritten by subsequent environment files. The last .env.js file is an exception to this rule: it is a JavaScript file which must export an default object containing the environment variables. All exported variables from .env.js will overwrite already existing variables.

The configuration object from an .env.js file is imported directly into both the build process and server runtime, allowing you to use package imports seamlessly.

export default {
  // Typical example env variables
  RECIPES_ENDPOINT: "https://dummyjson.com/recipes",
  CACHE_DIRECTORY: "/tmp/cache",

  // Jeasx configurations for esbuild & Fastify

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

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

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.

Configuration options

It is highly recommended to configure Jeasx via .env.js, but you can also use process environment variables if preferred.

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.

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 .env.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, default options applied by Jeasx:

{
  "logger": true
}

FASTIFY_STATIC_OPTIONS

Fastify-Static options reference, default options applied by Jeasx:

{
  "root": ["/absolute/path/to/public", "/absolute/path/to/dist/browser"],
  "prefix": "/",
  "wildcard": false
}

FASTIFY_MULTIPART_OPTIONS

Fastify-Multipart options reference, default options applied by Jeasx:

{
  "attachFieldsToBody": "keyValues"
}

FASTIFY_COOKIE_OPTIONS

Fastify-Cookie options reference, default options applied by Jeasx:

{}

FASTIFY_FORMBODY_OPTIONS

Fastify-Formbody options reference, default options applied by Jeasx:

{}