SolidStart SSR + Jitar example

This is an exploratory project aimed at integrating Jitar with SolidStart and leverage its SSR capabilities.

As of this writing, Jitar does not support Solid or SSR. Please do not expect to find a complete solution yet.

Note: Jitar is already integrated in this example. For integrating it into your own project, a detailed description is provided below. While following along can be useful for learning and experimentation, do not use this approach for production applications.

Installation

Simply install the dependencies, and the setup is complete.

npm install

Running the app

Step 1 - Build the app

The full build can be performed with a single command.

npm run build

Under the hood, the build will be performed in two separate steps in this specific order:

1. Jitar build
2. Solid build

This process creates two important folders:

1. .jitar - contains the segmented application used by Jitar (domain only)
2. .output - contains the fully build application used by Solid (combination of webui and domain, depending on the segmentation)

Step 2 - Perform manual fixes

The Jitar Vite plugin creates an additional bundle for setting up Jitar and adds it to the HTML so that it is loaded by the web browser before rendering any component. This works out of the box without issues. However, when rendering components on the server side, the same bundle is required. Without it, the server throws an error stating that it cannot find the __run function, which is globally defined by Jitar.

Because Solid support is not yet available, we need to add this bundle to the server manually for now. For this, we need the following files:

1. Created Jitar bundle: .output/public/_build/assets/jitar-bundle-[random].js (the random part differs each build)
2. Solid server runtime: .output/server/index.mjs (on older versions: .output/server/chunks/runtime.mjs)

Once located, we import the Jitar bundle at the top in the Solid runtime:

import '../public/_build/assets/jitar-bundle-[random].js';
// other imports

Since the bundle is designed for use in a web browser, we need to modify it to provide the Jitar server URL when running on the server side. The quick fix for this specific example looks like this:

// Replace
document.location.origin

// With
globalThis.document?globalThis.document.location.origin:'http://localhost:3001'

Important: These steps need to be repeated after each build.

Step 3 - Start the app

Solid and Jitar both provide their own servers, and therefore need to be started separately using two terminals.

Terminal 1 - Jitar

npm run start-jitar

Terminal 2 - Solid

npm run start-solid

The application should be now available at: http://localhost:3000

You should be able to see that the web browser receives he server rendered HTML containing the message provided by Jitar.

Integration process

These are the steps to integrate Jitar. Follow them to add Jitar to your own project.

Step 1 - Restructure the source

For a clean separation of the frontend and domain logic it's recommended to move all Solid code to it's own subfolder like src/webui. This move requires a small addition to the app.config.ts file.

export default defineConfig({
    appRoot: "./src/webui", // Add this line
});

Next, a separate folder can be added for the domain like src/domain.

Step 2 - Setup Jitar

First, add the jitar and plugin-vite dependencies to your project:

npm install jitar
npm install --save-dev @jitar/plugin-vite

Note that Jitar can also be installed globally for use across multiple projects.

Next, add Jitar configurations to the root of the project:

• segments folder with at least one segment configuration.
• services folder with at least a standalone configuration.
• jitar.json file to configure the correct source and target folders.
• tsconfig-jitar.json file to decouple the domain builds from Solid.

Lastly, add a build and start script to the package.json file.

Examples and values can be found this project's configurations.

Step 3 - Integrate Jitar

Add the Jitar Vite plugin to the app.config.ts file and configure it to the setup created in the previous step.

Step 4 - Test if it works

Perform the following actions in order:

• Run the Jitar build
• Run the Solid build
• Start Jitar
• Start Solid

Then, open the application to see if it works.

Learnings

From this project, we learned that we need to:

1. make our client bundle compatible with server-side clients, and
2. create a Solid plugin that dynamically adds the bundle to its runtime.

Both need to be addressed to support SolidStart + SSR in a production‑worthy way.