@nerest/nerest 0.0.8 → 0.1.0

package/README.md

@@ -37,6 +37,25 @@ The app directory should contain a `schema.json` file that describes the schema
 
 OpenAPI specification is compiled automatically based on the provided schemas and becomes available at `/api/json`. It can also be explored through Swagger UI that becomes available at `/api`.
 
+### Props Hook (`/props.ts`)
+
+The app directory may contain a `props.ts` module that exports a default function. If it exists, this function will be executed on the server for every incoming request, receiving the body of the request and a logger as parameters. You can use this hook to modify and return a new object, which will be passed down to the `index.tsx` entrypoint component instead. For example:
+
+```typescript
+import type { FastifyBaseLogger } from 'fastify';
+
+export default function (props: Props, logger: FastifyBaseLogger) {
+  logger.info('Hello from props.ts!');
+
+  return {
+    ...props,
+    greeting: `${props.greeting} (modified in props.ts)`,
+  };
+}
+```
+
+The exported function may be async, in which case nerest will wait for the Promise to resolve, then pass the result object to the entrypoint component.
+
 ## 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://gitlab.tcsbank.ru/tj/nerest-harness) repository.
@@ -84,7 +103,7 @@ Excludes modules from the client build and maps them to globally available const
 
 Here `react` and `react-dom` imports will be replaced with accessing the respective `window` constants.
 
