@nerest/nerest 0.0.1

package/README.md

@@ -0,0 +1,30 @@
+# @nerest/nerest
+
+React micro frontend framework
+
+> TODO: purpose, outline, documentation
+
+## Installation
+
+```
+npm i --save @nerest/nerest react react-dom
+```
+
+## Conventions
+
+The `apps` directory must contain all of the apps provided by the micro frontend. E.g. `/apps/foo/index.tsx` is the entrypoint component of the `foo` app. It becomes available as the `/api/foo` route of the micro frontend server.
+
+The single app directory may contain an `examples` subdirectory with example JSON files which can be used as props for the app entrypoint component. E.g. `/apps/foo/examples/example-1.json` becomes available as the `/api/foo/examples/example-1` route of the micro frontend server.
+
+See [nerest-harness](https://github.com/nerestjs/harness) for the minimal example of a nerest micro frontend.
+
+## Development
+
+Run the build script to build the framework.
+
+```
+npm install
+npm run build
+```
+
+Use [nerest-harness](https://github.com/nerestjs/harness) with `npm link` to test changes locally.

package/bin/index.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+// All executions of `nerest <command>` get routed through here
+import { watch } from './watch';
+
+async function cliEntry(args: string[]) {
+  if (args[0] === 'watch') {
+    await watch();
+  }
+}
+
+// [<path to node>, <path to nerest binary>, ...args]
+const args = process.argv.slice(2);
+cliEntry(args);

package/bin/watch.ts

@@ -0,0 +1,18 @@
+import { createServer } from '../server';
+
+// Start dev server in watch mode, that restarts on file change
+// and rebuilds the client static files
+export async function watch() {
+  // TODO: will be replaced with nerest logger
+  console.log('Starting Nerest watch...');
+
+  const { app } = await createServer();
+
+  // TODO: remove hardcoded port
+  await app.listen({
+    host: '0.0.0.0',
+    port: 3000,
+  });
+
+  console.log('Nerest is listening on 0.0.0.0:3000');
+}

package/client/index.ts

@@ -0,0 +1,40 @@
+// Shared client entrypoint that bootstraps all of the apps supplied
+// by current microfrontend
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+
+// Since this is a shared entrypoint, it dynamically imports all of the
+// available apps. They will be built as separate chunks and only loaded
+// if needed.
+const modules = import.meta.glob('/apps/*/index.tsx', { import: 'default' });
+
+async function runHydration() {
+  for (const container of document.querySelectorAll('div[data-app-name]')) {
+    const appName = container.getAttribute('data-app-name');
+    const appModuleLoader = modules[`/apps/${appName}/index.tsx`];
+
+    if (!appModuleLoader || container.hasAttribute('data-app-hydrated')) {
+      continue;
+    }
+
+    // Mark container as hydrated, in case there are multiple instances
+    // of the same microfrontend script on the page
+    container.setAttribute('data-app-hydrated', 'true');
+
+    const appId = container.getAttribute('data-app-id');
+    const propsContainer = document.querySelector(
+      `script[data-app-id="${appId}"]`
+    );
+    // TODO: more robust error handling and error logging
+    const props = JSON.parse(propsContainer?.textContent ?? '{}');
+
+    const reactElement = React.createElement(await appModuleLoader(), props);
+    ReactDOM.hydrateRoot(container, reactElement);
+  }
+}
+
+if (document.readyState !== 'complete') {
+  document.addEventListener('DOMContentLoaded', runHydration);
+} else {
+  runHydration();
+}

package/dist/bin/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/index.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+// All executions of `nerest <command>` get routed through here
+const watch_1 = require("./watch");
+async function cliEntry(args) {
+    if (args[0] === 'watch') {
+        await (0, watch_1.watch)();
+    }
+}
+// [<path to node>, <path to nerest binary>, ...args]
+const args = process.argv.slice(2);
+cliEntry(args);

package/dist/bin/watch.d.ts

@@ -0,0 +1 @@
+export declare function watch(): Promise<void>;

package/dist/bin/watch.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.watch = void 0;
+const server_1 = require("../server");
+// Start dev server in watch mode, that restarts on file change
+// and rebuilds the client static files
+async function watch() {
+    // TODO: will be replaced with nerest logger
+    console.log('Starting Nerest watch...');
+    const { app } = await (0, server_1.createServer)();
+    // TODO: remove hardcoded port
+    await app.listen({
+        host: '0.0.0.0',
+        port: 3000,
+    });
+    console.log('Nerest is listening on 0.0.0.0:3000');
+}
+exports.watch = watch;

package/dist/client/entry.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/client/entry.js

@@ -0,0 +1,3 @@
+const apps = import.meta.glob('/apps/*/index.tsx', { import: 'default' });
+console.log(apps);
+export {};

package/dist/server/app-parts/assets.d.ts

@@ -0,0 +1,2 @@
+import type { Manifest } from 'vite';
+export declare function loadAppAssets(manifest: Manifest, appName: string): string[];

package/dist/server/app-parts/assets.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadAppAssets = void 0;
+// TODO: this is not as simple in the real world
+const publicPath = process.env.PUBLIC_PATH ?? 'http://0.0.0.0:3000/';
+// Extracts the list of assets for a given app from the manifest file
+function loadAppAssets(manifest, appName) {
+    const entries = Object.entries(manifest);
+    // TODO: handling errors and potentially missing entries
+    const clientEntryJs = entries.find(([_, entry]) => entry.isEntry)?.[1].file;
+    const appCss = entries.find(([name, _]) => name.includes(`/${appName}/index.tsx`))?.[1]
+        .css ?? [];
+    return [clientEntryJs, ...appCss].map((x) => publicPath + x);
+}
+exports.loadAppAssets = loadAppAssets;

package/dist/server/app-parts/examples.d.ts

@@ -0,0 +1 @@
+export declare function loadAppExamples(appRoot: string): Promise<Record<string, unknown>>;

package/dist/server/app-parts/examples.js

@@ -0,0 +1,31 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadAppExamples = void 0;
+const path_1 = __importDefault(require("path"));
+const fs_1 = require("fs");
+const promises_1 = __importDefault(require("fs/promises"));
+// Loads and parses the example json files for providing
+// `/examples/` routes of the dev server
+async function loadAppExamples(appRoot) {
+    const examplesRoot = path_1.default.join(appRoot, 'examples');
+    // Examples are optional and may not exist
+    if (!(0, fs_1.existsSync)(examplesRoot)) {
+        return {};
+    }
+    const exampleFiles = (await promises_1.default.readdir(examplesRoot, { withFileTypes: true }))
+        .filter((d) => d.isFile() && d.name.endsWith('.json'))
+        .map((d) => d.name);
+    const examples = {};
+    // TODO: error handling and reporting
+    for (const filename of exampleFiles) {
+        const file = path_1.default.join(examplesRoot, filename);
+        const content = await promises_1.default.readFile(file, { encoding: 'utf8' });
+        const json = JSON.parse(content);
+        examples[path_1.default.basename(filename, '.json')] = json;
+    }
+    return examples;
+}
+exports.loadAppExamples = loadAppExamples;

package/dist/server/app-parts/preview.d.ts

@@ -0,0 +1 @@
+export declare function renderPreviewPage(html: string, assets: string[]): string;

package/dist/server/app-parts/preview.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderPreviewPage = void 0;
+function renderPreviewPage(html, assets) {
+    const { scripts, styles } = mapAssets(assets);
+    return `
+  <html>
+  <head>
+    ${styles.join('\n')}
+  </head>
+  <body>
+    ${html}
+    ${scripts.join('\n')}
+  </body>
+  </html>
+  `;
+}
+exports.renderPreviewPage = renderPreviewPage;
+function mapAssets(assets) {
+    const scripts = assets
+        .filter((src) => src.endsWith('.js'))
+        .map((src) => `<script type="module" src="${src}"></script>`);
+    const styles = assets
+        .filter((src) => src.endsWith('.css'))
+        .map((src) => `<link rel="stylesheet" href="${src}">`);
+    return { scripts, styles };
+}

package/dist/server/apps.d.ts

@@ -0,0 +1,10 @@
+export declare type AppEntry = {
+    name: string;
+    root: string;
+    entry: string;
+    assets: string[];
+    examples: Record<string, unknown>;
+};
+export declare function loadApps(root: string): Promise<{
+    [k: string]: AppEntry;
+}>;

package/dist/server/apps.js

@@ -0,0 +1,48 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadApps = void 0;
+const path_1 = __importDefault(require("path"));
+const promises_1 = __importDefault(require("fs/promises"));
+const assets_1 = require("./app-parts/assets");
+const examples_1 = require("./app-parts/examples");
+// Build the record of the available apps by convention
+// apps -> /apps/{name}/index.tsx
+// examples -> /apps/{name}/examples/{example}.json
+async function loadApps(root) {
+    const appsRoot = path_1.default.join(root, 'apps');
+    const manifest = await loadManifest(root);
+    const appsDirs = (await promises_1.default.readdir(appsRoot, { withFileTypes: true }))
+        .filter((d) => d.isDirectory())
+        .map((d) => d.name);
+    const apps = [];
+    for (const appDir of appsDirs) {
+        apps.push(await loadApp(appsRoot, appDir, manifest));
+    }
+    return Object.fromEntries(apps);
+}
+exports.loadApps = loadApps;
+async function loadApp(appsRoot, name, manifest) {
+    // TODO: report problems with loading entries, assets and/or examples
+    const appRoot = path_1.default.join(appsRoot, name);
+    return [
+        name,
+        {
+            name,
+            root: appRoot,
+            entry: path_1.default.join(appRoot, 'index.tsx'),
+            assets: (0, assets_1.loadAppAssets)(manifest, name),
+            examples: await (0, examples_1.loadAppExamples)(appRoot),
+        },
+    ];
+}
+// Manifest is used to provide assets list for every app
+// for use with SSR
+async function loadManifest(root) {
+    // TODO: error handling
+    const manifestPath = path_1.default.join(root, 'dist', 'manifest.json');
+    const manifestData = await promises_1.default.readFile(manifestPath, { encoding: 'utf8' });
+    return JSON.parse(manifestData);
+}

package/dist/server/assets.d.ts

@@ -0,0 +1 @@
+export declare function getAppAssets(appName: string, root: string): Promise<string[]>;

package/dist/server/assets.js

@@ -0,0 +1,28 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getAppAssets = void 0;
+const path_1 = __importDefault(require("path"));
+const promises_1 = __importDefault(require("fs/promises"));
+// TODO: way more complicated in the real world
+const publicPath = process.env.PUBLIC_PATH ?? 'http://127.0.0.1:3000/';
+async function getAppAssets(appName, root) {
+    const manifest = await loadManifest(root);
+    const assets = extractAssetsFromManifest(manifest, appName);
+    return assets.map((x) => publicPath + x);
+}
+exports.getAppAssets = getAppAssets;
+async function loadManifest(root) {
+    const manifestPath = path_1.default.join(root, 'dist', 'manifest.json');
+    const manifestData = await promises_1.default.readFile(manifestPath, { encoding: 'utf8' });
+    return JSON.parse(manifestData);
+}
+function extractAssetsFromManifest(manifest, appName) {
+    const entries = Object.entries(manifest);
+    const clientEntryJs = entries.find(([_, entry]) => entry.isEntry)?.[1].file;
+    const appCss = entries.find(([name, _]) => name.includes(`/${appName}/index.tsx`))?.[1]
+        .css ?? [];
+    return [clientEntryJs, ...appCss];
+}

package/dist/server/entry.d.ts

@@ -0,0 +1,2 @@
+import React from 'react';
+export declare function renderSsrComponent(appName: string, AppComponent: React.ComponentType, props?: Record<string, unknown>): string;

package/dist/server/entry.js

@@ -0,0 +1,17 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderSsrComponent = void 0;
+const react_1 = __importDefault(require("react"));
+const server_1 = require("react-dom/server");
+const nanoid_1 = require("nanoid");
+function renderSsrComponent(appName, AppComponent, props = {}) {
+    const html = (0, server_1.renderToString)(react_1.default.createElement(AppComponent, { ...props }));
+    const appId = (0, nanoid_1.nanoid)();
+    const container = `<div data-app-name="${appName}" data-app-id="${appId}">${html}</div>`;
+    const script = `<script type="application/json" data-app-id="${appId}">${JSON.stringify(props)}</script>`;
+    return container + script;
+}
+exports.renderSsrComponent = renderSsrComponent;

package/dist/server/index.d.ts

@@ -0,0 +1,5 @@
+/// <reference types="node" />
+import type { ServerResponse } from 'http';
+export declare function createServer(): Promise<{
+    app: import("fastify").FastifyInstance<import("http").Server<typeof import("http").IncomingMessage, typeof ServerResponse>, import("http").IncomingMessage, ServerResponse<import("http").IncomingMessage>, import("fastify").FastifyBaseLogger, import("fastify").FastifyTypeProviderDefault> & PromiseLike<import("fastify").FastifyInstance<import("http").Server<typeof import("http").IncomingMessage, typeof ServerResponse>, import("http").IncomingMessage, ServerResponse<import("http").IncomingMessage>, import("fastify").FastifyBaseLogger, import("fastify").FastifyTypeProviderDefault>>;
+}>;

package/dist/server/index.js

@@ -0,0 +1,102 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createServer = void 0;
+// This is the nerest server entrypoint
+const path_1 = __importDefault(require("path"));
+const vite_1 = __importDefault(require("vite"));
+const fastify_1 = __importDefault(require("fastify"));
+const static_1 = __importDefault(require("@fastify/static"));
+const apps_1 = require("./apps");
+const render_1 = require("./render");
+const preview_1 = require("./preview");
+// TODO: this turned out to be a dev server, production server
+// will most likely be implemented separately
+async function createServer() {
+    const root = process.cwd();
+    // TODO: move build config into a separate file
+    // TODO: look at @vitejs/plugin-react (everything seems fine without it though)
+    // TODO: look at @vitejs/plugin-legacy (needed for browsers without module support)
+    const config = {
+        root,
+        appType: 'custom',
+        server: { middlewareMode: true },
+        build: {
+            // Manifest is needed to report used assets in SSR handles
+            manifest: true,
+            modulePreload: false,
+            // TODO: watch is only necessary for the client build
+            watch: {},
+            rollupOptions: {
+                input: '/node_modules/@nerest/nerest/client/index.ts',
+                output: {
+                    entryFileNames: `assets/[name].js`,
+                    chunkFileNames: `assets/[name].js`,
+                    assetFileNames: `assets/[name].[ext]`,
+                },
+            },
+        },
+    };
+    // Build the clientside assets and watch for changes
+    // TODO: this should probably be moved from here
+    await startClientBuildWatcher(config);
+    // Load app entries following the `apps/{name}/index.tsx` convention
+    const apps = await (0, apps_1.loadApps)(root);
+    // Start vite server that will be rendering SSR components
+    const viteSsr = await vite_1.default.createServer(config);
+    const app = (0, fastify_1.default)();
+    for (const appEntry of Object.values(apps)) {
+        const { name, entry, examples } = appEntry;
+        // POST /api/{name} -> render app with request.body as props
+        app.post(`/api/${name}`, async (request) => {
+            // ssrLoadModule drives the "hot-reload" logic, and allows
+            // picking up changes to the source without restarting the server
+            const ssrComponent = await viteSsr.ssrLoadModule(entry, {
+                fixStacktrace: true,
+            });
+            return (0, render_1.renderApp)(appEntry, ssrComponent.default, request.body);
+        });
+        for (const [exampleName, example] of Object.entries(examples)) {
+            // GET /api/{name}/examples/{example} -> render a preview page
+            // with a predefined example body
+            app.get(`/api/${name}/examples/${exampleName}`, async (_, reply) => {
+                const ssrComponent = await viteSsr.ssrLoadModule(entry, {
+                    fixStacktrace: true,
+                });
+                const { html, assets } = (0, render_1.renderApp)(appEntry, ssrComponent.default, example);
+                reply.type('text/html');
+                return (0, preview_1.renderPreviewPage)(html, assets);
+            });
+        }
+    }
+    // TODO: only do this locally, load from CDN in production
+    app.register(static_1.default, {
+        root: path_1.default.join(root, 'dist'),
+        // TODO: maybe use @fastify/cors instead
+        setHeaders(res) {
+            res.setHeader('Access-Control-Allow-Origin', '*');
+            res.setHeader('Access-Control-Allow-Methods', 'GET');
+            res.setHeader('Access-Control-Allow-Headers', 'X-Requested-With, content-type, Authorization');
+        },
+    });
+    return { app };
+}
+exports.createServer = createServer;
+// TODO: this should probably be moved from here
+async function startClientBuildWatcher(config) {
+    const watcher = (await vite_1.default.build(config));
+    return new Promise((resolve) => {
+        // We need to have a built manifest.json to provide assets
+        // links in SSR. We will wait for rollup to report when it
+        // has finished the build
+        const listener = (ev) => {
+            if (ev.code === 'END') {
+                watcher.off('event', listener);
+                resolve();
+            }
+        };
+        watcher.on('event', listener);
+    });
+}

package/dist/server/preview.d.ts

@@ -0,0 +1 @@
+export declare function renderPreviewPage(html: string, assets: string[]): string;

package/dist/server/preview.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderPreviewPage = void 0;
+// Renders the preview page available by convention at /api/{name}/examples/{example}
+function renderPreviewPage(html, assets) {
+    const { scripts, styles } = mapAssets(assets);
+    return `
+  <html>
+  <head>
+    ${styles.join('\n')}
+  </head>
+  <body>
+    ${html}
+    ${scripts.join('\n')}
+  </body>
+  </html>
+  `;
+}
+exports.renderPreviewPage = renderPreviewPage;
+function mapAssets(assets) {
+    // TODO: script type="module" is not supported by older browsers
+    // but vite doesn't provide `nomodule` fallback by default
+    // see @vitejs/plugin-legacy
+    const scripts = assets
+        .filter((src) => src.endsWith('.js'))
+        .map((src) => `<script type="module" src="${src}"></script>`);
+    const styles = assets
+        .filter((src) => src.endsWith('.css'))
+        .map((src) => `<link rel="stylesheet" href="${src}">`);
+    return { scripts, styles };
+}

package/dist/server/render.d.ts

@@ -0,0 +1,6 @@
+import React from 'react';
+import type { AppEntry } from './apps';
+export declare function renderApp(appEntry: AppEntry, appComponent: React.ComponentType, props?: Record<string, unknown>): {
+    html: string;
+    assets: string[];
+};

package/dist/server/render.js

@@ -0,0 +1,26 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderApp = void 0;
+const react_1 = __importDefault(require("react"));
+const server_1 = require("react-dom/server");
+const nanoid_1 = require("nanoid");
+function renderApp(appEntry, appComponent, props = {}) {
+    const { name, assets } = appEntry;
+    const html = renderSsrComponent(name, appComponent, props);
+    return { html, assets };
+}
+exports.renderApp = renderApp;
+function renderSsrComponent(appName, appComponent, props) {
+    const html = (0, server_1.renderToString)(react_1.default.createElement(appComponent, props));
+    // There may be multiple instances of the same app on the page,
+    // so we will use a randomized id to avoid collisions
+    const appId = (0, nanoid_1.nanoid)();
+    // data-app-name and data-app-id are used by client entrypoint to hydrate
+    // apps using correct serialized props
+    const container = `<div data-app-name="${appName}" data-app-id="${appId}">${html}</div>`;
+    const script = `<script type="application/json" data-app-id="${appId}">${JSON.stringify(props)}</script>`;
+    return container + script;
+}

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@nerest/nerest",
+  "version": "0.0.1",
+  "description": "React micro frontend framework",
+  "homepage": "https://github.com/nerestjs/nerest#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nerestjs/nerest.git"
+  },
+  "bin": {
+    "nerest": "dist/bin/index.js"
+  },
+  "files": [
+    "/dist",
+    "/bin",
+    "/client",
+    "/server",
+    "/README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json -d",
+    "lint": "eslint --ext .ts server bin",
+    "prepare": "simple-git-hooks"
+  },
+  "simple-git-hooks": {
+    "pre-commit": "npx lint-staged"
+  },
+  "lint-staged": {
+    "*.ts": [
+      "eslint --fix",
+      "prettier --write"
+    ],
+    "*.{json,md}": [
+      "prettier --write"
+    ],
+    "package.json": [
+      "sort-package-json"
+    ]
+  },
+  "prettier": "@tinkoff/prettier-config",
+  "eslintConfig": {
+    "extends": [
+      "@tinkoff/eslint-config/lib",
+      "@tinkoff/eslint-config/jest",
+      "@tinkoff/eslint-config-react"
+    ]
+  },
+  "dependencies": {
+    "@fastify/static": "^6.5.0",
+    "fastify": "^4.9.2",
+    "nanoid": "^3.3.4",
+    "vite": "^3.2.3"
+  },
+  "devDependencies": {
+    "@tinkoff/eslint-config": "^1.41.0",
+    "@tinkoff/eslint-config-react": "^1.41.0",
+    "@tinkoff/prettier-config": "^1.32.1",
+    "@types/react": "^18.0.25",
+    "@types/react-dom": "^18.0.8",
+    "jest": "^29.3.1",
+    "lint-staged": "^13.0.3",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "simple-git-hooks": "^2.8.1",
+    "sort-package-json": "^2.1.0",
+    "typescript": "^4.8.4"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  }
+}

