@nerest/nerest 0.0.4 → 0.0.6

package/README.md

@@ -6,6 +6,8 @@ React micro frontend framework
 
 ## Installation
 
+TODO: update package
+
 ```
 npm i --save @nerest/nerest react react-dom
 ```
@@ -23,7 +25,7 @@ npm i --save @nerest/nerest react react-dom
 
 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.
 
-See [nerest-harness](https://github.com/nerestjs/harness) for the minimal example of a nerest micro frontend.
+See [nerest-harness](https://gitlab.tcsbank.ru/tj/nerest-harness) for the minimal example of a nerest micro frontend.
 
 ### Examples (`/examples/*.json`)
 
@@ -37,7 +39,7 @@ OpenAPI specification is compiled automatically based on the provided schemas an
 
 ## Configuration
 
-Different aspects of Nerest apps can be configured via environment variables, JSON configuration and runtime hooks written in TypeScript. Examples of all kinds of configuration can be viewed in the [nerest-harness](https://github.com/nerestjs/harness) repository.
+Different aspects of Nerest apps can be configured via environment variables, JSON configuration and runtime hooks written in TypeScript. Examples of all kinds of configuration can be viewed in the [nerest-harness](https://gitlab.tcsbank.ru/tj/nerest-harness) repository.
 
 ### Environment Variables
 
@@ -47,11 +49,40 @@ Different aspects of Nerest apps can be configured via environment variables, JS
 
 #### Runtime
 
+##### Client
+
 All environment variables prefixed with `NEREST_` will be bundled with your app during buildtime. You can access them in the code using the special `import.meta.env` object. For example, `import.meta.env.NEREST_SOMEVAR` will be statically replaced during buildtime with the value of this environment variable on the build machine.
 
+##### Server
+
+Additional environment variables which can be setup for a runtime:
+
+- `ENABLE_K8S_PROBES`: activates additional routes `/livenessProbe` and `/readinessProbe` to check application status
+
 ### JSON Configuration
 
-TODO
+You can configure the output of `nerest build` by placing an optional `nerest-build.json` configuration file in the root of the micro frontend. The full schema of this file is located in [schemas/nerest-build.schema.json](schemas/nerest-build.schema.json).
+
+#### excludes: `string[]`
+
+Excludes modules from the client build and replaces their imports with imports of an empty module instead. You can use this to exclude either JS or CSS modules from the final build.
+
+```
+"excludes": ["@scope/name"]
+```
+
+#### externals: `Record<string, string>`
+
+Excludes modules from the client build and maps them to globally available constants instead. You can use this to share common dependencies between different micro frontends by exposing them on the `window` object. For example:
+
+```
+"externals": {
+  "react": "window.React",
+  "react-dom": "window['ReactDOM']"
+}
+```
+
+Here `react` and `react-dom` imports will be replaced with accessing the respective `window` constants.
 
 ### Runtime Hooks
 
@@ -66,4 +97,4 @@ npm install
 npm run build
 ```
 
-Use [nerest-harness](https://github.com/nerestjs/harness) to test changes locally.
+Use [nerest-harness](https://gitlab.tcsbank.ru/tj/nerest-harness) to test changes locally.

package/build/excludes/empty-module

@@ -0,0 +1 @@
+/* Empty module to replace excluded imports with. */

package/build/excludes/index.ts

@@ -0,0 +1,20 @@
+/**
+ * Maps list of imports into a list of rollup aliases that resolve
+ * into an empty module.
+ */
+export function excludes(list: string[] | undefined) {
+  return list?.map((exclude) => ({
+    // Excluding '@some/package' should exclude both '@some/package' and
+    // '@some/package/...` imports
+    find: new RegExp(`^${escapeRegExp(exclude)}($|\\/.*)`),
+    replacement: '@nerest/nerest/build/excludes/empty-module',
+  }));
+}
+
+/**
+ * Escapes string to use inside of a regular expression.
+ * https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions#escaping
+ */
+function escapeRegExp(str: string) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/build/index.ts

@@ -1,10 +1,14 @@
 import path from 'path';
 import fs from 'fs/promises';
+import { existsSync } from 'fs';
 
 import vite from 'vite';
 import type { InlineConfig } from 'vite';
+import { viteExternalsPlugin } from 'vite-plugin-externals';
 
 import { loadApps } from '../server/parts/apps';
+import type { BuildConfiguration } from '../schemas/nerest-build.schema';
+import { excludes } from './excludes';
 
 export async function buildMicroFrontend() {
   const root = process.cwd();
@@ -19,6 +23,8 @@ export async function buildMicroFrontend() {
     );
   }
 
