News
What's new in Jeasx?
2026-11-11 - Jeasx 3.0.1 released
๐ This patch release includes a security update for Fastify (GHSA-3qgw-9275-xf8w). Please update.
๐ Fixes
nullfrom a route now means "no response". Before, a route returningnullsent an empty 200. Now it behaves likeundefined: the next route is tried and the 404 fallback applies.- Dev server serves the same
distfiles as production. In development adistfile is now hidden only when its last path segment is a route output ([name].ext). Before, a file inside a bracketed directory, like[x].d/style.css, was hidden in development but served in production.
๐ Fixes in jsx-async-runtime
- No more crash from deeply nested promises.
jsx()only guarded promises one level deep in a plain object. A promise nested deeper (e.gdata={[{ p }]}) could crash Node with an unhandled rejection when the render failed on it. It is now marked as handled first. - Streams are unlocked after rendering.
readStream()never calledreleaseLock(), so aReadableStreamchild stayed locked after it was fully rendered. The lock is now released when the stream ends, likefor awaitdoes.
๐ฆ Dependency updates
fastify@5.12.8@fastify/send@4.2.1jsx-async-runtime@3.0.1
2026-11-02 - Jeasx 3.0.0 released
The promise you made. Await anything, stream everything.
๐ Jeasx 3 streams your pages. JSX is now sent to the browser while it is
still rendering, powered by jsx-async-runtime@3, which also renders about
2x faster than v2. This release also hardens request routing, the build and
the dev server.
There are breaking changes in Jeasx and in jsx-async-runtime. Each one has
a migration recipe below. Most projects only need these steps:
- Replace
{{ html: "..." }}with{html("...")}. - Replace
class/styleobjects with strings. - Move
this.errorHandlertosetErrorHandlerinjeasx.config.js. - If your
responseHandlerchanges the HTML, read the stream into a string first.
๐ Want to see it in action? Jeasx Expo has many new examples that show off the new features, e.g. Streaming HTML, Out-of-order streaming and Server-Sent Events.
๐ฅ Breaking changes in Jeasx
JSX responses are streamed, so responseHandler gets a stream
Pages are rendered with jsxToStream instead of jsxToString. The browser
gets the first bytes while slow parts of the page (e.g. awaited data) are
still rendering. For JSX, the payload passed to this.responseHandler is
now a ReadableStream<string> instead of a string.
Migration: if your responseHandler only sets headers or passes the
payload through, nothing changes. If it changes the HTML (e.g. to format or
minify it), read the stream into a string first:
this.responseHandler = async (payload) => {
if (payload instanceof ReadableStream) {
payload = (await Array.fromAsync(payload)).join("");
}
return typeof payload === "string" ? format(payload) : payload;
};
Pages that are post-processed this way are not streamed.
this.errorHandler was removed
Errors thrown by routes and guards now go to Fastify's error handler. Jeasx
no longer looks for this.errorHandler.
Migration: register an error handler in jeasx.config.js. It runs for
errors from all routes:
// jeasx.config.js
export default {
FASTIFY_SERVER: (fastify) =>
fastify.setErrorHandler(async (error, request, reply) => {
request.log.error(error);
reply.status(error.statusCode ?? 500).type("text/html; charset=utf-8");
return "<h1>Something went wrong</h1>";
}),
};
Without your own handler, Fastify answers with a JSON error. jeasx.config.js is not compiled by esbuild by default, so it can't contain JSX. If you want JSX in your config, write it as jeasx.config.jsx and compile it with your own npm script:
esbuild jeasx.config.jsx --bundle --packages=external --outfile=jeasx.config.js --platform=node --format=esm --jsx=automatic --jsx-import-source=jsx-async-runtime
Errors while streaming: the error handler only runs for errors thrown before the first chunk is sent, e.g. in a guard or before the route returns its JSX. Once streaming has started, the status and headers are already sent, and an error thrown by an async component cuts the page off. Wrap risky components in an error boundary that renders them to a string first:
import { html, jsxToString } from "jsx-async-runtime";
async function ErrorBoundary({ fallback, children }) {
try {
return html(await jsxToString.call(this, children));
} catch (error) {
this.request.log.error(error);
return fallback;
}
}
<ErrorBoundary fallback={<p>This section could not be loaded.</p>}>
<RiskyComponent />
</ErrorBoundary>;
See Catch errors for all three cases.
request.path is decoded
request.path is now URL-decoded, e.g. /caf%C3%A9 becomes /cafรฉ.
Backslashes become slashes, and repeated slashes are collapsed (//a//b
becomes /a/b).
Migration: remove decodeURIComponent(request.path) from your routes.
Decoding twice fails for paths that contain a %. Use request.url if
you need the raw path.
The dev server only listens on localhost
jeasx dev binds to localhost, so other machines on your network can't
reach it. jeasx start still listens on all interfaces (::).
Migration: if you run jeasx dev in a container or VM, or test from
another device, set HOST:
HOST=:: npx jeasx dev
Missing imports in routes are errors
Before, if a route imported a module that doesn't exist, the route was skipped as if it didn't exist (usually ending in a 404). Now the error is thrown, so you see the real cause.
Migration: fix or remove the import that is reported.
Changed responses
- If no route answers and there is no
[404]route, the response is a404instead of an empty200. - Objects returned by guards are only used as props. They are never sent as the response, even if no route answers.
- Static files are only served for
GETandHEAD. Other methods (e.g. aPOSTto/form) go to your routes, even if a file with that path exists. - If a static file is missing or ignored (e.g. a dotfile),
[...path]and[404]routes answer instead of the plain error page of@fastify/send. - A
ReadableStreamor Node.js stream returned without a content type is sent astext/html; charset=utf-8, like strings and buffers.
Migration: set a status code or content type explicitly where you
relied on the old behavior. For example, register a Fastify route in
FASTIFY_SERVER for non-GET requests to a static file.
FASTIFY_SEND_OPTIONS.root is always the project directory
Jeasx passes file paths relative to the project directory, so a custom
root broke file serving. It is now always set to the project directory.
Migration: remove root from FASTIFY_SEND_OPTIONS.
dist is cleaned before every build
jeasx build and jeasx dev delete dist before building. This removes
outputs of deleted routes, which could otherwise still be served.
Migration: don't put files into dist by hand. Use public instead.
๐ Security
- Compiled routes were exposed in development: server routes
(e.g.
/[index].js), their sourcemaps and other outputs could be fetched fromdistas static files. This exposed server-side code. They are no longer served, including Windows tricks like/[index].js.or/[index].js::$DATA. - Special routes can't be requested by name: requests like
/[index],/[...guard],/[...path]or/[--metadata--]no longer call these routes directly. The check ignores case, because case-insensitive file systems (macOS, Windows) would otherwise resolve/[--METADATA--]./a/404is still answered by/a/[404]. - Malformed paths are rejected: paths with invalid URL encoding, null
bytes or
./..segments are rejected with400. Repeated slashes are collapsed, so//evil.comcan't be mistaken for another host (e.g. in a<base>tag). - Route and file lookups ignore inherited keys: a path like
/constructorno longer matches properties ofObject.prototype. - Fewer leaked file handles: file streams are closed when the response
ends or is aborted. This includes routes that send a stream with
reply.send(). - In production, other outputs of server routes aren't static files:
CSS or other files that esbuild writes for server routes
(e.g.
[index].css) are no longer served. Before, only sourcemaps were skipped.
โจ New features
-
Async config options: all options in
jeasx.config.js(ESBUILD_SERVER_OPTIONS,ESBUILD_BROWSER_OPTIONS,FASTIFY_SERVER_OPTIONS,FASTIFY_SEND_OPTIONS) andFASTIFY_SERVERcan be async. You can import build-only plugins lazily, so they aren't loaded in production:export default { ESBUILD_BROWSER_OPTIONS: async () => ({ plugins: [(await import("esbuild-sass-plugin")).sassPlugin()], }), }; -
Dotfiles in production: files like
public/.well-known/security.txtare now part of the production build. Whether they are served depends on thedotfilesoption ofFASTIFY_SEND_OPTIONS(default: ignored), the same as in development:export default { FASTIFY_SEND_OPTIONS: () => ({ dotfiles: "allow" }), }; -
Graceful shutdown: the server closes on
SIGINT(Ctrl+C) andSIGTERMand then exits. It stops cleanly in containers (where Node runs as PID 1) and while the esbuild watcher is running. Press Ctrl+C a second time to kill it if the shutdown hangs.
๐ ๏ธ Fixes
jeasx devwaits for the first build before starting the server, so the first requests don't fail on an emptydist. Build errors are logged and the watcher keeps running.- If a file exists in both
distandpublic,distwins in production, as it does in development. Symbolic links are skipped in production builds. - Config, routes and metadata are imported with
pathToFileURL, which fixes paths on Windows and paths with special characters. - A directly requested
/a/404page keeps its status only if it is answered by/a/[404]. If a parent[404]route answers, the status is404. - File paths with special characters (e.g.
#or%) are served correctly. - esbuild no longer forces colored output, so logs in CI and log files don't contain color codes.
- The docs in
env.jsexplain the load order: a variable that is already set is never overwritten, andNODE_ENVmust come from the environment.
๐ฆ Updates to jsx-async-runtime@3.0.0
Jeasx depends on jsx-async-runtime for all rendering, so these changes
affect every Jeasx project. See the
full changelog
for every detail.
๐ฅ Breaking changes
Raw markup needs html()
{{ html: "..." }} objects render nothing. This closes an injection path,
e.g. through parsed JSON with an html key.
// Before
<>{{ html: "<!DOCTYPE html>" }}</>;
// After
import { html } from "jsx-async-runtime";
<>{html("<!DOCTYPE html>")}</>;
Escaping can't be turned off
this.jsxEscapeHTML = false was removed.
Migration: wrap trusted markup in html(). To pass trusted text through
unescaped everywhere, use a this.jsxToString override that returns it as is.
class and style must be strings
Objects and arrays are no longer converted. They render as JSON, like other attributes, and TypeScript only accepts strings.
// Before
<div class={["card", { active }]} style={{ color, "font-size": "2em" }} />;
// After (e.g. with clsx)
import clsx from "clsx";
<div class={clsx("card", { active })} style={`color: ${color}; font-size: 2em`} />;
Components get children as written
As in React, a single child is passed as is, several children as an array,
and there is no children prop without children. Before, children was
always a flattened array without null and booleans.
Migration: most components that only render {children} keep working.
If you call array methods on children, normalize it first:
function List({ children }) {
return (
<ul>
{[children ?? []].flat().map((child) => (
<li>{child}</li>
))}
</ul>
);
}
Generators passed as children are read at render time, so they can only be rendered once.
Other breaking changes
- Text is plain values: text children are strings, numbers or bigints
instead of
{ type: "textNode", text }. ThetextNodetype was removed. - Only real elements render: hand-built objects like
{ type: "tag", tag: "b", props }render nothing. UsecreateElementinstead. Copies of real elements ({ ...element, tag: "i" }) still render. - Invalid component types throw: a tag that is neither a string nor a
function (e.g.
undefinedfrom a missing import) fails with aTypeErrorinstead of rendering nothing. With the Jeasx error handling above, you now see these errors. jsxToStringcan return synchronously: it returnsstring | Promise<string>.await jsxToString(...)keeps working.- Void tags ignore children:
<br>text</br>renders<br>. - Override scope: a
this.jsxToStringoverride set by a component also applies to the siblings that follow it. - Exports: the
Tagtype was renamed toElementNode.jsxsDEVwas removed fromjsx-async-runtime/jsx-dev-runtime. - Stricter types:
aria-*attributes no longer accept booleans, andcontenteditable,spellcheck,translateandwritingsuggestionsno longer acceptfalse. Use strings likearia-hidden="true"orspellcheck="false". Add custom elements toJSX.IntrinsicElementAttributesinstead ofJSX.IntrinsicElements.
โจ New features
jsxToStreamrenders to aReadableStream<string>. Jeasx uses it for all JSX responses. It sends what is rendered so far whenever rendering waits for async work, splits large pages into ~16 KB chunks, waits for slow clients and stops when the client disconnects.isJsxNodechecks whether a value is an element orhtml()markup and narrows the type in TypeScript.- More child types:
- Promises:
<div>{fetchUser()}</div> - Iterables:
Set, generators,map.values().map(...) - Async iterables: async generator components and
ReadableStream, rendered in order as items arrive - Bytes (
Uint8Array,Buffer) as escaped UTF-8 text:<pre>{response.body}</pre> - Objects with their own
toString(Date,URL,Error, your classes) as escaped text - Functions as render props:
<Loader>{(data) => <p>{data}</p>}</Loader>
- Promises:
- Promise attributes:
<img src={loadImageUrl()} />. All promise attributes of a tag are awaited in parallel. - Better types: async components with a
Promise<JSX.Element>return type,keyon every component,nullattributes, and JSX types for"jsx": "react-jsxdev".
๐ Security
- Only markup created by
html()is rendered raw. - Elements carry a Symbol marker, so JSON look-alikes such as
{"type":"tag","tag":"script",...}render nothing. - Attribute names with whitespace, quotes,
<,>,/,=,&or control characters are skipped, and so are invalid tag names (with their children). Valid names likeonmouseoverorscriptstill render, so allowlist attributes and tags that come from untrusted input. - Keys inherited from a polluted
Object.prototypeare ignored.
๐ ๏ธ Fixes
- Rejected promises in props no longer crash Node with an unhandled rejection. The error goes to the render.
- Streams that are never rendered (e.g. in a void tag or after a failed render) are closed, so they don't keep connections or files open.
- Functions and symbols in attributes are skipped. Event handlers no longer print their source code.
keyis never rendered, and components don't receive it in their props.createElementno longer modifies the props you pass in.- Rendering without a context gives each render its own empty context, so data no longer leaks between renders.
escapeEntitiesconverts non-strings withString()before escaping.
Dependency updates: jsx-async-runtime@3.0.0, @types/node@26.6.6
2026-10-23 - Jeasx 2.10.7 released
Core changes
-
New: Routes and guards can return a web
ResponseorReadableStream, which is served directly. -
Fixed: File handles leaked when a guard or route responded before a static file was served. The file stream is now always closed.
-
Security: Requesting a guard file by its literal path (e.g.
/admin/[...guard]) was treated as a static file request and bypassed the guard. Guards now run for these requests as well.
Updates to jsx-async-runtime
-
Attribute rendering is about 1.5x faster, because it no longer builds intermediate arrays.
-
Empty style objects and
null,undefinedorfalsestyle values are no longer rendered. -
0is now rendered when it is the only child (e.g.<h1>{0}</h1>). -
bigintchildren are now rendered. -
Arrays returned by components are now rendered.
Dependency updates: jsx-async-runtime@2.3.0, @fastify/send@4.2.0
2026-10-13 - Jeasx 2.10.6 released
๐ Security update for Fastify (GHSA-389g-gv7q-r4x8).
This release adds a minor performance improvement by switching checks for guards which return additional props.
Dependency updates: fastify@5.12.7, @fastify/send@4.1.2, @types/node@26.6.5
2026-10-01 - Jeasx 2.10.5 released
๐ Security update for Fastify (GHSA-4mh8-r7rc-xpvc).
Dependency updates: fastify@5.12.5, @types/node@26.6.3
2026-09-11 - Jeasx 2.10.4 released
๐ Just some dependency updates...
Dependency updates: fastify@5.12.4, jsx-async-runtime@2.2.1, @types/node@26.5.1
2026-09-04 - Jeasx 2.10.3 released
๐ More efficient route handling
The central method generateRoutes has been updated to use a JavaScript generator instead of building and checking an array of all routes. This change reduces unnecessary memory usage and computational overhead, as most routes are matched early in the sequence and no longer require being pushed to an array.
๐ Security updates
This version addresses four security vulnerabilities in the fastify dependency:
We strongly recommend updating to this version to ensure the security of your application.
Dependency updates: fastify@5.12.3, @types/node@26.4.1
2026-08-22 - Jeasx 2.10.2 released
๐ Security fixes for Fastify (GHSA-w2qp-rph6-63g4 and GHSA-3m5p-2c4r-xxw2)
Dependency updates: fastify@5.12.1
2026-08-15 - Jeasx 2.10.1 released
๐ Just a bunch of dependency updates...
Dependency updates: fastify@5.12.0, @fastify/send@4.1.1, esbuild@0.28.2, @types/node@26.2.0
2026-08-04 - Jeasx 2.10.0 released
๐ BUILD_TIME moved to userland
As part of my ongoing goal to move features from the core into userland, Iโve removed the core-level BUILD_TIME variable. While this simplifies the core, I want to ensure your builds aren't affected. If you use BUILD_TIME for cache busting, you can now let esbuild handle it directly using the powerful define option in your jeasx.config.js:
/** @type {() => import("esbuild").BuildOptions} */
ESBUILD_SERVER_OPTIONS: () => ({
define: { "process.env.BUILD_TIME": `"${Date.now().toString(36)}"` },
});
This configuration replaces all references to process.env.BUILD_TIME with a Base36 (a-z0-9) encoded timestamp as string (note the additional quotes above).
I have also removed the automatic provision of BROWSER_PUBLIC_ environment variables to frontend bundles. This gives you the freedom to define your own schema; simply add the appropriate define option to ESBUILD_BROWSER_OPTIONS to specify which variables should be available to the frontend.
Dependency updates: fastify@5.11.2
2026-07-30 - Jeasx 2.9.1 released
๐ Routine maintenance release.
BUILD_TIME is now injected into the environment during the build process, before jeasx.config.js is loaded. This enables you to capture the build timestamp for use during runtime (e.g. for using it in FASTIFY_SERVER_OPTIONS#rewriteUrl).
Dependency updates: fastify@5.11.0, @types/node@26.1.2
2026-07-17 - Jeasx 2.9.0 released
โจ Less is more... trimming the fat
This release removes @fastify/formbody, @fastify/cookie, and @fastify/multipart as core dependencies. Since Jeasx is capable of powering serious, real-world projects without these dependencies, removing them keeps your project's footprint as small as possible. This allows you to enable them individually, only when your specific use case requires them.
- Forms: Install
@fastify/formbodyif your project requires POST form support. - Cookies: Install
@fastify/cookieif you need to handle HTTP cookies. - Uploads: Install
@fastify/multipartif your project handles file uploads.
Jeasx is built on the philosophy of providing a powerful core while pushing customizations to the user level. By avoiding opinionated defaults, Jeasx gives you the freedom to build a setup that is uniquely your own.
Need these features? No problem! Jeasx makes it easy to customize your stack. To get back to the exact setup from previous releases, just add these dependencies directly to your project:
npm install @fastify/formbody @fastify/cookie @fastify/multipart
Next, update your jeasx.config.js with the following configuration to customize your Fastify server instance:
/** @type {(fastify: import("fastify").FastifyInstance) => import("fastify").FastifyInstance} */
FASTIFY_SERVER: (fastify) =>
fastify
.register(import("@fastify/formbody"), {/* insert options from FASTIFY_FORMBODY_OPTIONS */})
.register(import("@fastify/multipart"), {/* insert options from FASTIFY_MULTIPART_OPTIONS */})
.register(import("@fastify/cookie"), {/* insert options from FASTIFY_COOKIE_OPTIONS */});
Because plugins like @fastify/cookie and @fastify/multipart extend the request and reply objects, you should add the following imports to src/types.d.ts (or a similar definition file in your project) to ensure proper TypeScript support for your editor:
import "@fastify/cookie";
import "@fastify/multipart";
This release also removes the additional encapsulation context from the Fastify initialization. This change allows for a more direct and flexible customization of the underlying Fastify instance.
Dependency updates: jsx-async-runtime@2.2.0, @types/node@26.1.1
2026-07-07 - Jeasx 2.8.1 released
๐ You can now access static file metadata in guards directly via reply.file. If a file exists for the requested path, this object will be pre-populated with headers, statusCode, and stream for the current file. This eliminates the need for manual checks when performing logic on static files, including:
- Skipping basic authentication.
- Dynamically modifying headers.
- Replacing content on the fly.
Check out the new basic auth example for implementation details.
Also refined type definitions in serverless.ts to improve code readability and maintainability.
Dependency updates: fastify@5.10.0
2026-07-03 - Jeasx 2.8.0 released
๐ Unified Asset & Route Handling
This release completes the architectural transition of merging dynamic server routes and static browser assets into a common directory tree. While Jeasx 2.6 removed the strict directory separation, this version further unifies how these files are processed.
Previously, browser assets were served directly by @fastify/static, while server routes were handled by the route handler. This created a limitation where server-side logic (like authentication or custom headers) couldn't be applied to static assets.
With this release, all files - regardless of type - are now handled directly by the route handler. This introduces several major improvements:
-
Enhanced Control: You can now use guards to modify responses for static assets, such as adding security headers or implementing password protection.
-
Hot-Reloading for Assets: Static files in development mode are now picked up instantly. No application restarts are required to make new files accessible.
-
Production Optimization & Security: In production, static files are mapped into a metadata export at build time. This improves server startup performance by eliminating file globbing and provides robust protection against path traversal attacks.
โ ๏ธ Important Migration Note
To achieve these improvements, @fastify/static has been removed as a direct dependency in favor of @fastify/send. Since @fastify/static relied on @fastify/send internally, this change provides more flexibility while maintaining the same functionality with fewer dependencies.
A minor configuration change is required to make your application work as expected. You'll need to change references in jeasx.config.js from @fastify/static to @fastify/send .
// BEFORE
/** @type {() => import("@fastify/static").FastifyStaticOptions} */
FASTIFY_STATIC_OPTIONS: () => ({/* configuraton options */}),
// AFTER
/** @type {() => import("@fastify/send").SendOptions} */
FASTIFY_SEND_OPTIONS: () => ({/* configuraton options */}),
Because the configuration options for @fastify/static and @fastify/send are almost identical, no changes to existing options are required for most users.
Dependency updates: @fastify/send@4.1.0, @types/node@26.1.0
2026-06-28 - Jeasx 2.7.5 released
๐ This release focuses on internal improvements and codebase organization. I have renamed esbuild.config.js to build.js and server.js to start.js to more accurately reflect their roles within cli.js. The renamed scripts are intended for internal use and should not be called directly. If your current workflow requires calling them, please update your project configuration accordingly.
Additionally, minor refactorings were applied to cli.js and env.js to improve maintainability.
Dependency updates: fastify@5.9.0, @types/node@26.0.1
2026-06-21 - Jeasx 2.7.4 released
๐ Introduced pre-calculation of all module paths during server startup for production environments. This provides a robust defense against path traversal attacks from malformed requests, even in scenarios where Fastifyโs built-in path sanitization might fail.
Optimized path processing by skipping empty segments directly, removing the overhead of filtering segments into new arrays before iteration.
Improved the module loading logic for development mode to ensure better compatibility with Node.js and alternative JavaScript runtimes like Bun.
Dependency updates: @types/node@26.0.0
2026-06-12 - Jeasx 2.7.3 released
๐ Routine maintenance release.
Dependency updates: jsx-async-runtime@2.1.3, esbuild@0.28.1, @types/node@25.9.3
2026-06-10 - Jeasx 2.7.2 released
๐ This release introduces significant performance and memory optimizations:
-
The core
generateRoutesmethod has been rewritten to improve execution speed and significantly reduce temporary array creation. This minimizes garbage collection overhead during high-load scenarios. -
The internal cache has been migrated from a
Mapto a plain object to leverage engine-level optimizations for small, read-heavy collections. I've also added a missing type definition for the module cache. -
The
.jsextension is now stripped from route export metadata during the build process, reducing the number of string operations required when resolving modules from the cache.
2026-06-07 - Jeasx 2.7.1 released
๐ This patch release requires no changes to your project but introduces significant improvements to internal module handling: Previously, a dynamic runtime cache was used to resolve modules for routes. This cache stored entries for both existing and non-existent routes, leading to potential growth over time - despite a predefined maximum cache size.
With this update, the cache strategy has been optimized for more efficient and sustainable memory usage: This release leverages esbuildโs metadata to generate a static metadata file at build time, containing all existing routes. This metadata is loaded during server startup, ensuring that only modules included in the routes list are loaded on the first request.
The result? Fast cold starts, efficient handling of existing and non-existent routes (without caching overhead), and enhanced security. Since only modules generated at build time can be loaded, even in the unlikely case where a malformed request could bypass Fastifyโs strict request sanitation, it cannot escape the dist directory.
The changes above have no impact on your development workflow. You can continue creating new routes or modifying existing ones - your updates will be loaded automatically, without requiring a restart of the application.
Dependency updates: @types/node@25.9.2
2026-06-02 - Jeasx 2.7.0 released
๐ This release introduces an explicit configuration file named jeasx.config.js, replacing the previously used .env.js. This change improves clarity and usability for configuring esbuild and Fastify options, which could no longer be passed as environment variables in recent releases.
To upgrade:
- If you used
.env.jsbefore, just rename it tojeasx.config.js. - If you didnโt use
.env.js, create a new file calledjeasx.config.jsin your project folder. Add the following code as default to get a reminder of all available configuration options:
export default {
/** @type {() => import("esbuild").BuildOptions} */
// ESBUILD_SERVER_OPTIONS: () => ({}),
/** @type {() => import("esbuild").BuildOptions} */
// ESBUILD_BROWSER_OPTIONS: () => ({}),
/** @type {(fastify: import("fastify").FastifyInstance) => import("fastify").FastifyInstance} */
// FASTIFY_SERVER: (fastify) => fastify,
/** @type {() => import("fastify").FastifyServerOptions} */
// FASTIFY_SERVER_OPTIONS: () => ({}),
/** @type {() => import("@fastify/static").FastifyStaticOptions} */
// FASTIFY_STATIC_OPTIONS: () => ({}),
/** @type {() => import("@fastify/cookie").FastifyCookieOptions} */
// FASTIFY_COOKIE_OPTIONS: () => ({}),
/** @type {() => import("@fastify/formbody").FastifyFormbodyOptions} */
// FASTIFY_FORMBODY_OPTIONS: () => ({}),
/** @type {() => import("@fastify/multipart").FastifyMultipartOptions} */
// FASTIFY_MULTIPART_OPTIONS: () => ({}),
};
If youโre using Docker, make sure to create an entry for jeasx.config.js in your .dockerignore file.
Please note: Support for .env.js has been discontinued in this release to streamline and simplify the codebase. If you previously used .env.js to set or modify environment variables besides the existing configuration options, you can now do this directly in jeasx.config.js by modifying process.env using JavaScript.
process.env.API_ENDPOINT = "https://expo.jeasx.dev/jokes/api/";
export default {/* ... */};
Dependency updates: @types/node@25.9.1
2026-05-14 - Jeasx 2.6.2 released
๐ This release moves the configuration for esbuildโs sourcemap settings from core to userland. Since there is no universal default that fits all environments and policies, this change allows for greater flexibility.
To enable sourcemaps for debugging your code, configure ESBUILD_SERVER_OPTIONS or ESBUILD_BROWSER_OPTIONS in your .env.js file based on your specific needs. While I recommend using inline as the configuration value for simplicity, the optimal choice may depend on your setup and tooling.
Please study the esbuild documentation for the different configuration options.
/** @type {() => import("esbuild").BuildOptions} */
ESBUILD_SERVER_OPTIONS: () => ({
sourcemap: "inline",
});
2026-05-12 - Jeasx 2.6.1 released
๐ This release includes a small update to the tsconfig.json file: The types attribute has been adjusted from ["*"] to ["node"] to align with the TypeScript teamโs best practices. This change ensures better type resolution and resolves a warning that appeared when using Zed as the editor.
Dependency updates: @types/node@25.7.0
2026-05-08 - Jeasx 2.6.0 released
๐ Back in the early days, Jeasx enforced a strict separation between browser and server code. This meant developers had to organize their projects into specific directories like browser and routes. Over time, this limitation was lifted, allowing for more flexible project structures. While you could freely arrange your application code in the src directory, the dist directory still maintained the separation between browser and server files.
This created a significant challenge: esbuild loaders (such as those for importing files or using CSS modules) couldnโt be applied to server routes. The reason? Assets generated for the server and stored in dist/server were inaccessible to the browser, making it impossible to leverage these powerful tools in server-side code.
Here are the good news: everything in the dist folder is now organized exactly as youโve structured your application, hard coded sub-directories for browser and server are gone for good. All files in the dist directory are delivered directly to the browser via @fastify/static, except the code for server routes (JavaScript files enclosed in square brackets) - this code is still handled on the server. Now you are free to utilize esbuild loaders for your routes and enjoy all the advanced esbuild configurations for bundling server-side code.
โ ๏ธ Required updates to .env.js
Previously, common browser asset extensions (e.g., .ttf, .woff2, .svg, .jpg) were automatically treated as external by Jeasx. This meant they were excluded from the bundling process by esbuild. For example, font files or icons stored in the public directory and referenced in your bundled CSS files would not be processed by esbuild.
Now, no extensions are marked as external by default anymore. If your build fails with an error like ERROR: No loader is configured for ".woff2", youโll need to explicitly mark the missing extensions as external in your .env.js configuration by updating the ESBUILD_BROWSER_OPTIONS.
Also Jeasx no longer sets a default value for the esbuild target option. I recommend configuring it explicitly based on your projectโs needs. If you donโt specify a value, esbuild will default to esnext.
The example below restores the former esbuild settings used by Jeasx, ensuring a smooth transition to the current release.
/** @type {() => import("esbuild").BuildOptions} */
ESBUILD_BROWSER_OPTIONS: () => ({
// Itโs best to start with an empty list and
// only add extensions that cause build errors.
external: [
"*.avif",
"*.gif",
"*.jpg",
"*.jpeg",
"*.png",
"*.svg",
"*.webp",
"*.eot",
"*.ttf",
"*.otf",
"*.woff",
"*.woff2",
],
target: ["chrome130", "edge130", "firefox130", "safari18"],
});
After the update, you should start using the esbuild loader to handle assets. To help you get started, hereโs an example of how you can import images directly in your server routes. Simply configure the file loader for .jpg files in your .env.js file:
/** @type {() => import("esbuild").BuildOptions} */
ESBUILD_SERVER_OPTIONS: () => ({
loader: { ".jpg": "file" },
});
You can now import an image located next to your server route and reference it in your code. This way esbuild automatically hashes the image path, so you donโt need to manually update references - even with caching headers applied.
import Image from "./image.jpg";
export default function () {
return (
<figure>
<img src={Image} alt="Example image" />
</figure>
);
}
If you encounter a TypeScript warning for the import, you can resolve it by adding a definition file (e.g., jpg.d.ts) to specify the correct typing.
declare module "*.jpg" {
const content: string;
export default content;
}
Dependency updates: jsx-async-runtime@2.1.2, @types/node@25.6.2
2026-04-24 - Jeasx 2.5.3 released
๐ Just dependency updates...
Dependency updates: @fastify/static@9.1.3
2026-04-20 - Jeasx 2.5.2 released
๐ This release resolves an issue where existing routes failed to load if a JavaScript error occurred during initialization (for example, when setting up a global scoped variable). Previously, this error was masked by returning a 404 route, causing the route to never be re-evaluated.
2026-04-16 - Jeasx 2.5.1 released
๐ Upgrade to latest @fastify/static to fix CVE-2026-6410 and CVE-2026-6414.
Dependency updates: @fastify/static@9.1.1
2026-04-15 - Jeasx 2.5.0 released
๐ This release removes all non-essential Fastify configuration options from the Jeasx core, aligning it more closely with Fastifyโs well-chosen default settings.
To maintain your previous behavior, I recommend making minor adjustments to your configuration via .env.js:
export default {
// ...
FASTIFY_SERVER_OPTIONS: () => ({
logger: { level: process.env.NODE_ENV === "development" ? "error" : "info" },
// 'disableRequestLogging' should be removed.
}),
FASTIFY_MULTIPART_OPTIONS: () => ({
// Only relevant if you use file uploads in your project.
attachFieldsToBody: "keyValues",
}),
// ...
};
Additionally, the configured Fastify logger is now used for error logging, replacing the previous use of console.error.
This release also addresses CVE-2026-33806 by upgrading to the latest Fastify version.
Dependency updates: fastify@5.8.5, @types/node@25.6.0
2026-04-09 - Jeasx 2.4.8 released
๐ Just some dependency updates...
Dependency updates: @fastify/multipart@10.0.0, @fastify/static@9.1.0
2026-04-04 - Jeasx 2.4.7 released
๐ Just some dependency updates...
Dependency updates: jsx-async-runtime@2.1.1, esbuild@0.28.0, @types/node@25.5.2
2026-04-02 - Jeasx 2.4.6 released
๐ This release updates the tsconfig.json settings to fully support the latest TypeScript 6 changes. Now, the latest version of VSCode runs smoothly without any warnings.
Dependency updates: esbuild@0.27.7
2026-03-25 - Jeasx 2.4.5 released
๐ Just a patch update to stay synced with latest jsx-async-runtime.
Dependency updates: jsx-async-runtime@2.1.0
2026-03-23 - Jeasx 2.4.4 released
๐ Just a patch release to update Fastify to fix CVE-2026-3635.
Dependency updates: fastify@5.8.4
2026-03-14 - Jeasx 2.4.3 released
๐ Just some dependency updates...
Dependency updates: fastify@5.8.2, esbuild@0.27.4, @types/node@25.5.0
2026-03-05 - Jeasx 2.4.2 released
๐ Just a patch release to update Fastify to fix CVE-2026-3419.
Jeasx uses from now on trusted publishing for npm packages to release new versions.
Dependency updates: fastify@5.8.1, jsx-async-runtime@2.0.3
2026-03-02 - Jeasx 2.4.1 released
๐ This release introduces route prop inheritance from guards. Guards can return objects whose entries are used as additional props for your routes. Previously, only props from the closest guard were used. With this update, props from all guards along the route are collected and passed down. If multiple guards provide props with the same key, the value from the guard nearest to the route takes precedence and overwrites earlier ones.
Dependency updates: @types/node@25.3.3
2026-02-20 - Jeasx 2.4.0 released
๐ This release is both a step forward and a step back: the recently introduced support for MDX has been removed from the core project. Jeasx aims to keep its core as lean as possible, so this change aligns with the project's overall goals. Since MDX is not essential for every Jeasx website or application, it makes sense to move it out of the core.
Another key goal of Jeasx is to empower users to implement their own custom solutions in userland, providing the right tools to do so. In short, while MDX remains a fantastic technology for content-driven websites, Jeasx now lets you configure MDX support yourself through a much improved configuration system for its base technologies like esbuild and Fastify.
For esbuild, two new configuration options are available: ESBUILD_SERVER_OPTIONS and ESBUILD_BROWSER_OPTIONS. These can be defined as functions in .env.js that return additional configuration settings for esbuild.
Why use functions instead of plain objects for the configuration? Because using functions allows configurations to be created lazily - only when needed - which is especially helpful for more complex setups over time.
If you want to use MDX with Jeasx, simply run npm install @mdx-js/esbuild and add the configuration below to ESBUILD_SERVER_OPTIONS in .env.js.
If you've used ESBUILD_BROWSER_TARGET in the past, you have to move this configuration to ESBUILD_BROWSER_OPTIONS as shown below.
import mdx from "@mdx-js/esbuild";
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",
}),
],
}),
/** @type {() => import("esbuild").BuildOptions} */
ESBUILD_BROWSER_OPTIONS: () => ({
target: ["chrome130", "edge130", "firefox130", "safari18"],
}),
};
The existing configuration options for Fastify (such as FASTIFY_SERVER_OPTIONS, FASTIFY_COOKIE_OPTIONS, FASTIFY_MULTIPART_OPTIONS, FASTIFY_STATIC_OPTIONS) now require a minor change: they must be defined as functions instead of plain objects.
Additionally, you can now customize the Fastify server instance using the optional FASTIFY_SERVER function. This function receives the created server instance and should return the modified version. This feature is especially useful when integrating existing Fastify plugins like @fastify/compress, as demonstrated below.
import fastifyCompress from "@fastify/compress";
const NODE_ENV_IS_DEVELOPMENT = process.env.NODE_ENV === "development";
export default {
/** @type {(fastify: import("fastify").FastifyInstance) => import("fastify").FastifyInstance} */
FASTIFY_SERVER: (fastify) => fastify.register(fastifyCompress),
/** @type {() => import("fastify").FastifyServerOptions} */
FASTIFY_SERVER_OPTIONS: () => ({
disableRequestLogging: NODE_ENV_IS_DEVELOPMENT,
bodyLimit: 1024 * 1024,
}),
/** @type {() => import("@fastify/static").FastifyStaticOptions} */
FASTIFY_STATIC_OPTIONS: () => ({
immutable: !NODE_ENV_IS_DEVELOPMENT,
maxAge: NODE_ENV_IS_DEVELOPMENT ? 0 : "365d",
}),
};
Another notable change is that the fallback content-type (text/html) for routes is now set as late as possible. This means you can return plain JavaScript objects from routes, which will be automatically sent as application/json by default - without needing to explicitly specify the content-type in your code. This update brings Jeasx in line with Fastifyโs default behavior.
Additionally, you can now define routes directly from simple *.json or *.txt files - perfect for creating static endpoints like a health check or a robots.txt file right in your routes folder.
Dependency updates: @types/node@25.3.0
2026-02-12 - Jeasx 2.3.2 released
๐ Upgraded to @types/node@25, enabling seamless development with Node 25 while maintaining compatibility for Node 24 users.
Dependency updates: esbuild@0.27.3, @types/node@25.2.3
2026-02-04 - Jeasx 2.3.1 released
๐ Just a patch release to update Fastify to fix CVE-2026-25224.
Additionally, I performed minor refactorings identified by oxlint and replaced prettier with oxfmt, a high-performance formatter optimized for the JavaScript ecosystem.
Dependency updates: fastify@5.7.4, @types/node@24.10.10
2026-01-30 - Jeasx 2.3.0 released
๐ This release introduces support for MDX, enabling you to seamlessly embed JSX within Markdown content. Just create a route with a .mdx extension, and youโre all set to enhance your websites and blogs with Markdown enriched by dynamic JSX components.
import Layout from "./Layout";
<Layout title="MDX - Markdown for the component era">
# MDX as content companion alongside JSX You can easily access existing `props` in MDX: - Current
url: {props.request.url}
</Layout>;
You can also create MDX-based components for use within JSX by importing them with their full .mdx file extension into your JSX routes or components.
Since MDX supports a variety of plugins - and Jeasx provides only the MDX core to stay focused on infrastructure while letting users handle customization - the overall configuration for Jeasx has been significantly improved. Now, 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. Previously, (de)serializing the configuration via process.env restricted this capability and limited advanced setups.
Please note: Variables loaded from .env.js now consistently overwrite any existing environment variables. This ensures predictable and consistent behavior across your configuration.
Hereโs an example of how to configure the MDX engine: if you want to enable GitHub-flavored Markdown (remark-gfm), add syntax highlighting (rehype-prism-plus), and generate IDs for your headings (rehype-slug), you can install and configure these plugins accordingly in .env.js.
import rehypePrismPlus from "rehype-prism-plus";
import rehypeSlug from "rehype-slug";
import remarkGFM from "remark-gfm";
export default {
/** @type import("@mdx-js/esbuild").Options */
ESBUILD_MDX_OPTIONS: {
remarkPlugins: [[remarkGFM, { singleTilde: false }]],
rehypePlugins: [rehypePrismPlus, [rehypeSlug, { prefix: "jeasx-" }]],
},
//...
};
For a full overview of available configuration options and plugins, check out the excellent documentation of @mdx-js/esbuild.
Please note: The update to the Jeasx configuration introduced a minor change in how ESBUILD_BROWSER_TARGET is specified to ensure consistency across the configuration. Previously, a comma-separated string was accepted and parsed as customization. Going forward, you must provide a proper JSON array (or its stringified form when using traditional .env files or the process environment).
export default {
/** @type import("esbuild").BuildOptions["target"] */
ESBUILD_BROWSER_TARGET: ["chrome130", "edge130", "firefox130", "safari18"],
//...
};
Dependency updates: fastify@5.7.2, @fastify/multipart@9.4.0
2026-01-17 - Jeasx 2.2.2 released
๐ This release now preserves the original status code when a 404 page is accessed directly (defaults to 200). This improvement makes it easier to use Jeasx as a static site generator and to fetch the 404 page with common tools for saving it to a file system.
While Jeasx is fundamentally a server-side rendering framework, there are valid use cases where serving a static page alone is sufficient. For example, you can use wget to download a Jeasx website to a www-directory with just a single line:
wget --mirror --page-requisites --no-host-directories --directory-prefix=www http://localhost:3000 http://localhost:3000/404
Have a look at the Dockerfile of the Jeasx website to see how things can be wired up for serving a static export with Caddy as web server.
If you want to restore the old behaviour (directly calling /404 resulting in status code 404), you can simple add reply.status(404) to your /[404] handler.
Dependency updates: fastify@5.7.1, @fastify/static@9.0.0, @types/node@24.10.9