@nerest/nerest 0.0.5 → 0.0.7

package/README.md

@@ -61,11 +61,42 @@ Additional environment variables which can be setup for a runtime:
 
 ### 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
 
-TODO
+If the module `nerest-runtime.ts` exists in the root of the micro frontend and exports a default function, this function will be executed when the server starts, and the fastify app instance will be passed to it as its only argument. Example of `nerest-runtime.ts`:
+
+```typescript
+import type { FastifyInstance } from 'fastify';
+
+export default function (app: FastifyInstance) {
+  console.log('Hello from nerest-runtime.ts');
+}
+```
+
+This runtime hook can be used to adjust fastify settings, register additional plugins or add custom routes.
 
 ## Development
 

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

@@ -16,6 +16,8 @@ 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");
+const runtime_hook_1 = require("./parts/runtime-hook");
+// eslint-disable-next-line max-statements
 async function runDevelopmentServer() {
     const root = process.cwd();
     // TODO: move build config into a separate file
@@ -136,6 +138,8 @@ async function runDevelopmentServer() {
             res.setHeader('Access-Control-Allow-Headers', 'X-Requested-With, content-type, Authorization');
         },
     });
+    // Execute runtime hook in nerest-runtime.ts if it exists
+    await (0, runtime_hook_1.runRuntimeHook)(app, () => viteSsr.ssrLoadModule('/nerest-runtime.ts'));
     // TODO: remove hardcoded port
     await app.listen({
         host: '0.0.0.0',

package/dist/server/parts/runtime-hook.d.ts

@@ -0,0 +1,2 @@
+import type { FastifyInstance } from 'fastify';
+export declare function runRuntimeHook(app: FastifyInstance, loader: () => Promise<Record<string, any>>): Promise<void>;

package/dist/server/parts/runtime-hook.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runRuntimeHook = void 0;
+// Load the runtime hook module and run it if it exists, passing down our
+// fastify instance. This hook can be used to modify fastify settings, add
+// plugins or routes on an individual app level.
+async function runRuntimeHook(app, loader) {
+    let module;
+    try {
+        module = (await loader());
+    }
+    catch { }
+    if (typeof module?.default === 'function') {
+        // If module exists and exports a default function, execute it and
+        // pass down the fastify instance
+        try {
+            await module.default(app);
+        }
+        catch (e) {
+            console.error('Failed to execute runtime hook', e);
+            process.exit(1);
+        }
+    }
+    else if (module) {
+        console.error("Runtime hook found, but doesn't export default function!");
+        process.exit(1);
+    }
+    else {
+        console.log('Runtime hook not found, skipping...');
+    }
+}
+exports.runRuntimeHook = runRuntimeHook;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nerest/nerest",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "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,31 +52,33 @@
     ]
   },
   "dependencies": {
-    "@fastify/static": "^6.10.2",
-    "@fastify/swagger": "^8.5.1",
-    "@fastify/swagger-ui": "^1.8.1",
+    "@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.1.4",
-    "fast-uri": "^2.2.0",
-    "fastify": "^4.17.0",
+    "dotenv": "^16.3.1",
+    "fast-uri": "^2.3.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.33",
+    "@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

@@ -17,7 +17,9 @@ import { renderPreviewPage } from './parts/preview';
 import { validator } from './parts/validator';
 import { setupSwagger } from './parts/swagger';
 import { setupK8SProbes } from './parts/k8s-probes';
+import { runRuntimeHook } from './parts/runtime-hook';
 
+// eslint-disable-next-line max-statements
 export async function runDevelopmentServer() {
   const root = process.cwd();
 
@@ -171,6 +173,9 @@ export async function runDevelopmentServer() {
     },
   });
 
+  // Execute runtime hook in nerest-runtime.ts if it exists
+  await runRuntimeHook(app, () => viteSsr.ssrLoadModule('/nerest-runtime.ts'));
+
   // TODO: remove hardcoded port
   await app.listen({
     host: '0.0.0.0',

package/server/parts/runtime-hook.ts

@@ -0,0 +1,35 @@
+import type { FastifyInstance } from 'fastify';
+
+type RuntimeHookModule = {
+  default: (app: FastifyInstance) => unknown;
+};
+
+// Load the runtime hook module and run it if it exists, passing down our
+// fastify instance. This hook can be used to modify fastify settings, add
+// plugins or routes on an individual app level.
+export async function runRuntimeHook(
+  app: FastifyInstance,
+  loader: () => Promise<Record<string, any>>
+) {
+  let module: RuntimeHookModule | undefined;
+
+  try {
+    module = (await loader()) as RuntimeHookModule;
+  } catch {}
+
+  if (typeof module?.default === 'function') {
+    // If module exists and exports a default function, execute it and
+    // pass down the fastify instance
+    try {
+      await module.default(app);
+    } catch (e) {
+      console.error('Failed to execute runtime hook', e);
+      process.exit(1);
+    }
+  } else if (module) {
+    console.error("Runtime hook found, but doesn't export default function!");
+    process.exit(1);
+  } else {
+    console.log('Runtime hook not found, skipping...');
+  }
+}

package/server/production.ts

@@ -12,6 +12,7 @@ import { setupSwagger } from './parts/swagger';
 import { validator } from './parts/validator';
 import { renderPreviewPage } from './parts/preview';
 import { setupK8SProbes } from './parts/k8s-probes';
+import { runRuntimeHook } from './parts/runtime-hook';
 
 // TODO: refactor to merge the similar parts between production and development server?
 async function runProductionServer() {
@@ -103,6 +104,12 @@ async function runProductionServer() {
     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'];
+  });
+
   // TODO: remove hardcoded port
   await app.listen({
     host: '0.0.0.0',