package/server/app-parts/assets.ts

@@ -0,0 +1,17 @@
+import type { Manifest } from 'vite';
+
+// TODO: this is not as simple in the real world
+const publicPath = process.env.PUBLIC_PATH ?? 'http://0.0.0.0:3000/';
+
+// Extracts the list of assets for a given app from the manifest file
+export function loadAppAssets(manifest: Manifest, appName: string) {
+  const entries = Object.entries(manifest);
+
+  // TODO: handling errors and potentially missing entries
+  const clientEntryJs = entries.find(([_, entry]) => entry.isEntry)?.[1].file;
+  const appCss =
+    entries.find(([name, _]) => name.includes(`/${appName}/index.tsx`))?.[1]
+      .css ?? [];
+
+  return [clientEntryJs, ...appCss].map((x) => publicPath + x);
+}

package/server/app-parts/examples.ts

@@ -0,0 +1,30 @@
+import path from 'path';
+import { existsSync } from 'fs';
+import fs from 'fs/promises';
+
+// Loads and parses the example json files for providing
+// `/examples/` routes of the dev server
+export async function loadAppExamples(appRoot: string) {
+  const examplesRoot = path.join(appRoot, 'examples');
+
+  // Examples are optional and may not exist
+  if (!existsSync(examplesRoot)) {
+    return {};
+  }
+
+  const exampleFiles = (await fs.readdir(examplesRoot, { withFileTypes: true }))
+    .filter((d) => d.isFile() && d.name.endsWith('.json'))
+    .map((d) => d.name);
+
+  const examples: Record<string, unknown> = {};
+
+  // TODO: error handling and reporting
+  for (const filename of exampleFiles) {
+    const file = path.join(examplesRoot, filename);
+    const content = await fs.readFile(file, { encoding: 'utf8' });
+    const json = JSON.parse(content);
+    examples[path.basename(filename, '.json')] = json;
+  }
+
+  return examples;
+}