+  const buildConfig = await readBuildConfig(root);
+
   // Build client
   // TODO: extract shared parts between build/index.ts and server/index.ts
   // into a shared config
@@ -40,6 +46,14 @@ export async function buildMicroFrontend() {
         },
       },
     },
+    resolve: {
+      // excludes - map buildConfig.excludes packages to an empty module
+      alias: excludes(buildConfig?.excludes),
+    },
+    plugins: [
+      // externals - map buildConfig.externals packages to a global variable on window
+      viteExternalsPlugin(buildConfig?.externals, { useWindow: false }),
+    ],
   };
 
   console.log('Producing production client build...');
@@ -80,3 +94,12 @@ async function buildAppsManifest(root: string, staticPath: string) {
     { encoding: 'utf-8' }
   );
 }
+
+// TODO: error handling
+async function readBuildConfig(root: string) {
+  const configPath = path.join(root, 'nerest-build.json');
+  if (existsSync(configPath)) {
+    const content = await fs.readFile(configPath, { encoding: 'utf-8' });
+    return JSON.parse(content) as BuildConfiguration;
+  }
+}

package/dist/build/excludes/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Maps list of imports into a list of rollup aliases that resolve
+ * into an empty module.
+ */
+export declare function excludes(list: string[] | undefined): {
+    find: RegExp;
+    replacement: string;
+}[] | undefined;

package/dist/build/excludes/index.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.excludes = void 0;
+/**
+ * Maps list of imports into a list of rollup aliases that resolve
+ * into an empty module.
+ */
+function excludes(list) {
+    return list?.map((exclude) => ({
+        // Excluding '@some/package' should exclude both '@some/package' and
+        // '@some/package/...` imports
+        find: new RegExp(`^${escapeRegExp(exclude)}($|\\/.*)`),
+        replacement: '@nerest/nerest/build/excludes/empty-module',
+    }));
+}
+exports.excludes = excludes;
+/**
+ * Escapes string to use inside of a regular expression.
+ * https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions#escaping
+ */
+function escapeRegExp(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/dist/build/index.js

@@ -6,8 +6,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildMicroFrontend = void 0;
 const path_1 = __importDefault(require("path"));
 const promises_1 = __importDefault(require("fs/promises"));
+const fs_1 = require("fs");
 const vite_1 = __importDefault(require("vite"));
+const vite_plugin_externals_1 = require("vite-plugin-externals");
 const apps_1 = require("../server/parts/apps");
+const excludes_1 = require("./excludes");
 async function buildMicroFrontend() {
     const root = process.cwd();
     const staticPath = process.env.NEREST_STATIC_PATH;
@@ -17,6 +20,7 @@ async function buildMicroFrontend() {
     if (!staticPath) {
         throw new Error('NEREST_STATIC_PATH environment variable is not set but is required for the production build');
     }
+    const buildConfig = await readBuildConfig(root);
     // Build client
     // TODO: extract shared parts between build/index.ts and server/index.ts
     // into a shared config
@@ -38,6 +42,14 @@ async function buildMicroFrontend() {
                 },
             },
         },
+        resolve: {
+            // excludes - map buildConfig.excludes packages to an empty module
+            alias: (0, excludes_1.excludes)(buildConfig?.excludes),
+        },
+        plugins: [
+            // externals - map buildConfig.externals packages to a global variable on window
+            (0, vite_plugin_externals_1.viteExternalsPlugin)(buildConfig?.externals, { useWindow: false }),
+        ],
     };
     console.log('Producing production client build...');
     await vite_1.default.build(clientConfig);
@@ -70,3 +82,11 @@ async function buildAppsManifest(root, staticPath) {
     const apps = await (0, apps_1.loadApps)(root, staticPath);
     await promises_1.default.writeFile(path_1.default.join(root, 'build/nerest-manifest.json'), JSON.stringify(apps), { encoding: 'utf-8' });
 }
+// TODO: error handling
+async function readBuildConfig(root) {
+    const configPath = path_1.default.join(root, 'nerest-build.json');
+    if ((0, fs_1.existsSync)(configPath)) {
+        const content = await promises_1.default.readFile(configPath, { encoding: 'utf-8' });
+        return JSON.parse(content);
+    }
+}

package/dist/server/development.js

@@ -9,11 +9,13 @@ 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 fastify_graceful_shutdown_1 = __importDefault(require("fastify-graceful-shutdown"));
 const apps_1 = require("./parts/apps");
 const render_1 = require("./parts/render");
 const preview_1 = require("./parts/preview");
 const validator_1 = require("./parts/validator");
 const swagger_1 = require("./parts/swagger");
+const k8s_probes_1 = require("./parts/k8s-probes");
 async function runDevelopmentServer() {
     const root = process.cwd();
     // TODO: move build config into a separate file
@@ -119,6 +121,11 @@ async function runDevelopmentServer() {
             });
         }
     }
