@nerest/nerest 0.0.8 → 0.0.9

package/README.md

@@ -37,6 +37,21 @@ 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 a single object as an argument -- the body of the request. 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
+export default function (props: Props) {
+  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.

package/dist/server/development.js

@@ -10,7 +10,8 @@ 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';
 // eslint-disable-next-line max-statements
 export async function runDevelopmentServer() {
     const root = process.cwd();
@@ -59,7 +60,7 @@ export async function runDevelopmentServer() {
     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 +83,12 @@ export async function runDevelopmentServer() {
             const ssrComponent = await viteSsr.ssrLoadModule(entry, {
                 fixStacktrace: true,
             });
+            const props = await runPropsHook(request.body, () => 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
@@ -107,11 +109,12 @@ export async function runDevelopmentServer() {
                 const ssrComponent = await viteSsr.ssrLoadModule(entry, {
                     fixStacktrace: true,
                 });
+                const props = await runPropsHook(example, () => viteSsr.ssrLoadModule(propsHookEntry));
                 const { html, assets } = renderApp({
                     name,
                     assets: appEntry.assets,
                     component: ssrComponent.default,
-                }, example);
+                }, props);
                 reply.type('text/html');
                 return renderPreviewPage(html, assets);
             });

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

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

package/dist/server/hooks/props.js

@@ -0,0 +1,12 @@
+// Load the props hook module and run it if it exists, passing down app's
+// props object. This hook can be used to modify props before they are passed
+// to the root app component.
+export async function runPropsHook(props, 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) : 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,8 @@ 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';
 // TODO: refactor to merge the similar parts between production and development server?
 async function runProductionServer() {
     const root = process.cwd();
@@ -16,11 +17,13 @@ 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 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
@@ -30,6 +33,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 +47,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, 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
@@ -55,11 +62,12 @@ async function runProductionServer() {
                     description: `Open sandbox: [${exampleRoute}](${exampleRoute})`,
                 },
             }, async (_, reply) => {
+                const props = await runPropsHook(example, propsHook);
                 const { html, assets: outAssets } = renderApp({
                     name,
                     assets,
                     component,
-                }, example);
+                }, props);
                 reply.type('text/html');
                 return renderPreviewPage(html, outAssets);
             });

package/package.json

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

package/server/development.ts

@@ -17,7 +17,8 @@ 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';
 
 // eslint-disable-next-line max-statements
 export async function runDevelopmentServer() {
@@ -74,7 +75,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 +101,16 @@ export async function runDevelopmentServer() {
       const ssrComponent = await viteSsr.ssrLoadModule(entry, {
         fixStacktrace: true,
       });
+      const props = await runPropsHook(request.body, () =>
+        viteSsr.ssrLoadModule(propsHookEntry)
+      );
       return renderApp(
         {
           name,
           assets: appEntry.assets,
           component: ssrComponent.default,
         },
-        request.body as Record<string, unknown>
+        props
       );
     });
 
@@ -135,13 +139,16 @@ export async function runDevelopmentServer() {
           const ssrComponent = await viteSsr.ssrLoadModule(entry, {
             fixStacktrace: true,
           });
+          const props = await runPropsHook(example, () =>
+            viteSsr.ssrLoadModule(propsHookEntry)
+          );
           const { html, assets } = renderApp(
             {
               name,
               assets: appEntry.assets,
               component: ssrComponent.default,
             },
-            example as Record<string, unknown>
+            props
           );
 
           reply.type('text/html');

package/server/hooks/props.ts

@@ -0,0 +1,22 @@
+type PropsHookModule = {
+  default: (props: unknown) => unknown;
+};
+
+// Load the props hook module and run it if it exists, passing down app's
+// props object. This hook can be used to modify props before they are passed
+// to the root app component.
+export async function runPropsHook(
+  props: unknown,
+  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) : 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,8 @@ 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';
 
 // TODO: refactor to merge the similar parts between production and development server?
 async function runProductionServer() {
@@ -25,12 +26,15 @@ 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 propsHooks = import.meta.glob('/apps/*/props.ts', {
+    eager: true,
+  });
+
   const app = fastify();
 
   // Setup schema validation. We have to use our own ajv instance that
@@ -43,6 +47,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 +64,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, propsHook);
+      return renderApp({ name, assets, component }, props);
+    });
 
     for (const [exampleName, example] of Object.entries(examples)) {
       // GET /api/{name}/examples/{example} -> render a preview page
@@ -80,13 +83,14 @@ async function runProductionServer() {
           },
         },
         async (_, reply) => {
+          const props = await runPropsHook(example, propsHook);
           const { html, assets: outAssets } = renderApp(
             {
               name,
               assets,
               component,
             },
-            example as Record<string, unknown>
+            props
           );
 
           reply.type('text/html');