package/server/apps.ts

@@ -0,0 +1,61 @@
+import path from 'path';
+import fs from 'fs/promises';
+import type { Manifest } from 'vite';
+
+import { loadAppAssets } from './app-parts/assets';
+import { loadAppExamples } from './app-parts/examples';
+
+export type AppEntry = {
+  name: string;
+  root: string;
+  entry: string;
+  assets: string[];
+  examples: Record<string, unknown>;
+};
+
+// Build the record of the available apps by convention
+// apps -> /apps/{name}/index.tsx
+// examples -> /apps/{name}/examples/{example}.json
+export async function loadApps(root: string) {
+  const appsRoot = path.join(root, 'apps');
+  const manifest = await loadManifest(root);
+
+  const appsDirs = (await fs.readdir(appsRoot, { withFileTypes: true }))
+    .filter((d) => d.isDirectory())
+    .map((d) => d.name);
+
+  const apps: Array<[name: string, entry: AppEntry]> = [];
+  for (const appDir of appsDirs) {
+    apps.push(await loadApp(appsRoot, appDir, manifest));
+  }
+
+  return Object.fromEntries(apps);
+}
+
+async function loadApp(
+  appsRoot: string,
+  name: string,
+  manifest: Manifest
+): Promise<[name: string, entry: AppEntry]> {
+  // TODO: report problems with loading entries, assets and/or examples
+  const appRoot = path.join(appsRoot, name);
+  return [
+    name,
+    {
+      name,
+      root: appRoot,
+      entry: path.join(appRoot, 'index.tsx'),
+      assets: loadAppAssets(manifest, name),
+      examples: await loadAppExamples(appRoot),
+    },
+  ];
+}
+
+// Manifest is used to provide assets list for every app
+// for use with SSR
+async function loadManifest(root: string) {
+  // TODO: error handling
+  const manifestPath = path.join(root, 'dist', 'manifest.json');
+  const manifestData = await fs.readFile(manifestPath, { encoding: 'utf8' });
+  return JSON.parse(manifestData);
+}