-### Runtime Hooks
+### Runtime Hook
 
 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`:
 
@@ -98,6 +117,22 @@ export default function (app: FastifyInstance) {
 
 This runtime hook can be used to adjust fastify settings, register additional plugins or add custom routes.
 
+#### Logger Configuration
+
+Nerest uses the default server-side [fastify logger](https://fastify.dev/docs/latest/Reference/Logging/#logging), enabled by default. To configure or disable it, export a `logger` function from the `nerest-runtime.ts` module. It will be called on server start, and the return value will be passed to fastify as logger configuration.
+
+```typescript
+import type { FastifyServerOptions } from 'fastify';
+
+export function logger(): FastifyServerOptions['logger'] {
+  return { prettyPrint: true };
+}
+```
+
+To disable the logger, return `false` from the function.
+
+You can also supply your own logger instance. Instead of passing configuration options, pass the instance. The logger you supply must conform to the [Pino](https://github.com/pinojs/pino) interface; that is, it must have the following methods: `info`, `error`, `debug`, `fatal`, `warn`, `trace`, `silent`, `child` and a string property `level`.
+
 ## Development
 
 Run the build script to build the framework.

package/dist/server/development.js

@@ -10,7 +10,9 @@ import { renderPreviewPage } from './parts/preview.js';
 import { validator } from './parts/validator.js';
 import { setupSwagger } from './parts/swagger.js';
 import { setupK8SProbes } from './parts/k8s-probes.js';
-import { runRuntimeHook } from './parts/runtime-hook.js';
+import { runRuntimeHook } from './hooks/runtime.js';
+import { runPropsHook } from './hooks/props.js';
+import { runLoggerHook } from './hooks/logger.js';
 // eslint-disable-next-line max-statements
 export async function runDevelopmentServer() {
     const root = process.cwd();
@@ -52,14 +54,19 @@ export async function runDevelopmentServer() {
     const apps = await loadApps(root, 'http://0.0.0.0:3000/');
     // Start vite server that will be rendering SSR components
     const viteSsr = await createServer(config);
-    const app = fastify();
+    // Start fastify server that will be processing HTTP requests
+    const app = fastify({
+        // Receive logger configuration from `nerest-runtime.logger()` or
+        // use the default fastify one (`true`)
+        logger: (await runLoggerHook(() => viteSsr.ssrLoadModule('/nerest-runtime.ts'))) ?? true,
+    });
     // 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, entry, examples, schema } = appEntry;
+        const { name, entry, propsHookEntry, examples, schema } = appEntry;
         const routeOptions = {};
         // TODO: report error if schema is missing, unless this app is client-only
         if (schema) {
@@ -82,11 +89,12 @@ export async function runDevelopmentServer() {
             const ssrComponent = await viteSsr.ssrLoadModule(entry, {
                 fixStacktrace: true,
             });
+            const props = await runPropsHook(request.body, request.log, () => viteSsr.ssrLoadModule(propsHookEntry));
             return renderApp({
                 name,
                 assets: appEntry.assets,
                 component: ssrComponent.default,
-            }, request.body);
+            }, props);
         });
         for (const [exampleName, example] of Object.entries(examples)) {
             // Validate example against schema when specified
@@ -103,15 +111,16 @@ export async function runDevelopmentServer() {
                     // description so it's easier to navigate to
                     description: `Open sandbox: [${exampleRoute}](${exampleRoute})`,
                 },
-            }, async (_, reply) => {
+            }, async (request, reply) => {
                 const ssrComponent = await viteSsr.ssrLoadModule(entry, {
                     fixStacktrace: true,
                 });
+                const props = await runPropsHook(example, request.log, () => viteSsr.ssrLoadModule(propsHookEntry));
                 const { html, assets } = renderApp({
                     name,
                     assets: appEntry.assets,
                     component: ssrComponent.default,
-                }, example);
+                }, props);
                 reply.type('text/html');
                 return renderPreviewPage(html, assets);
             });
@@ -139,7 +148,6 @@ export async function runDevelopmentServer() {
         host: '0.0.0.0',
         port: 3000,
     });
-    console.log('Nerest is listening on 0.0.0.0:3000');
 }
 // TODO: this should probably be moved from here
 async function startClientBuildWatcher(config) {

package/dist/server/hooks/logger.d.ts

@@ -0,0 +1,2 @@
+/// <reference types="node" resolution-mode="require"/>
+export declare function runLoggerHook(loader: () => Promise<unknown>): Promise<boolean | import("fastify").FastifyBaseLogger | (import("fastify").FastifyLoggerOptions<import("fastify").RawServerDefault, import("fastify").FastifyRequest<import("fastify").RouteGenericInterface, import("fastify").RawServerDefault, import("http").IncomingMessage, import("fastify").FastifySchema, import("fastify").FastifyTypeProviderDefault, unknown, import("fastify").FastifyBaseLogger, import("fastify/types/type-provider.js").ResolveFastifyRequestType<import("fastify").FastifyTypeProviderDefault, import("fastify").FastifySchema, import("fastify").RouteGenericInterface>>, import("fastify").FastifyReply<import("fastify").RawServerDefault, import("http").IncomingMessage, import("http").ServerResponse<import("http").IncomingMessage>, import("fastify").RouteGenericInterface, unknown, import("fastify").FastifySchema, import("fastify").FastifyTypeProviderDefault, unknown>> & import("pino").default.LoggerOptions) | null | undefined>;

package/dist/server/hooks/logger.js

@@ -0,0 +1,21 @@
+// Load the runtime hook module and run it if it exists, to receive
+// logger configuration. If the `logger` function does not exist
+// in the module, ignore it and use default configuration.
+export async function runLoggerHook(loader) {
+    let module;
+    try {
+        module = (await loader());
+    }
+    catch { }
+    if (typeof module?.logger === 'function') {
+        // If module exists and exports a logger function, execute it
+        try {
+            return module.logger();
+        }
+        catch (e) {
+            console.error('Failed to load logger configuration', e);
+            process.exit(1);
+        }
+    }
+    return null;
+}

package/dist/server/hooks/props.d.ts

@@ -0,0 +1,2 @@
+import type { FastifyBaseLogger } from 'fastify';
+export declare function runPropsHook(props: unknown, logger: FastifyBaseLogger, loader: () => Promise<unknown>): Promise<Record<string, unknown>>;

package/dist/server/hooks/props.js

@@ -0,0 +1,14 @@
+// Load the props hook module and run it if it exists, passing down app's
+// props object and logger. This hook can be used to modify props before
+// they are passed to the root app component.
+export async function runPropsHook(props, logger, loader) {
+    let module;
+    try {
+        module = (await loader());
+    }
+    catch { }
+    // If module exists and exports a default function, run it to modify props
+    return (typeof module?.default === 'function'
+        ? module.default(props, logger)
+        : props);
+}

package/dist/server/hooks/runtime.d.ts

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

package/dist/server/hooks/runtime.js

@@ -0,0 +1,28 @@
+// 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, 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...');
+    }
+}

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

@@ -2,6 +2,7 @@ export type AppEntry = {
     name: string;
     root: string;
     entry: string;
+    propsHookEntry: string;
     assets: string[];
     examples: Record<string, unknown>;
     schema: Record<string, unknown> | null;

package/dist/server/parts/apps.js

@@ -28,6 +28,7 @@ async function loadApp(appsRoot, name, manifest, deployedStaticPath) {
             name,
             root: appRoot,
             entry: path.join(appRoot, 'index.tsx'),
+            propsHookEntry: path.join(appRoot, 'props.ts'),
             assets: loadAppAssets(name, manifest, deployedStaticPath),
             examples: await loadAppExamples(appRoot),
             schema: await loadAppSchema(appRoot),

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

@@ -0,0 +1 @@
+export declare function runPropsHook(props: unknown, loader: () => Promise<unknown>): Promise<Record<string, unknown>>;

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

@@ -0,0 +1,8 @@
+export async function runPropsHook(props, loader) {
+    let module;
+    try {
+        module = (await loader());
+    }
+    catch { }
+    return (typeof module?.default === 'function' ? module.default(props) : props);
+}

package/dist/server/production.js

@@ -8,7 +8,9 @@ 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 './parts/runtime-hook.js';
+import { runRuntimeHook } from './hooks/runtime.js';
+import { runPropsHook } from './hooks/props.js';
+import { runLoggerHook } from './hooks/logger.js';
 // TODO: refactor to merge the similar parts between production and development server?
 async function runProductionServer() {
     const root = process.cwd();
@@ -16,12 +18,20 @@ async function runProductionServer() {
     const apps = JSON.parse(await fs.readFile(path.join(root, 'build/nerest-manifest.json'), {
         encoding: 'utf-8',
     }));
-    // TODO: fix client-side vite types
     const components = import.meta.glob('/apps/*/index.tsx', {
         import: 'default',
         eager: true,
     });
-    const app = fastify();
+    const propsHooks = import.meta.glob('/apps/*/props.ts', {
+        eager: true,
+    });
+    const runtimeHook = import.meta.glob('/nerest-runtime.ts', { eager: true });
+    const app = fastify({
+        // Receive logger configuration from `nerest-runtime.logger()` or
+        // use the default fastify one (`true`)
+        logger: (await runLoggerHook(async () => runtimeHook['/nerest-runtime.ts'])) ??
+            true,
+    });
     // 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
@@ -30,6 +40,7 @@ async function runProductionServer() {
     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
@@ -43,7 +54,10 @@ async function runProductionServer() {
             };
         }
         // POST /api/{name} -> render app with request.body as props
-        app.post(`/api/${name}`, routeOptions, (request) => renderApp({ name, assets, component }, request.body));
+        app.post(`/api/${name}`, routeOptions, async (request) => {
+            const props = await runPropsHook(request.body, request.log, 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
@@ -54,12 +68,13 @@ async function runProductionServer() {
                     // description so it's easier to navigate to
                     description: `Open sandbox: [${exampleRoute}](${exampleRoute})`,
                 },
-            }, async (_, reply) => {
+            }, async (request, reply) => {
+                const props = await runPropsHook(example, request.log, propsHook);
                 const { html, assets: outAssets } = renderApp({
                     name,
                     assets,
                     component,
-                }, example);
+                }, props);
                 reply.type('text/html');
                 return renderPreviewPage(html, outAssets);
             });
@@ -71,15 +86,11 @@ 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'];
-    });
+    await runRuntimeHook(app, async () => runtimeHook['/nerest-runtime.ts']);
     // 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');
 }
 runProductionServer();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nerest/nerest",
-  "version": "0.0.8",
+  "version": "0.1.0",
   "description": "React micro frontend framework",
   "homepage": "https://github.com/nerestjs/nerest#readme",
   "repository": {

package/server/development.ts

@@ -17,7 +17,9 @@ import { renderPreviewPage } from './parts/preview.js';
 import { validator } from './parts/validator.js';
 import { setupSwagger } from './parts/swagger.js';
 import { setupK8SProbes } from './parts/k8s-probes.js';
-import { runRuntimeHook } from './parts/runtime-hook.js';
+import { runRuntimeHook } from './hooks/runtime.js';
+import { runPropsHook } from './hooks/props.js';
+import { runLoggerHook } from './hooks/logger.js';
 
 // eslint-disable-next-line max-statements
 export async function runDevelopmentServer() {
@@ -64,7 +66,16 @@ export async function runDevelopmentServer() {
 
   // Start vite server that will be rendering SSR components
   const viteSsr = await createServer(config);
-  const app = fastify();
+
+  // Start fastify server that will be processing HTTP requests
+  const app = fastify({
+    // Receive logger configuration from `nerest-runtime.logger()` or
+    // use the default fastify one (`true`)
+    logger:
+      (await runLoggerHook(() =>
+        viteSsr.ssrLoadModule('/nerest-runtime.ts')
+      )) ?? true,
+  });
 
   // Setup schema validation. We have to use our own ajv instance that
   // we can use both to validate request bodies and examples against
@@ -74,7 +85,7 @@ export async function runDevelopmentServer() {
   await setupSwagger(app);
 
   for (const appEntry of Object.values(apps)) {
-    const { name, entry, examples, schema } = appEntry;
+    const { name, entry, propsHookEntry, examples, schema } = appEntry;
 
     const routeOptions: RouteShorthandOptions = {};
 
@@ -100,13 +111,16 @@ export async function runDevelopmentServer() {
       const ssrComponent = await viteSsr.ssrLoadModule(entry, {
         fixStacktrace: true,
       });
+      const props = await runPropsHook(request.body, request.log, () =>
+        viteSsr.ssrLoadModule(propsHookEntry)
+      );
       return renderApp(
         {
           name,
           assets: appEntry.assets,
           component: ssrComponent.default,
         },
-        request.body as Record<string, unknown>
+        props
       );
     });
 
@@ -131,17 +145,20 @@ export async function runDevelopmentServer() {
             description: `Open sandbox: [${exampleRoute}](${exampleRoute})`,
           },
         },
-        async (_, reply) => {
+        async (request, reply) => {
           const ssrComponent = await viteSsr.ssrLoadModule(entry, {
             fixStacktrace: true,
           });
+          const props = await runPropsHook(example, request.log, () =>
+            viteSsr.ssrLoadModule(propsHookEntry)
+          );
           const { html, assets } = renderApp(
             {
               name,
               assets: appEntry.assets,
               component: ssrComponent.default,
             },
-            example as Record<string, unknown>
+            props
           );
 
           reply.type('text/html');
@@ -181,8 +198,6 @@ export async function runDevelopmentServer() {
     host: '0.0.0.0',
     port: 3000,
   });
-
-  console.log('Nerest is listening on 0.0.0.0:3000');
 }
 
 // TODO: this should probably be moved from here

package/server/hooks/logger.ts

@@ -0,0 +1,28 @@
+import type { FastifyServerOptions } from 'fastify';
+
+type LoggerHookModule = {
+  logger?: () => FastifyServerOptions['logger'];
+};
+
+// Load the runtime hook module and run it if it exists, to receive
+// logger configuration. If the `logger` function does not exist
+// in the module, ignore it and use default configuration.
+export async function runLoggerHook(loader: () => Promise<unknown>) {
+  let module: LoggerHookModule | undefined;
+
+  try {
+    module = (await loader()) as LoggerHookModule;
+  } catch {}
+
+  if (typeof module?.logger === 'function') {
+    // If module exists and exports a logger function, execute it
+    try {
+      return module.logger();
+    } catch (e) {
+      console.error('Failed to load logger configuration', e);
+      process.exit(1);
+    }
+  }
+
+  return null;
+}

package/server/hooks/props.ts

@@ -0,0 +1,27 @@
+import type { FastifyBaseLogger } from 'fastify';
+
+type PropsHookModule = {
+  default: (props: unknown, logger: FastifyBaseLogger) => unknown;
+};
+
+// Load the props hook module and run it if it exists, passing down app's
+// props object and logger. This hook can be used to modify props before
+// they are passed to the root app component.
+export async function runPropsHook(
+  props: unknown,
+  logger: FastifyBaseLogger,
+  loader: () => Promise<unknown>
+) {
+  let module: PropsHookModule | undefined;
+
+  try {
+    module = (await loader()) as PropsHookModule;
+  } catch {}
+
+  // If module exists and exports a default function, run it to modify props
+  return (
+    typeof module?.default === 'function'
+      ? module.default(props, logger)
+      : props
+  ) as Record<string, unknown>;
+}

package/server/parts/apps.ts

@@ -11,6 +11,7 @@ export type AppEntry = {
   name: string;
   root: string;
   entry: string;
+  propsHookEntry: string;
   assets: string[];
   examples: Record<string, unknown>;
   schema: Record<string, unknown> | null;
@@ -49,6 +50,7 @@ async function loadApp(
       name,
       root: appRoot,
       entry: path.join(appRoot, 'index.tsx'),
+      propsHookEntry: path.join(appRoot, 'props.ts'),
       assets: loadAppAssets(name, manifest, deployedStaticPath),
       examples: await loadAppExamples(appRoot),
       schema: await loadAppSchema(appRoot),

package/server/production.ts

@@ -12,7 +12,9 @@ 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 './parts/runtime-hook.js';
+import { runRuntimeHook } from './hooks/runtime.js';
+import { runPropsHook } from './hooks/props.js';
+import { runLoggerHook } from './hooks/logger.js';
 
 // TODO: refactor to merge the similar parts between production and development server?
 async function runProductionServer() {
@@ -25,13 +27,24 @@ 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,
   }) as Record<string, React.ComponentType>;
 
-  const app = fastify();
+  const propsHooks = import.meta.glob('/apps/*/props.ts', {
+    eager: true,
+  });
+
+  const runtimeHook = import.meta.glob('/nerest-runtime.ts', { eager: true });
+
+  const app = fastify({
+    // Receive logger configuration from `nerest-runtime.logger()` or
+    // use the default fastify one (`true`)
+    logger:
+      (await runLoggerHook(async () => runtimeHook['/nerest-runtime.ts'])) ??
+      true,
+  });
 
   // Setup schema validation. We have to use our own ajv instance that
   // we can use both to validate request bodies and examples against
@@ -43,6 +56,7 @@ async function runProductionServer() {
   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: RouteShorthandOptions = {};
 
@@ -59,12 +73,10 @@ async function runProductionServer() {
     }
 
     // POST /api/{name} -> render app with request.body as props
-    app.post(`/api/${name}`, routeOptions, (request) =>
-      renderApp(
-        { name, assets, component },
-        request.body as Record<string, unknown>
-      )
-    );
+    app.post(`/api/${name}`, routeOptions, async (request) => {
+      const props = await runPropsHook(request.body, request.log, propsHook);
+      return renderApp({ name, assets, component }, props);
+    });
 
     for (const [exampleName, example] of Object.entries(examples)) {
       // GET /api/{name}/examples/{example} -> render a preview page
@@ -79,14 +91,15 @@ async function runProductionServer() {
             description: `Open sandbox: [${exampleRoute}](${exampleRoute})`,
           },
         },
-        async (_, reply) => {
+        async (request, reply) => {
+          const props = await runPropsHook(example, request.log, propsHook);
           const { html, assets: outAssets } = renderApp(
             {
               name,
               assets,
               component,
             },
-            example as Record<string, unknown>
+            props
           );
 
           reply.type('text/html');
@@ -105,18 +118,13 @@ async function runProductionServer() {
   }
 
   // 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'];
-  });
+  await runRuntimeHook(app, async () => runtimeHook['/nerest-runtime.ts']);
 
   // 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');
 }
 
 runProductionServer();