@nerest/nerest 0.0.9 → 1.5.0

package/server/development.ts

@@ -1,176 +1,86 @@
 // This is the nerest development server entrypoint
 import path from 'path';
-import type { ServerResponse } from 'http';
-
-import { build, createServer } from 'vite';
+import { build, createServer as createViteServer } from 'vite';
 import type { InlineConfig } from 'vite';
 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 fastifyMiddie from '@fastify/middie';
+import { createServer } from './shared.js';
+import {
+  viteConfigDevelopmentClient,
+  viteConfigDevelopmentServer,
+} from '../build/configs/development.js';
+import { loadBuildConfig } from './loaders/build.js';
+import { loadApps } from './loaders/apps.js';
+import { loadProject } from './loaders/project.js';
+
+export async function runDevelopmentServer(port: number) {
+  const root = process.cwd();
 
-import { loadApps } from './parts/apps.js';
-import { renderApp } from './parts/render.js';
-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 './hooks/runtime.js';
-import { runPropsHook } from './hooks/props.js';
+  // Allow overriding STATIC_PATH in development, useful for debugging
+  // micro frontend from another device on the same local network
+  let staticPath = process.env.STATIC_PATH || `http://127.0.0.1:${port}/`;
+  if (!staticPath.endsWith('/')) {
+    staticPath += '/';
+  }
 
-// eslint-disable-next-line max-statements
-export async function runDevelopmentServer() {
-  const root = process.cwd();
+  // Generate vite configuration with nerest/build.json applied
+  const buildConfig = await loadBuildConfig(root);
 
-  // TODO: move build config into a separate file
-  // TODO: look at @vitejs/plugin-react (everything seems fine without it though)
-  // TODO: look at @vitejs/plugin-legacy (needed for browsers without module support)
-  const config: InlineConfig = {
-    root,
-    appType: 'custom',
-    envPrefix: 'NEREST_',
-    server: { middlewareMode: true },
-    build: {
-      // Manifest is needed to report used assets in SSR handles
-      manifest: true,
-      modulePreload: false,
-      // TODO: watch is only necessary for the client build
-      watch: {},
-      rollupOptions: {
-        input: '/node_modules/@nerest/nerest/client/index.ts',
-        output: {
-          dir: 'build',
-          entryFileNames: `client/assets/[name].js`,
-          chunkFileNames: `client/assets/[name].js`,
-          assetFileNames: `client/assets/[name].[ext]`,
-        },
-      },
-    },
-    // TODO: this doesn't seem to work without the index.html file entry and
-    // produces warnings in dev mode. look into this maybe
-    optimizeDeps: {
-      disabled: true,
-    },
-  };
+  // Load project meta details
+  const project = await loadProject(root);
 
   // Build the clientside assets and watch for changes
-  // TODO: this should probably be moved from here
-  await startClientBuildWatcher(config);
-
-  // Load app entries following the `apps/{name}/index.tsx` convention
-  // TODO: remove hardcoded port
-  const apps = await loadApps(root, 'http://0.0.0.0:3000/');
+  await startClientBuildWatcher(
+    await viteConfigDevelopmentClient({
+      root,
+      base: staticPath,
+      buildConfig,
+      project,
+    })
+  );
 
   // Start vite server that will be rendering SSR components
-  const viteSsr = await createServer(config);
-  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);
+  const viteSsr = await createViteServer(
+    await viteConfigDevelopmentServer({
+      root,
+      base: staticPath,
+      buildConfig,
+      project,
+    })
+  );
 
-  for (const appEntry of Object.values(apps)) {
-    const { name, entry, propsHookEntry, examples, schema } = appEntry;
-
-    const routeOptions: RouteShorthandOptions = {};
-
-    // TODO: report error if schema is missing, unless this app is client-only
-    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 as string,
-        body: {
-          ...schema,
-          // Mix examples into the schema so they become accessible
-          // in the Swagger UI
-          examples: Object.values(examples),
-        },
-      };
-    }
-
-    // POST /api/{name} -> render app with request.body as props
-    app.post(`/api/${name}`, routeOptions, async (request) => {
-      // ssrLoadModule drives the "hot-reload" logic, and allows
-      // picking up changes to the source without restarting the server
-      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,
-        },
-        props
-      );
-    });
-
-    for (const [exampleName, example] of Object.entries(examples)) {
-      // Validate example against schema when specified
-      if (schema && !validator.validate(schema, example)) {
-        // TODO: use logger and display errors more prominently
-        console.error(
-          `Example "${exampleName}" of app "${name}" does not satisfy schema: ${validator.errorsText()}`
-        );
-      }
-
-      // 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 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,
-            },
-            props
-          );
-
-          reply.type('text/html');
-
-          return renderPreviewPage(html, assets);
-        }
-      );
-    }
-  }
+  // Load app entries following the `apps/{name}/index.tsx` convention
+  const apps = await loadApps(root, staticPath);
 