package/server/index.ts

@@ -0,0 +1,125 @@
+// This is the nerest server entrypoint
+import path from 'path';
+import type { ServerResponse } from 'http';
+
+import vite from 'vite';
+import type { InlineConfig } from 'vite';
+import type { RollupWatcher, RollupWatcherEvent } from 'rollup';
+
+import fastify from 'fastify';
+import fastifyStatic from '@fastify/static';
+
+import { loadApps } from './apps';
+import { renderApp } from './render';
+import { renderPreviewPage } from './preview';
+
+// TODO: this turned out to be a dev server, production server
+// will most likely be implemented separately
+export async function createServer() {
+  const root = process.cwd();
+
+  // TODO: move build config into a separate file
+  // TODO: look at @vitejs/plugin-react (everything seems fine without it though)
+  // TODO: look at @vitejs/plugin-legacy (needed for browsers without module support)
+  const config: InlineConfig = {
+    root,
+    appType: 'custom',
+    server: { middlewareMode: true },
+    build: {
+      // Manifest is needed to report used assets in SSR handles
+      manifest: true,
+      modulePreload: false,
+      // TODO: watch is only necessary for the client build
+      watch: {},
+      rollupOptions: {
+        input: '/node_modules/@nerest/nerest/client/index.ts',
+        output: {
+          entryFileNames: `assets/[name].js`,
+          chunkFileNames: `assets/[name].js`,
+          assetFileNames: `assets/[name].[ext]`,
+        },
+      },
+    },
+  };
+
+  // Build the clientside assets and watch for changes
+  // TODO: this should probably be moved from here
+  await startClientBuildWatcher(config);
+
+  // Load app entries following the `apps/{name}/index.tsx` convention
+  const apps = await loadApps(root);
+
+  // Start vite server that will be rendering SSR components
+  const viteSsr = await vite.createServer(config);
+  const app = fastify();
+
+  for (const appEntry of Object.values(apps)) {
+    const { name, entry, examples } = appEntry;
+
+    // POST /api/{name} -> render app with request.body as props
+    app.post(`/api/${name}`, async (request) => {
+      // ssrLoadModule drives the "hot-reload" logic, and allows
+      // picking up changes to the source without restarting the server
+      const ssrComponent = await viteSsr.ssrLoadModule(entry, {
+        fixStacktrace: true,
+      });
+      return renderApp(
+        appEntry,
+        ssrComponent.default,
+        request.body as Record<string, unknown>
+      );
+    });
+
+    for (const [exampleName, example] of Object.entries(examples)) {
+      // GET /api/{name}/examples/{example} -> render a preview page
+      // with a predefined example body
+      app.get(`/api/${name}/examples/${exampleName}`, async (_, reply) => {
+        const ssrComponent = await viteSsr.ssrLoadModule(entry, {
+          fixStacktrace: true,
+        });
+        const { html, assets } = renderApp(
+          appEntry,
+          ssrComponent.default,
+          example as Record<string, unknown>
+        );
+
+        reply.type('text/html');
+
+        return renderPreviewPage(html, assets);
+      });
+    }
+  }
+
+  // TODO: only do this locally, load from CDN in production
+  app.register(fastifyStatic, {
+    root: path.join(root, 'dist'),
+    // TODO: maybe use @fastify/cors instead
+    setHeaders(res: ServerResponse) {
+      res.setHeader('Access-Control-Allow-Origin', '*');
+      res.setHeader('Access-Control-Allow-Methods', 'GET');
+      res.setHeader(
+        'Access-Control-Allow-Headers',
+        'X-Requested-With, content-type, Authorization'
+      );
+    },
+  });
+
+  return { app };
+}
+
+// TODO: this should probably be moved from here
+async function startClientBuildWatcher(config: InlineConfig) {
+  const watcher = (await vite.build(config)) as RollupWatcher;
+  return new Promise<void>((resolve) => {
+    // We need to have a built manifest.json to provide assets
+    // links in SSR. We will wait for rollup to report when it
+    // has finished the build
+    const listener = (ev: RollupWatcherEvent) => {
+      if (ev.code === 'END') {
+        watcher.off('event', listener);
+        resolve();
+      }
+    };
+    watcher.on('event', listener);
+  });
+}

