FAQ
Frequently Asked Questions
Here you can find some frequently asked questions and recipes to customize Jeasx.
How is Jeasx officially pronounced?
Jeasx is a combination of the words "JSX" and "ease". The phonetic transcription is d͡ʒizɛks.
Is there something like a context object similar to React?
Yes, Jeasx provides a context object via this, which is passed on to all sub-components automatically. See context for details.
How can I provide user friendly error messages?
Register a Fastify error handler via setErrorHandler in jeasx.config.js and add a [404] route for unknown URLs. Errors thrown while a page is already streaming need an error boundary. The Errors & Logging page explains all cases in detail.
How can I modify the resulting response (e.g. post-process HTML)?
For example, if you want to prettify the HTML output, you can wire up a response handler in any endpoint (e.g. a guard). The response handler takes the resulting payload as a parameter and returns the modified payload. For JSX routes, the payload is a ReadableStream, so read it into a string before changing it. Pages that are post-processed this way are not streamed to the browser.
import * as prettier from "prettier";
...
export default function ({ request, reply }) {
this.responseHandler = async (payload) => {
// JSX responses are streamed, so read the stream into a string first
if (payload instanceof ReadableStream) {
payload = (await Array.fromAsync(payload)).join("");
}
// Jeasx sets the default content type (text/html) after the response handler,
// so a missing content type means HTML, too.
const type = reply.getHeader("content-type");
return typeof payload === "string" &&
(type === undefined || String(type).startsWith("text/html"))
? await prettier.format(payload, { parser: "html" })
: payload;
};
}
Is there a way to set the document title in a sub-component (aka Helmet)?
In most cases, you don't need one: pass the title and description as props to your layout, as the route knows best what it renders:
export default function ({ request }) {
return (
<Layout title="My books" description="All books on my reading list">
...
</Layout>
);
}
Jeasx renders the page in order, so the <head> is already sent when a nested component runs. If a deeply nested component has to change the title, have a look at the head example, which shows how this can be achieved with a guard.
Is it possible to use CSS frameworks like Sass or Tailwind?
Certainly! As Jeasx supports all esbuild plugins, you can use the existing ecosystem.
Can I use Jeasx as a Static Site Generator (SSG)?
Yes, of course. Jeasx is a server side rendering framework at its heart, but it can be easily used to export a static site. In order to do so, build your application and start it in production mode. Set NODE_ENV=production for both steps, as the build reads jeasx.config.js and your .env files, too:
export NODE_ENV=production
npm run build
npm start
Then execute the following commands in a second terminal to export your site to a www-directory, which can be easily served via a simple file-server:
wget --mirror --page-requisites --no-host-directories --directory-prefix=www http://localhost:3000 http://localhost:3000/404
cp -a public/* www
wget only saves pages and files which are linked from your pages, so the contents of public (e.g. robots.txt or a sitemap.xml) are copied afterwards. The 404 page is requested directly, so it is exported with status 200 (see 404 routes).
Have a look at the Dockerfile of this website to see how things can be wired up for serving a static export with Caddy as file-server.
How to use Browsersync with Jeasx?
If you want to reload CSS automagically, start Browsersync in proxy-mode in a second terminal:
npx -y browser-sync start -w -f "dist/**/index.css" -p localhost:3000
How to use a debugger with Jeasx?
To enable sourcemaps for debugging your code, configure ESBUILD_SERVER_OPTIONS or ESBUILD_BROWSER_OPTIONS in your jeasx.config.js file based on your specific needs. While inline is recommended 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.
export default {
/** @type {() => import("esbuild").BuildOptions} */
ESBUILD_SERVER_OPTIONS: () => ({
sourcemap: "inline",
}),
};
Can I use TypeScript?
Yes. esbuild compiles TypeScript out of the box, so you can write routes, components and browser code as .ts or .tsx files (e.g. src/[index].tsx or src/browser/index.ts) without any configuration.
Your tsconfig.json only has to extend the configuration shipped with Jeasx, which sets up JSX with jsx-async-runtime:
{
"extends": "jeasx/tsconfig.json"
}
To get types for the request and reply props, define them once in src/types.d.ts. Importing jeasx/serverless adds the types for request.path, request.route and reply.file, which Jeasx adds to Fastify:
// src/types.d.ts
import type { FastifyReply, FastifyRequest } from "fastify";
import "jeasx/serverless";
type RouteProps = {
request: FastifyRequest;
reply: FastifyReply;
};
// Assumes your root guard puts request and reply into the context
type ThisContext = RouteProps & {
// Add your own context properties here
};
Then use these types in your routes and components. Components which read the context declare the type of this as first parameter:
// src/[hello].tsx
import type { RouteProps, ThisContext } from "./types";
export default function ({ request }: RouteProps) {
const { name = "World" } = request.query as { name?: string };
return <Greeting name={name} />;
}
function Greeting(this: ThisContext, { name }: { name: string }) {
return <h1 title={this.request.path}>Hello {name}</h1>;
}
If you prefer plain JavaScript, you get the same type hints in your editor with JSDoc comments, e.g. /** @param {import("./types").RouteProps} props */ or /** @this {import("./types").ThisContext} */.
Please note: esbuild only removes types, it doesn't check them. Install typescript and run npx tsc --noEmit (e.g. in your CI) to find type errors. jeasx.config.js isn't compiled by esbuild, so it can't be written in TypeScript unless you compile it yourself (see configuration).
How can I test my routes and components?
Routes and components are plain functions, so you can call them with props you create yourself and render the result to a string with jsxToString. Guards that return props help here: routes which receive their data as props don't need a real request at all.
// src/components/Greeting.test.jsx
import assert from "node:assert/strict";
import { test } from "node:test";
import { jsxToString } from "jsx-async-runtime";
import Greeting from "./Greeting";
test("escapes the name", async () => {
const html = await jsxToString(<Greeting name="<b>Bob</b>" />);
assert.match(html, /<b>Bob<\/b>/);
});
Test files contain JSX, so run them with a test runner that compiles JSX with jsx-async-runtime as import source or bundle them with esbuild first. For end-to-end tests, start your app with npm run build && npm start and use a tool like Playwright. Test files without brackets in their names are never exposed as routes.