-  // Add graceful shutdown handler to prevent requests errors
-  await app.register(fastifyGracefulShutdown);
+  const app = await createServer({
+    root,
+    project,
+    apps,
+    // ssrLoadModule picks up the changes without restarting the server
+    loadComponent: async (entry: string) =>
+      (
+        await viteSsr.ssrLoadModule(`/apps/${entry}/index.tsx`, {
+          fixStacktrace: true,
+        })
+      ).default,
+    loadPropsHook: (entry: string) =>
+      viteSsr.ssrLoadModule(`/apps/${entry}/props.ts`),
+    loadRuntimeHook: () => viteSsr.ssrLoadModule('/nerest/runtime.ts'),
+  });
 
-  if (process.env.ENABLE_K8S_PROBES) {
-    await setupK8SProbes(app);
-  }
+  // Register middie to use vite's Connect-style middlewares
+  await app.register(fastifyMiddie);
+  app.use(viteSsr.middlewares);
 
-  // TODO: only do this locally, load from CDN in production
+  // @fastify/static is only used locally for development, in production static
+  // files are served from STATIC_PATH, which is usually a CDN location
   await app.register(fastifyStatic, {
-    root: path.join(root, 'build'),
-    // TODO: maybe use @fastify/cors instead
-    setHeaders(res: ServerResponse) {
+    root: path.join(root, 'build/client/assets'),
+
+    // Set CORS headers so the development server assets can be accessed from
+    // remote devices, e.g. mobile phones
+    setHeaders(res) {
       res.setHeader('Access-Control-Allow-Origin', '*');
       res.setHeader('Access-Control-Allow-Methods', 'GET');
       res.setHeader(
@@ -180,19 +90,12 @@ 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',
-    port: 3000,
+    port,
   });
-
-  console.log('Nerest is listening on 0.0.0.0:3000');
 }
 
-// TODO: this should probably be moved from here
 async function startClientBuildWatcher(config: InlineConfig) {
   const watcher = (await build(config)) as RollupWatcher;
   return new Promise<void>((resolve) => {

package/server/hooks/logger.ts

@@ -0,0 +1,31 @@
+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) {
+      // Allow console.error here, because we can't app.log the error if we
+      // can't create the logger in the first place.
+      // eslint-disable-next-line no-console
+      console.error('Failed to load logger configuration', e);
+      process.exit(1);
+    }
+  }
+
+  return null;
+}

package/server/hooks/props.ts

@@ -1,13 +1,16 @@
+import type { FastifyBaseLogger, FastifyInstance } from 'fastify';
+
 type PropsHookModule = {
-  default: (props: unknown) => unknown;
+  default: (props: unknown, logger: FastifyBaseLogger) => 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.
+// 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,
-  loader: () => Promise<unknown>
+  app: FastifyInstance,
+  loader: () => Promise<unknown>,
+  props: unknown
 ) {
   let module: PropsHookModule | undefined;
 
@@ -17,6 +20,8 @@ export async function runPropsHook(
 
   // If module exists and exports a default function, run it to modify props
   return (
-    typeof module?.default === 'function' ? module.default(props) : props
+    typeof module?.default === 'function'
+      ? module.default(props, app.log)
+      : props
   ) as Record<string, unknown>;
 }

package/server/hooks/runtime.ts

@@ -23,13 +23,13 @@ export async function runRuntimeHook(
     try {
       await module.default(app);
     } catch (e) {
-      console.error('Failed to execute runtime hook', e);
+      app.log.fatal('Failed to execute runtime hook', e);
       process.exit(1);
     }
   } else if (module) {
-    console.error("Runtime hook found, but doesn't export default function!");
+    app.log.fatal("Runtime hook found, but doesn't export default function!");
     process.exit(1);
   } else {
-    console.log('Runtime hook not found, skipping...');
+    app.log.info('Runtime hook not found, skipping...');
   }
 }

package/server/loaders/apps.ts

@@ -0,0 +1,58 @@
+import path from 'path';
+import fg from 'fast-glob';
+import type { Manifest as ViteManifest } from 'vite';
+import type { JSONSchema } from '@apidevtools/json-schema-ref-parser';
+
+import { loadAppAssets } from './assets.js';
+import { loadAppExamples } from './examples.js';
+import { loadAppSchema } from './schema.js';
+import { loadViteManifest } from './manifest.js';
+
+export type AppEntry = {
+  name: string;
+  root: string;
+  entry: string;
+  propsHookEntry: string;
+  assets: string[];
+  examples: Record<string, unknown>;
+  schema: JSONSchema | null;
+};
+
+// Build the record of the available apps by convention
+// apps -> /apps/{name}/index.tsx
+// examples -> /apps/{name}/examples/{example}.json
+export async function loadApps(root: string, deployedStaticPath: string) {
+  const manifest = await loadViteManifest(root);
+
+  const appBase = path.join(root, 'apps');
+  const appPattern = `${fg.convertPathToPattern(appBase)}/*`;
+  const appDirs = await fg.glob(appPattern, { onlyDirectories: true });
+
+  const apps: Array<[name: string, entry: AppEntry]> = [];
+  for (const appDir of appDirs) {
+    apps.push(await loadApp(appDir, manifest, deployedStaticPath));
+  }
+
+  return Object.fromEntries(apps);
+}
+
+async function loadApp(
+  appDir: string,
+  manifest: ViteManifest,
+  deployedStaticPath: string
+): Promise<[name: string, entry: AppEntry]> {
+  // TODO: report problems with loading entries, assets and/or examples
+  const name = path.basename(appDir);
+  return [
+    name,
+    {
+      name,
+      root: appDir,
+      entry: path.join(appDir, 'index.tsx'),
+      propsHookEntry: path.join(appDir, 'props.ts'),
+      assets: loadAppAssets(name, manifest, deployedStaticPath),
+      examples: await loadAppExamples(appDir),
+      schema: await loadAppSchema(appDir),
+    },
+  ];
+}

package/server/loaders/assets.ts

@@ -13,7 +13,35 @@ export function loadAppAssets(
     manifest['node_modules/@nerest/nerest/client/index.ts'].file;
 
   // Each app has its own CSS bundles, if it imports any CSS
-  const appCss = manifest[`apps/${appName}/index.tsx`].css ?? [];
+  const appCss = collectCssUrls(manifest, `apps/${appName}/index.tsx`);
 
-  return [clientEntryJs, ...appCss].map((x) => staticPath + x);
+  return [clientEntryJs, ...appCss].map((x) => new URL(x, staticPath).href);
+}
+
+// Collects all CSS URLs by walking the manifest tree of static imports
+// for a specific entry. These CSS chunks are loaded dynamically by Vite,
+// but we need to inject them into the page statically to prevent a flash
+// of unstyled content
+function collectCssUrls(manifest: Manifest, entryName: string) {
+  const cssUrls = new Set<string>();
+  const scannedEntries = new Set([entryName]);
+  const queue = [entryName];
+
+  while (queue.length > 0) {
+    const entry = queue.shift()!;
+    const manifestEntry = manifest[entry];
+
+    if (manifestEntry) {
+      manifestEntry.css?.forEach((url) => cssUrls.add(url));
+
+      manifestEntry.imports?.forEach((name) => {
+        if (!scannedEntries.has(name)) {
+          scannedEntries.add(name);
+          queue.push(name);
+        }
+      });
+    }
+  }
+
+  return cssUrls;
 }

package/server/loaders/build.ts

@@ -0,0 +1,14 @@
+import path from 'path';
+import fs from 'fs/promises';
+import { existsSync } from 'fs';
+
+import type { BuildConfiguration } from '../../schemas/nerest-build.schema.js';
+
+// TODO: error handling
+export async function loadBuildConfig(root: string) {
+  const configPath = path.join(root, 'nerest/build.json');
+  if (existsSync(configPath)) {
+    const content = await fs.readFile(configPath, 'utf-8');
+    return JSON.parse(content) as BuildConfiguration;
+  }
+}

package/server/loaders/examples.ts

@@ -1,29 +1,21 @@
 import path from 'path';
-import { existsSync } from 'fs';
 import fs from 'fs/promises';
+import fg from 'fast-glob';
 
 // Loads and parses the example json files for providing
 // `/examples/` routes of the dev server
 export async function loadAppExamples(appRoot: string) {
-  const examplesRoot = path.join(appRoot, 'examples');
-
-  // Examples are optional and may not exist
-  if (!existsSync(examplesRoot)) {
-    return {};
-  }
-
-  const exampleFiles = (await fs.readdir(examplesRoot, { withFileTypes: true }))
-    .filter((d) => d.isFile() && d.name.endsWith('.json'))
-    .map((d) => d.name);
+  const exampleBase = path.join(appRoot, 'examples');
+  const examplePattern = `${fg.convertPathToPattern(exampleBase)}/*.json`;
+  const exampleFiles = await fg.glob(examplePattern, { onlyFiles: true });
 
   const examples: Record<string, unknown> = {};
 
   // TODO: error handling and reporting
-  for (const filename of exampleFiles) {
-    const file = path.join(examplesRoot, filename);
-    const content = await fs.readFile(file, { encoding: 'utf8' });
+  for (const filePath of exampleFiles) {
+    const content = await fs.readFile(filePath, 'utf-8');
     const json = JSON.parse(content);
-    examples[path.basename(filename, '.json')] = json;
+    examples[path.basename(filePath, '.json')] = json;
   }
 
   return examples;

package/server/loaders/manifest.ts

@@ -1,11 +1,30 @@
 import path from 'path';
 import fs from 'fs/promises';
+import type { Manifest as ViteManifest } from 'vite';
 
-// Manifest is used to provide assets list for every app
+import type { Project } from './project.js';
+import type { AppEntry } from './apps.js';
+
+// Vite manifest is used to provide assets list for every app
 // for use with SSR
-export async function loadAppManifest(root: string) {
+export async function loadViteManifest(root: string): Promise<ViteManifest> {
+  // TODO: error handling
+  const manifestPath = path.join(
+    root,
+    'build/client/assets/.vite/manifest.json'
+  );
+  const manifestData = await fs.readFile(manifestPath, 'utf-8');
+  return JSON.parse(manifestData);
+}
+
+// Nerest manifest contains info about the whole project
+// and every app within it
+export async function loadNerestManifest(root: string): Promise<{
+  project: Project;
+  apps: Record<string, AppEntry>;
+}> {
   // TODO: error handling
-  const manifestPath = path.join(root, 'build', 'manifest.json');
-  const manifestData = await fs.readFile(manifestPath, { encoding: 'utf8' });
+  const manifestPath = path.join(root, 'build/nerest-manifest.json');
+  const manifestData = await fs.readFile(manifestPath, 'utf-8');
   return JSON.parse(manifestData);
 }

package/server/loaders/preview.ts

@@ -0,0 +1,17 @@
+import path from 'path';
+import { existsSync } from 'fs';
+import fs from 'fs/promises';
+
+export type PreviewParts = {
+  head: string;
+};
+
+export async function loadPreviewParts(root: string): Promise<PreviewParts> {
+  let head = '';
+  const headPath = path.join(root, 'nerest/preview-head.html');
+  if (existsSync(headPath)) {
+    head = await fs.readFile(headPath, 'utf-8');
+  }
+
+  return { head };
+}

package/server/loaders/project.ts

@@ -0,0 +1,33 @@
+import path from 'path';
+import fs from 'fs/promises';
+
+export type Project = {
+  name: string;
+  description?: string;
+  version?: string;
+  homepage?: string;
+  repository?: string | { url?: string };
+};
+
+// Loads project meta information and available apps
+export async function loadProject(root: string) {
+  const packageJson = await fs.readFile(
+    path.join(root, 'package.json'),
+    'utf-8'
+  );
+  const {
+    name = '',
+    description,
+    version,
+    homepage,
+    repository,
+  } = JSON.parse(packageJson);
+
+  if (!name) {
+    console.warn(
+      '"name" is not set in package.json, this may cause conflicts when hydrating multiple apps from different micro frontends'
+    );
+  }
+
+  return { name, description, version, homepage, repository };
+}

package/server/loaders/schema.ts

@@ -1,18 +1,20 @@
 import path from 'path';
 import { existsSync } from 'fs';
-import fs from 'fs/promises';
+import RefParser from '@apidevtools/json-schema-ref-parser';
 
 // Loads and parses the schema file for a specific app
 export async function loadAppSchema(appRoot: string) {
   const schemaPath = path.join(appRoot, 'schema.json');
 
-  let schema = null;
-
-  // TODO: error handling and reporting
-  if (existsSync(schemaPath)) {
-    const file = await fs.readFile(schemaPath, { encoding: 'utf-8' });
-    schema = JSON.parse(file);
-  }
-
-  return schema;
+  // We are using dereference to resolve $refs in schema files and
+  // to resolve relative dependencies between schemas. The resolved
+  // schema will be stringified and saved in the build manifest,
+  // so we need it to have no circular references.
+  return existsSync(schemaPath)
+    ? RefParser.dereference(schemaPath, {
+        dereference: {
+          circular: false,
+        },
+      })
+    : null;
 }

package/server/parts/k8s-probes.ts

@@ -9,22 +9,35 @@ export async function setupK8SProbes(app: FastifyInstance) {
   // - 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.gracefulShutdown(() => {
+    app.log.info('Graceful shutdown in process...');
+    isShutdownInProgress = true;
   });
 
-  app.get('/readinessProbe', { logLevel: 'silent' }, (req, res) => {
-    if (isShutdownInProgress) {
-      res.status(503).send({ status: 'Shutdown in progress' });
-    } else {
+  app.get(
+    '/livenessProbe',
+    {
+      schema: { tags: ['@service'] },
+      logLevel: 'silent',
+    },
+    (req, res) => {
       res.status(200).send();
     }
-  });
+  );
+
+  app.get(
+    '/readinessProbe',
+    {
+      schema: { tags: ['@service'] },
+      logLevel: 'silent',
+    },
+    (req, res) => {
+      if (isShutdownInProgress) {
+        res.status(503).send({ status: 'Shutdown in progress' });
+      } else {
+        res.status(200).send();
+      }
+    }
+  );
 }