@nerest/nerest 0.0.9 → 1.5.0

package/dist/server/parts/render.d.ts

@@ -1,10 +1,12 @@
-import React from 'react';
+import type { ComponentType } from 'react';
+import type { Project } from '../loaders/project.js';
 type RenderProps = {
     name: string;
     assets: string[];
-    component: React.ComponentType;
+    component: ComponentType;
+    project: Project;
 };
-export declare function renderApp({ name, assets, component }: RenderProps, props?: Record<string, unknown>): {
+export declare function renderApp({ name, assets, component, project }: RenderProps, props?: Record<string, unknown>): {
     html: string;
     assets: string[];
 };

package/dist/server/parts/render.js

@@ -1,18 +1,18 @@
-import React from 'react';
+import { createElement } from 'react';
 import { renderToString } from 'react-dom/server';
-import { nanoid } from 'nanoid';
-export function renderApp({ name, assets, component }, props = {}) {
-    const html = renderSsrComponent(name, component, props);
+import { randomId } from '../utils.js';
+export function renderApp({ name, assets, component, project }, props = {}) {
+    const html = renderSsrComponent(name, component, project, props);
     return { html, assets };
 }
-function renderSsrComponent(appName, appComponent, props) {
-    const html = renderToString(React.createElement(appComponent, props));
+function renderSsrComponent(appName, appComponent, project, props) {
+    const html = renderToString(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();
+    const appId = randomId();
     // 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 container = `<div data-project-name="${project.name}" 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/dist/server/parts/swagger.d.ts

@@ -1,2 +1,3 @@
 import type { FastifyInstance } from 'fastify';
-export declare function setupSwagger(app: FastifyInstance): Promise<void>;
+import type { Project } from '../loaders/project.js';
+export declare function setupSwagger(app: FastifyInstance, project: Project): Promise<void>;

package/dist/server/parts/swagger.js

@@ -1,29 +1,18 @@
-import path from 'path';
-import fs from 'fs';
 import fastifySwagger from '@fastify/swagger';
 import fastifySwaggerUi from '@fastify/swagger-ui';
 // Setup automatic OpenAPI specification compilation and enable
 // Swagger UI at the `/api` route
-export async function setupSwagger(app) {
-    let appInfo = {};
-    try {
-        const packageJson = fs.readFileSync(path.join(process.cwd(), 'package.json'), { encoding: 'utf-8' });
-        appInfo = JSON.parse(packageJson);
-    }
-    catch (e) {
-        // We only use package.json info to setup Swagger info and links,
-        // if we are unable to load them -- that's fine
-    }
-    const homepage = appInfo.homepage ||
-        (typeof appInfo.repository === 'string'
-            ? appInfo.repository
-            : appInfo.repository?.url);
+export async function setupSwagger(app, project) {
+    const homepage = project.homepage ||
+        (typeof project.repository === 'string'
+            ? project.repository
+            : project.repository?.url);
     await app.register(fastifySwagger, {
         openapi: {
             info: {
-                title: appInfo.name ?? 'Nerest micro frontend',
-                description: appInfo.description,
-                version: appInfo.version ?? '',
+                title: project.name || 'Nerest micro frontend',
+                description: project.description,
+                version: project.version ?? '',
                 contact: homepage
                     ? {
                         name: 'Homepage',

package/dist/server/parts/validator.d.ts

@@ -1,2 +1,4 @@
 import Ajv from 'ajv';
-export declare const validator: Ajv.default;
+import type { FastifyInstance } from 'fastify';
+export declare const validator: Ajv.Ajv;
+export declare function setupValidator(app: FastifyInstance): void;

package/dist/server/parts/validator.js

@@ -18,3 +18,16 @@ export const validator = new Ajv.default({
 // `email`, `url`, etc. Used by default in fastify
 // https://www.npmjs.com/package/ajv-formats
 addFormats.default(validator);
+// Setup schema validation. We have to use our own ajv instance that
+// we can use both to validate request bodies and examples against
+// app schemas
+export function setupValidator(app) {
+    if (process.env.DISABLE_SCHEMA_VALIDATION) {
+        // If schema validation is disabled, return data as is without any checks
+        app.setValidatorCompiler(() => (data) => ({ value: data }));
+    }
+    else {
+        // If schema validation is enabled, validate and coerce data via ajv
+        app.setValidatorCompiler(({ schema }) => validator.compile(schema));
+    }
+}

package/dist/server/production.js

@@ -1,22 +1,11 @@
-// This is the nerest production server entrypoint
-import path from 'path';
-import fs from 'fs/promises';
-import fastify from 'fastify';
-import fastifyGracefulShutdown from 'fastify-graceful-shutdown';
-import { renderApp } from './parts/render.js';
-import { setupSwagger } from './parts/swagger.js';
-import { validator } from './parts/validator.js';
-import { renderPreviewPage } from './parts/preview.js';
-import { setupK8SProbes } from './parts/k8s-probes.js';
-import { runRuntimeHook } from './hooks/runtime.js';
-import { runPropsHook } from './hooks/props.js';
-// TODO: refactor to merge the similar parts between production and development server?
-async function runProductionServer() {
+import { createServer } from './shared.js';
+import { loadNerestManifest } from './loaders/manifest.js';
+// Important: this file is the server entrypoint that will be built by vite
+// in `build/index.ts`. All of the import.meta.glob's will be resolved at build time
+async function runProductionServer(port) {
     const root = process.cwd();
-    // TODO: error handling for file reading
-    const apps = JSON.parse(await fs.readFile(path.join(root, 'build/nerest-manifest.json'), {
-        encoding: 'utf-8',
-    }));
+    // Load project information from the manifest generated during production build
+    const { project, apps } = await loadNerestManifest(root);
     const components = import.meta.glob('/apps/*/index.tsx', {
         import: 'default',
         eager: true,
@@ -24,70 +13,18 @@ async function runProductionServer() {
     const propsHooks = import.meta.glob('/apps/*/props.ts', {
         eager: true,
     });
-    const app = fastify();
-    // Setup schema validation. We have to use our own ajv instance that
-    // we can use both to validate request bodies and examples against
-    // app schemas
-    app.setValidatorCompiler(({ schema }) => validator.compile(schema));
-    await setupSwagger(app);
-    for (const appEntry of Object.values(apps)) {
-        const { name, examples, schema, assets } = appEntry;
-        const component = components[`/apps/${name}/index.tsx`];
-        const propsHook = async () => propsHooks[`/apps/${name}/props.ts`];
-        const routeOptions = {};
-        // TODO: report error if schema is missing, unless this app is client-only
-        // TODO: disallow apps without schemas in production build
-        if (schema) {
-            routeOptions.schema = {
-                // Use description as Swagger summary, since summary is visible
-                // even when the route is collapsed in the UI
-                summary: schema.description,
-                // TODO: do we need to mix in examples like in the development server?
-                body: schema,
-            };
-        }
-        // POST /api/{name} -> render app with request.body as props
-        app.post(`/api/${name}`, routeOptions, async (request) => {
-            const props = await runPropsHook(request.body, propsHook);
-            return renderApp({ name, assets, component }, props);
-        });
-        for (const [exampleName, example] of Object.entries(examples)) {
-            // GET /api/{name}/examples/{example} -> render a preview page
-            // with a predefined example body
-            const exampleRoute = `/api/${name}/examples/${exampleName}`;
-            app.get(exampleRoute, {
-                schema: {
-                    // Add a clickable link to the example route in route's Swagger
-                    // description so it's easier to navigate to
-                    description: `Open sandbox: [${exampleRoute}](${exampleRoute})`,
-                },
-            }, async (_, reply) => {
-                const props = await runPropsHook(example, propsHook);
-                const { html, assets: outAssets } = renderApp({
-                    name,
-                    assets,
-                    component,
-                }, props);
-                reply.type('text/html');
-                return renderPreviewPage(html, outAssets);
-            });
-        }
-    }
-    // Add graceful shutdown handler to prevent requests errors
-    await app.register(fastifyGracefulShutdown);
-    if (process.env.ENABLE_K8S_PROBES) {
-        await setupK8SProbes(app);
-    }
-    // Execute runtime hook in nerest-runtime.ts if it exists
-    await runRuntimeHook(app, async () => {
-        const glob = import.meta.glob('/nerest-runtime.ts', { eager: true });
-        return glob['/nerest-runtime.ts'];
+    const runtimeHook = import.meta.glob('/nerest/runtime.ts', { eager: true });
+    const app = await createServer({
+        root,
+        project,
+        apps,
+        loadComponent: async (entry) => components[`/apps/${entry}/index.tsx`],
+        loadPropsHook: async (entry) => propsHooks[`/apps/${entry}/props.ts`],
+        loadRuntimeHook: async () => runtimeHook['/nerest/runtime.ts'],
     });
-    // TODO: remove hardcoded port
     await app.listen({
         host: '0.0.0.0',
-        port: 3000,
+        port,
     });
-    console.log('Nerest is listening on 0.0.0.0:3000');
 }
-runProductionServer();
+runProductionServer(process.env.PORT ? Number(process.env.PORT) : 3000);

package/dist/server/shared.d.ts

@@ -0,0 +1,14 @@
+import fastify from 'fastify';
+import type { ComponentType } from 'react';
+import type { Project } from './loaders/project.js';
+import type { AppEntry } from './loaders/apps.js';
+type ServerOptions = {
+    root: string;
+    project: Project;
+    apps: Record<string, AppEntry>;
+    loadComponent: (entry: string) => Promise<ComponentType>;
+    loadPropsHook: (entry: string) => Promise<unknown>;
+    loadRuntimeHook: () => Promise<unknown>;
+};
+export declare function createServer(options: ServerOptions): Promise<fastify.FastifyInstance<fastify.RawServerDefault, import("http").IncomingMessage, import("http").ServerResponse<import("http").IncomingMessage>, fastify.FastifyBaseLogger, fastify.FastifyTypeProviderDefault>>;
+export {};

package/dist/server/shared.js

@@ -0,0 +1,94 @@
+import fastify from 'fastify';
+import fastifyGracefulShutdown from 'fastify-graceful-shutdown';
+import { renderApp } from './parts/render.js';
+import { setupSwagger } from './parts/swagger.js';
+import { setupValidator, validator } from './parts/validator.js';
+import { renderPreviewPage } from './parts/preview.js';
+import { setupK8SProbes } from './parts/k8s-probes.js';
+import { runRuntimeHook } from './hooks/runtime.js';
+import { runPropsHook } from './hooks/props.js';
+import { runLoggerHook } from './hooks/logger.js';
+import { loadPreviewParts } from './loaders/preview.js';
+import { randomId } from './utils.js';
+export async function createServer(options) {
+    const { project, root, loadRuntimeHook } = options;
+    const app = fastify({
+        logger: (await runLoggerHook(loadRuntimeHook)) ?? true,
+        ignoreTrailingSlash: true,
+        useSemicolonDelimiter: false,
+        // JSON parsing can take a long time and blocks the event loop,
+        // so we need to limit the size of the body. 10MB is a good compromise
+        // baseline that was chosen by experimenting with real world usage
+        bodyLimit: 10 * 1024 * 1024,
+        genReqId(req) {
+            return String(req.headers['x-request-id'] || randomId());
+        },
+    });
+    // Setup payload validation and Swagger based on apps' JSON Schema
+    setupValidator(app);
+    await setupSwagger(app, project);
+    // Load preview parts from `nerest/preview-{part}.html` files
+    const previewParts = await loadPreviewParts(root);
+    await setupRoutes(app, { ...options, previewParts });
+    // Add graceful shutdown handler to prevent requests errors
+    await app.register(fastifyGracefulShutdown);
+    if (process.env.ENABLE_K8S_PROBES) {
+        await setupK8SProbes(app);
+    }
+    // Execute runtime hook in nerest/runtime.ts if it exists
+    await runRuntimeHook(app, loadRuntimeHook);
+    return app;
+}
+async function setupRoutes(app, options) {
+    const { project, apps, previewParts, loadComponent, loadPropsHook } = options;
+    for (const appEntry of Object.values(apps)) {
+        const { name, examples, schema, assets } = appEntry;
+        const routeOptions = {};
+        // TODO: report error if schema is missing, making it mandatory
+        if (schema) {
+            routeOptions.schema = {
+                summary: schema.description,
+                // Tags are used to group routes in Swagger UI
+                tags: [name],
+                body: {
+                    ...schema,
+                    // Examples are also displayed in Swagger UI
+                    examples: Object.values(examples),
+                },
+            };
+        }
+        // POST /api/{name} -> render app with request.body as props
+        app.post(`/api/${name}`, routeOptions, async (request) => {
+            const component = await loadComponent(name);
+            const props = await runPropsHook(app, () => loadPropsHook(name), request.body);
+            return renderApp({ name, assets, component, project }, props);
+        });
+        for (const [exampleName, example] of Object.entries(examples)) {
+            // Validate examples against schema
+            if (schema && !validator.validate(schema, example)) {
+                app.log.error(`Example "${exampleName}" of app "${name}" does not satisfy schema: ${validator.errorsText()}`);
+            }
+            // GET /api/{name}/examples/{example} -> render a preview page
+            const exampleRoute = `/api/${name}/examples/${exampleName}`;
+            app.get(exampleRoute, {
+                schema: {
+                    // Add clickable link to go to the example in Swagger UI
+                    description: `Open sandbox: [${exampleRoute}](${exampleRoute})`,
+                    // Place examples under the same tag as the app
+                    tags: [name],
+                },
+            }, async (request, reply) => {
+                const component = await loadComponent(name);
+                const props = await runPropsHook(app, () => loadPropsHook(name), example);
+                const { html, assets: outAssets } = renderApp({
+                    name,
+                    assets,
+                    component,
+                    project,
+                }, props);
+                reply.type('text/html');
+                return renderPreviewPage(html, outAssets, previewParts);
+            });
+        }
+    }
+}

package/dist/server/utils.d.ts

@@ -0,0 +1 @@
+export declare function randomId(): string;

package/dist/server/utils.js

@@ -0,0 +1,5 @@
+import crypto from 'crypto';
+// Generate a random string ID 20 characters long
+export function randomId() {
+    return crypto.randomBytes(10).toString('hex');
+}

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@nerest/nerest",
-  "version": "0.0.9",
+  "version": "1.5.0",
   "description": "React micro frontend framework",
-  "homepage": "https://github.com/nerestjs/nerest#readme",
+  "homepage": "https://github.com/nerestjs/nerest",
   "repository": {
     "type": "git",
     "url": "https://github.com/nerestjs/nerest.git"
   },
+  "license": "Apache-2.0",
   "type": "module",
   "bin": {
     "nerest": "dist/bin/index.js"
@@ -18,16 +19,23 @@
     "/client",
     "/schemas",
     "/server",
-    "/README.md"
+    "/README.md",
+    "/LICENSE.md"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json -d",
-    "lint": "eslint --ext .ts server bin",
+    "docs": "scripts/docs.sh",
+    "lint": "eslint --ext .ts .",
     "prepare": "simple-git-hooks",
+    "test": "npm run test:module && npm run test:integration:dev && npm run test:integration:prod",
+    "test:integration:dev": "node tests/integration/run.development.js",
+    "test:integration:prod": "node tests/integration/run.production.js",
+    "test:module": "vitest run tests/module/**",
     "typegen": "json2ts -i 'schemas/**/*.json' -o schemas --bannerComment ''"
   },
   "simple-git-hooks": {
-    "pre-commit": "npx lint-staged"
+    "pre-commit": "npx lint-staged",
+    "commit-msg": "npx commitlint --edit ${1}"
   },
   "lint-staged": {
     "*.ts": [
@@ -41,51 +49,46 @@
       "sort-package-json"
     ]
   },
-  "prettier": "@tinkoff/prettier-config",
-  "eslintConfig": {
-    "parserOptions": {
-      "project": true
-    },
-    "extends": [
-      "@tinkoff/eslint-config/lib",
-      "@tinkoff/eslint-config/jest",
-      "@tinkoff/eslint-config-react"
-    ]
-  },
   "dependencies": {
-    "@fastify/static": "^6.12.0",
-    "@fastify/swagger": "^8.12.0",
-    "@fastify/swagger-ui": "^1.10.1",
-    "ajv": "^8.12.0",
-    "ajv-formats": "^2.1.1",
-    "dotenv": "^16.3.1",
-    "fast-uri": "^2.3.0",
-    "fastify": "^4.24.3",
-    "fastify-graceful-shutdown": "^3.5.1",
-    "nanoid": "^5.0.2",
-    "vite": "^4.5.0",
+    "@apidevtools/json-schema-ref-parser": "^11.9.3",
+    "@fastify/middie": "^9.0.3",
+    "@fastify/static": "^8.1.1",
+    "@fastify/swagger": "^9.4.2",
+    "@fastify/swagger-ui": "^5.2.2",
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
+    "dotenv": "^16.4.7",
+    "fast-glob": "^3.3.3",
+    "fast-uri": "^3.0.6",
+    "fastify": "^5.2.1",
+    "fastify-graceful-shutdown": "^4.0.1",
+    "json-schema-to-typescript": "^15.0.4",
+    "vite": "^6.2.2",
     "vite-plugin-externals": "^0.6.2"
   },
   "devDependencies": {
-    "@tinkoff/eslint-config": "^1.54.4",
-    "@tinkoff/eslint-config-react": "^1.54.4",
-    "@tinkoff/prettier-config": "^1.52.1",
-    "@types/react": "^18.2.34",
-    "@types/react-dom": "^18.2.14",
-    "jest": "^29.7.0",
-    "json-schema-to-typescript": "^13.1.1",
-    "lint-staged": "^15.0.2",
-    "react": "^18.2.0",
-    "react-dom": "^18.2.0",
-    "simple-git-hooks": "^2.9.0",
-    "sort-package-json": "^2.6.0",
-    "typescript": "^5.2.2"
+    "@commitlint/cli": "^19.8.0",
+    "@commitlint/config-conventional": "^19.8.0",
+    "@playwright/test": "^1.51.0",
+    "@tinkoff/eslint-config": "^5.0.1",
+    "@tinkoff/eslint-config-react": "^5.0.1",
+    "@tinkoff/prettier-config": "^5.0.0",
+    "@types/react": "^19.0.10",
+    "@types/react-dom": "^19.0.4",
+    "execa": "^9.5.2",
+    "lint-staged": "^15.5.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "simple-git-hooks": "^2.11.1",
+    "sort-package-json": "^3.0.0",
+    "typescript": "^5.8.2",
+    "vitest": "^3.0.8"
   },
   "peerDependencies": {
-    "react": "^18.0.0",
-    "react-dom": "^18.0.0"
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
   },
   "engines": {
-    "node": ">=16.0.0"
+    "node": ">=v20.17.0"
   }
 }

package/schemas/nerest-build.schema.d.ts

@@ -1,5 +1,5 @@
 /**
- * Build configuration placed as nerest-build.schema.json in the root of the application.
+ * Build configuration placed as nerest/build.json in the root of the application.
  */
 export interface BuildConfiguration {
   /**
@@ -12,5 +12,23 @@ export interface BuildConfiguration {
   externals?: {
     [k: string]: string;
   };
+  /**
+   * Additional PostCSS configuration. Nerest uses the standard vite PostCSS configuration by default.
+   */
+  postcss?: {
+    /**
+     * List packages and options of PostCSS plugins to use. They will be added to the default plugin list.
+     */
+    plugins?: {
+      [k: string]: {
+        [k: string]: unknown;
+      };
+    };
+    [k: string]: unknown;
+  };
+  /**
+   * List of names of apps that have client side-effects, for example have their own self-initialization code that runs on import. Their entries will be loaded when hydration starts to run side-effect code.
+   */
+  clientSideEffects?: string[];
   [k: string]: unknown;
 }

package/schemas/nerest-build.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft-07/schema",
   "title": "Build Configuration",
-  "description": "Build configuration placed as nerest-build.schema.json in the root of the application.",
+  "description": "Build configuration placed as nerest/build.json in the root of the application.",
   "type": "object",
   "properties": {
     "excludes": {
@@ -17,6 +17,26 @@
       "additionalProperties": {
         "type": "string"
       }
+    },
+    "postcss": {
+      "description": "Additional PostCSS configuration. Nerest uses the standard vite PostCSS configuration by default.",
+      "type": "object",
+      "properties": {
+        "plugins": {
+          "description": "List packages and options of PostCSS plugins to use. They will be added to the default plugin list.",
+          "type": "object",
+          "additionalProperties": {
+            "type": "object"
+          }
+        }
+      }
+    },
+    "clientSideEffects": {
+      "description": "List of names of apps that have client side-effects, for example have their own self-initialization code that runs on import. Their entries will be loaded when hydration starts to run side-effect code.",
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
     }
   }
 }