+    // Add graceful shutdown handler to prevent requests errors
+    await app.register(fastify_graceful_shutdown_1.default);
+    if (process.env.ENABLE_K8S_PROBES) {
+        await (0, k8s_probes_1.setupK8SProbes)(app);
+    }
     // TODO: only do this locally, load from CDN in production
     await app.register(static_1.default, {
         root: path_1.default.join(root, 'build'),

package/dist/server/parts/k8s-probes.d.ts

@@ -0,0 +1,2 @@
+import type { FastifyInstance } from 'fastify';
+export declare function setupK8SProbes(app: FastifyInstance): Promise<void>;

package/dist/server/parts/k8s-probes.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setupK8SProbes = void 0;
+// Setup routes for k8s probes to check if application is live
+async function setupK8SProbes(app) {
+    // Handler for graceful shutdowns
+    // K8s can initiate shutdown at any moment: on pods restart or on deploy.
+    // So, if we receive shutdown request, we:
+    // - starts to send 503 response code on readiness probes to stop receiving requests
+    // - finishes all current requests
+    // - shuts down the server
+    let isShutdownInProgress = false;
+    app.gracefulShutdown((code, next) => {
+        // TODO: replace with nerest logger, when it'll be ready
+        console.log('Graceful shutdown in process...');
+        isShutdownInProgress = true;
+        next();
+    });
+    app.get('/livenessProbe', { logLevel: 'silent' }, (req, res) => {
+        res.status(200).send();
+    });
+    app.get('/readinessProbe', { logLevel: 'silent' }, (req, res) => {
+        if (isShutdownInProgress) {
+            res.status(503).send({ status: 'Shutdown in progress' });
+        }
+        else {
+            res.status(200).send();
+        }
+    });
+}
+exports.setupK8SProbes = setupK8SProbes;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nerest/nerest",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "description": "React micro frontend framework",
   "homepage": "https://github.com/nerestjs/nerest#readme",
   "repository": {
@@ -15,13 +15,15 @@
     "/bin",
     "/build",
     "/client",
+    "/schemas",
     "/server",
     "/README.md"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json -d",
     "lint": "eslint --ext .ts server bin",
-    "prepare": "simple-git-hooks"
+    "prepare": "simple-git-hooks",
+    "typegen": "json2ts -i 'schemas/**/*.json' -o schemas --bannerComment ''"
   },
   "simple-git-hooks": {
     "pre-commit": "npx lint-staged"
@@ -40,6 +42,9 @@
   },
   "prettier": "@tinkoff/prettier-config",
   "eslintConfig": {
+    "parserOptions": {
+      "project": true
+    },
     "extends": [
       "@tinkoff/eslint-config/lib",
       "@tinkoff/eslint-config/jest",
@@ -47,30 +52,33 @@
     ]
   },
   "dependencies": {
-    "@fastify/static": "^6.10.2",
-    "@fastify/swagger": "^8.5.1",
-    "@fastify/swagger-ui": "^1.8.1",
+    "@fastify/static": "^6.11.2",
+    "@fastify/swagger": "^8.12.0",
+    "@fastify/swagger-ui": "^1.10.1",
     "ajv": "^8.12.0",
     "ajv-formats": "^2.1.1",
-    "dotenv": "^16.1.4",
+    "dotenv": "^16.3.1",
     "fast-uri": "^2.2.0",
-    "fastify": "^4.17.0",
+    "fastify": "^4.24.3",
+    "fastify-graceful-shutdown": "^3.5.1",
     "nanoid": "^3.3.6",
-    "vite": "^4.3.9"
+    "vite": "^4.5.0",
+    "vite-plugin-externals": "^0.6.2"
   },
   "devDependencies": {
-    "@tinkoff/eslint-config": "^1.52.1",
-    "@tinkoff/eslint-config-react": "^1.52.1",
+    "@tinkoff/eslint-config": "^1.54.4",
+    "@tinkoff/eslint-config-react": "^1.54.4",
     "@tinkoff/prettier-config": "^1.52.1",
-    "@types/react": "^18.2.7",
-    "@types/react-dom": "^18.2.4",
-    "jest": "^29.5.0",
-    "lint-staged": "^13.2.2",
+    "@types/react": "^18.2.29",
+    "@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.8.1",
-    "sort-package-json": "^2.4.1",
-    "typescript": "^5.0.4"
+    "simple-git-hooks": "^2.9.0",
+    "sort-package-json": "^2.6.0",
+    "typescript": "^5.2.2"
   },
   "peerDependencies": {
     "react": "^18.0.0",

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

@@ -0,0 +1,16 @@
+/**
+ * Build configuration placed as nerest-build.schema.json in the root of the application.
+ */
+export interface BuildConfiguration {
+  /**
+   * Excludes modules from the client build and replaces them with empty modules instead.
+   */
+  excludes?: string[];
+  /**
+   * Excludes modules from the client build and maps them to globally available constants instead.
+   */
+  externals?: {
+    [k: string]: string;
+  };
+  [k: string]: unknown;
+}

package/schemas/nerest-build.schema.json

@@ -0,0 +1,22 @@
+{
+  "$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.",
+  "type": "object",
+  "properties": {
+    "excludes": {
+      "description": "Excludes modules from the client build and replaces them with empty modules instead.",
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "externals": {
+      "description": "Excludes modules from the client build and maps them to globally available constants instead.",
+      "type": "object",
+      "additionalProperties": {
+        "type": "string"
+      }
+    }
+  }
+}

package/server/development.ts

@@ -9,12 +9,14 @@ import type { RollupWatcher, RollupWatcherEvent } from 'rollup';
 import type { RouteShorthandOptions } from 'fastify';
 import fastify from 'fastify';
 import fastifyStatic from '@fastify/static';
+import fastifyGracefulShutdown from 'fastify-graceful-shutdown';
 
 import { loadApps } from './parts/apps';
 import { renderApp } from './parts/render';
 import { renderPreviewPage } from './parts/preview';
 import { validator } from './parts/validator';
 import { setupSwagger } from './parts/swagger';
+import { setupK8SProbes } from './parts/k8s-probes';
 
 export async function runDevelopmentServer() {
   const root = process.cwd();
@@ -148,6 +150,13 @@ export async function runDevelopmentServer() {
     }
   }
 
+  // Add graceful shutdown handler to prevent requests errors
+  await app.register(fastifyGracefulShutdown);
+
+  if (process.env.ENABLE_K8S_PROBES) {
+    await setupK8SProbes(app);
+  }
+
   // TODO: only do this locally, load from CDN in production
   await app.register(fastifyStatic, {
     root: path.join(root, 'build'),

package/server/parts/k8s-probes.ts

@@ -0,0 +1,30 @@
+import type { FastifyInstance } from 'fastify';
+
+// Setup routes for k8s probes to check if application is live
+export async function setupK8SProbes(app: FastifyInstance) {
+  // Handler for graceful shutdowns
+  // K8s can initiate shutdown at any moment: on pods restart or on deploy.
+  // So, if we receive shutdown request, we:
+  // - starts to send 503 response code on readiness probes to stop receiving requests
+  // - finishes all current requests
+  // - shuts down the server
+  let isShutdownInProgress = false;
+  app.gracefulShutdown((code, next) => {
+    // TODO: replace with nerest logger, when it'll be ready
+    console.log('Graceful shutdown in process...');
+    isShutdownInProgress = true;
+    next();
+  });
+
+  app.get('/livenessProbe', { logLevel: 'silent' }, (req, res) => {
+    res.status(200).send();
+  });
+
+  app.get('/readinessProbe', { logLevel: 'silent' }, (req, res) => {
+    if (isShutdownInProgress) {
+      res.status(503).send({ status: 'Shutdown in progress' });
+    } else {
+      res.status(200).send();
+    }
+  });
+}

package/server/production.ts

@@ -3,6 +3,7 @@ import path from 'path';
 import fs from 'fs/promises';
 
 import fastify from 'fastify';
+import fastifyGracefulShutdown from 'fastify-graceful-shutdown';
 import type { RouteShorthandOptions } from 'fastify';
 
 import type { AppEntry } from './parts/apps';
@@ -10,6 +11,7 @@ import { renderApp } from './parts/render';
 import { setupSwagger } from './parts/swagger';
 import { validator } from './parts/validator';
 import { renderPreviewPage } from './parts/preview';
+import { setupK8SProbes } from './parts/k8s-probes';
 
 // TODO: refactor to merge the similar parts between production and development server?
 async function runProductionServer() {
@@ -22,6 +24,7 @@ async function runProductionServer() {
     })
   ) as Record<string, AppEntry>;
 
+  // TODO: fix client-side vite types
   const components = import.meta.glob('/apps/*/index.tsx', {
     import: 'default',
     eager: true,
@@ -93,6 +96,13 @@ async function runProductionServer() {
     }
   }
 
+  // Add graceful shutdown handler to prevent requests errors
+  await app.register(fastifyGracefulShutdown);
+
+  if (process.env.ENABLE_K8S_PROBES) {
+    await setupK8SProbes(app);
+  }
+
   // TODO: remove hardcoded port
   await app.listen({
     host: '0.0.0.0',