package/server/preview.ts

@@ -0,0 +1,30 @@
+// Renders the preview page available by convention at /api/{name}/examples/{example}
+export function renderPreviewPage(html: string, assets: string[]) {
+  const { scripts, styles } = mapAssets(assets);
+  return `
+  <html>
+  <head>
+    ${styles.join('\n')}
+  </head>
+  <body>
+    ${html}
+    ${scripts.join('\n')}
+  </body>
+  </html>
+  `;
+}
+
+function mapAssets(assets: string[]) {
+  // TODO: script type="module" is not supported by older browsers
+  // but vite doesn't provide `nomodule` fallback by default
+  // see @vitejs/plugin-legacy
+  const scripts = assets
+    .filter((src) => src.endsWith('.js'))
+    .map((src) => `<script type="module" src="${src}"></script>`);
+
+  const styles = assets
+    .filter((src) => src.endsWith('.css'))
+    .map((src) => `<link rel="stylesheet" href="${src}">`);
+
+  return { scripts, styles };
+}

package/server/render.ts

@@ -0,0 +1,36 @@
+import React from 'react';
+import { renderToString } from 'react-dom/server';
+import { nanoid } from 'nanoid';
+
+import type { AppEntry } from './apps';
+
+export function renderApp(
+  appEntry: AppEntry,
+  appComponent: React.ComponentType,
+  props: Record<string, unknown> = {}
+) {
+  const { name, assets } = appEntry;
+  const html = renderSsrComponent(name, appComponent, props);
+  return { html, assets };
+}
+
+function renderSsrComponent(
+  appName: string,
+  appComponent: React.ComponentType,
+  props: Record<string, unknown>
+) {
+  const html = renderToString(React.createElement(appComponent, props));
+
+  // There may be multiple instances of the same app on the page,
+  // so we will use a randomized id to avoid collisions
+  const appId = nanoid();
+
+  // data-app-name and data-app-id are used by client entrypoint to hydrate
+  // apps using correct serialized props
+  const container = `<div data-app-name="${appName}" data-app-id="${appId}">${html}</div>`;
+  const script = `<script type="application/json" data-app-id="${appId}">${JSON.stringify(
+    props
+  )}</script>`;
+
+  return container + script;
+}