@nerest/nerest 0.0.2 → 0.0.4

package/dist/server/parts/swagger.js

@@ -0,0 +1,50 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setupSwagger = void 0;
+const path_1 = __importDefault(require("path"));
+const fs_1 = __importDefault(require("fs"));
+const swagger_1 = __importDefault(require("@fastify/swagger"));
+const swagger_ui_1 = __importDefault(require("@fastify/swagger-ui"));
+// Setup automatic OpenAPI specification compilation and enable
+// Swagger UI at the `/api` route
+async function setupSwagger(app) {
+    let appInfo = {};
+    try {
+        const packageJson = fs_1.default.readFileSync(path_1.default.join(process.cwd(), 'package.json'), { encoding: 'utf-8' });
+        appInfo = JSON.parse(packageJson);
+    }
+    catch (e) {
+        // We only use package.json info to setup Swagger info and links,
+        // if we are unable to load them -- that's fine
+    }
+    const homepage = appInfo.homepage ||
+        (typeof appInfo.repository === 'string'
+            ? appInfo.repository
+            : appInfo.repository?.url);
+    await app.register(swagger_1.default, {
+        openapi: {
+            info: {
+                title: appInfo.name ?? 'Nerest micro frontend',
+                description: appInfo.description,
+                version: appInfo.version ?? '',
+                contact: homepage
+                    ? {
+                        name: 'Homepage',
+                        url: homepage,
+                    }
+                    : undefined,
+            },
+            externalDocs: {
+                url: 'https://github.com/nerestjs/nerest',
+                description: 'Built with Nerest',
+            },
+        },
+    });
+    await app.register(swagger_ui_1.default, {
+        routePrefix: '/api',
+    });
+}
+exports.setupSwagger = setupSwagger;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nerest/nerest",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "React micro frontend framework",
   "homepage": "https://github.com/nerestjs/nerest#readme",
   "repository": {
@@ -13,6 +13,7 @@
   "files": [
     "/dist",
     "/bin",
+    "/build",
     "/client",
     "/server",
     "/README.md"
@@ -46,27 +47,30 @@
     ]
   },
   "dependencies": {
-    "@fastify/static": "^6.9.0",
+    "@fastify/static": "^6.10.2",
+    "@fastify/swagger": "^8.5.1",
+    "@fastify/swagger-ui": "^1.8.1",
     "ajv": "^8.12.0",
     "ajv-formats": "^2.1.1",
+    "dotenv": "^16.1.4",
     "fast-uri": "^2.2.0",
-    "fastify": "^4.13.0",
-    "nanoid": "^3.3.4",
-    "vite": "^4.1.4"
+    "fastify": "^4.17.0",
+    "nanoid": "^3.3.6",
+    "vite": "^4.3.9"
   },
   "devDependencies": {
-    "@tinkoff/eslint-config": "^1.50.1",
-    "@tinkoff/eslint-config-react": "^1.50.2",
-    "@tinkoff/prettier-config": "^1.47.1",
-    "@types/react": "^18.0.28",
-    "@types/react-dom": "^18.0.11",
-    "jest": "^29.4.3",
-    "lint-staged": "^13.1.2",
+    "@tinkoff/eslint-config": "^1.52.1",
+    "@tinkoff/eslint-config-react": "^1.52.1",
+    "@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",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
     "simple-git-hooks": "^2.8.1",
     "sort-package-json": "^2.4.1",
-    "typescript": "^4.9.5"
+    "typescript": "^5.0.4"
   },
   "peerDependencies": {
     "react": "^18.0.0",

package/server/{index.ts → development.ts}

@@ -1,4 +1,4 @@
-// This is the nerest server entrypoint
+// This is the nerest development server entrypoint
 import path from 'path';
 import type { ServerResponse } from 'http';
 
@@ -10,14 +10,13 @@ import type { RouteShorthandOptions } from 'fastify';
 import fastify from 'fastify';
 import fastifyStatic from '@fastify/static';
 
-import { loadApps } from './apps';
-import { renderApp } from './render';
-import { renderPreviewPage } from './preview';
-import { validator } from './validator';
+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';
 
-// TODO: this turned out to be a dev server, production server
-// will most likely be implemented separately
-export async function createServer() {
+export async function runDevelopmentServer() {
   const root = process.cwd();
 
   // TODO: move build config into a separate file
@@ -26,6 +25,7 @@ export async function createServer() {
   const config: InlineConfig = {
     root,
     appType: 'custom',
+    envPrefix: 'NEREST_',
     server: { middlewareMode: true },
     build: {
       // Manifest is needed to report used assets in SSR handles
@@ -36,12 +36,18 @@ export async function createServer() {
       rollupOptions: {
         input: '/node_modules/@nerest/nerest/client/index.ts',
         output: {
-          entryFileNames: `assets/[name].js`,
-          chunkFileNames: `assets/[name].js`,
-          assetFileNames: `assets/[name].[ext]`,
+          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,
+    },
   };
 
   // Build the clientside assets and watch for changes
@@ -49,7 +55,8 @@ export async function createServer() {
   await startClientBuildWatcher(config);
 
   // Load app entries following the `apps/{name}/index.tsx` convention
-  const apps = await loadApps(root);
+  // TODO: remove hardcoded port
+  const apps = await loadApps(root, 'http://0.0.0.0:3000/');
 
   // Start vite server that will be rendering SSR components
   const viteSsr = await vite.createServer(config);
@@ -60,16 +67,25 @@ export async function createServer() {
   // 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 routeOptions: RouteShorthandOptions = {};
 
-    // TODO: report error if schema is missing, unless this app is client-only.
-    // TODO: disallow apps without schemas in production build
+    // TODO: report error if schema is missing, unless this app is client-only
     if (schema) {
       routeOptions.schema = {
-        body: 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),
+        },
       };
     }
 
@@ -81,8 +97,11 @@ export async function createServer() {
         fixStacktrace: true,
       });
       return renderApp(
-        appEntry,
-        ssrComponent.default,
+        {
+          name,
+          assets: appEntry.assets,
+          component: ssrComponent.default,
+        },
         request.body as Record<string, unknown>
       );
     });
@@ -98,26 +117,40 @@ export async function createServer() {
 
       // GET /api/{name}/examples/{example} -> render a preview page
       // with a predefined example body
-      app.get(`/api/${name}/examples/${exampleName}`, async (_, reply) => {
-        const ssrComponent = await viteSsr.ssrLoadModule(entry, {
-          fixStacktrace: true,
-        });
-        const { html, assets } = renderApp(
-          appEntry,
-          ssrComponent.default,
-          example as Record<string, unknown>
-        );
-
-        reply.type('text/html');
-
-        return renderPreviewPage(html, assets);
-      });
+      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 { html, assets } = renderApp(
+            {
+              name,
+              assets: appEntry.assets,
+              component: ssrComponent.default,
+            },
+            example as Record<string, unknown>
+          );
+
+          reply.type('text/html');
+
+          return renderPreviewPage(html, assets);
+        }
+      );
     }
   }
 
   // TODO: only do this locally, load from CDN in production
-  app.register(fastifyStatic, {
-    root: path.join(root, 'dist'),
+  await app.register(fastifyStatic, {
+    root: path.join(root, 'build'),
     // TODO: maybe use @fastify/cors instead
     setHeaders(res: ServerResponse) {
       res.setHeader('Access-Control-Allow-Origin', '*');
@@ -129,7 +162,13 @@ export async function createServer() {
     },
   });
 
-  return { app };
+  // 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');
 }
 
 // TODO: this should probably be moved from here

package/server/loaders/assets.ts

@@ -0,0 +1,19 @@
+import type { Manifest } from 'vite';
+
+// Extracts the list of assets for a given app from the manifest file
+export function loadAppAssets(
+  appName: string,
+  manifest: Manifest,
+  staticPath: string
+) {
+  // TODO: handling errors and potentially missing entries
+  // All apps share the same JS entry that dynamically imports the chunks of the apps
+  // that are used on the page based on their name
+  const clientEntryJs =
+    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 ?? [];
+
+  return [clientEntryJs, ...appCss].map((x) => staticPath + x);
+}

package/server/loaders/manifest.ts

@@ -0,0 +1,11 @@
+import path from 'path';
+import fs from 'fs/promises';
+
+// Manifest is used to provide assets list for every app
+// for use with SSR
+export async function loadAppManifest(root: string) {
+  // TODO: error handling
+  const manifestPath = path.join(root, 'build', 'manifest.json');
+  const manifestData = await fs.readFile(manifestPath, { encoding: 'utf8' });
+  return JSON.parse(manifestData);
+}

package/server/{apps.ts → parts/apps.ts}

@@ -2,9 +2,10 @@ import path from 'path';
 import fs from 'fs/promises';
 import type { Manifest } from 'vite';
 
-import { loadAppAssets } from './app-parts/assets';
-import { loadAppExamples } from './app-parts/examples';
-import { loadAppSchema } from './app-parts/schema';
+import { loadAppAssets } from '../loaders/assets';
+import { loadAppExamples } from '../loaders/examples';
+import { loadAppSchema } from '../loaders/schema';
+import { loadAppManifest } from '../loaders/manifest';
 
 export type AppEntry = {
   name: string;
@@ -18,9 +19,9 @@ export type AppEntry = {
 // 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) {
+export async function loadApps(root: string, deployedStaticPath: string) {
   const appsRoot = path.join(root, 'apps');
-  const manifest = await loadManifest(root);
+  const manifest = await loadAppManifest(root);
 
   const appsDirs = (await fs.readdir(appsRoot, { withFileTypes: true }))
     .filter((d) => d.isDirectory())
@@ -28,7 +29,7 @@ export async function loadApps(root: string) {
 
   const apps: Array<[name: string, entry: AppEntry]> = [];
   for (const appDir of appsDirs) {
-    apps.push(await loadApp(appsRoot, appDir, manifest));
+    apps.push(await loadApp(appsRoot, appDir, manifest, deployedStaticPath));
   }
 
   return Object.fromEntries(apps);
@@ -37,7 +38,8 @@ export async function loadApps(root: string) {
 async function loadApp(
   appsRoot: string,
   name: string,
-  manifest: Manifest
+  manifest: Manifest,
+  deployedStaticPath: string
 ): Promise<[name: string, entry: AppEntry]> {
   // TODO: report problems with loading entries, assets and/or examples
   const appRoot = path.join(appsRoot, name);
@@ -47,18 +49,9 @@ async function loadApp(
       name,
       root: appRoot,
       entry: path.join(appRoot, 'index.tsx'),
-      assets: loadAppAssets(manifest, name),
+      assets: loadAppAssets(name, manifest, deployedStaticPath),
       examples: await loadAppExamples(appRoot),
       schema: await loadAppSchema(appRoot),
     },
   ];
 }
-
-// Manifest is used to provide assets list for every app
-// for use with SSR
-async function loadManifest(root: string) {
-  // TODO: error handling
-  const manifestPath = path.join(root, 'dist', 'manifest.json');
-  const manifestData = await fs.readFile(manifestPath, { encoding: 'utf8' });
-  return JSON.parse(manifestData);
-}

package/server/{render.ts → parts/render.ts}

@@ -2,15 +2,17 @@ import React from 'react';
 import { renderToString } from 'react-dom/server';
 import { nanoid } from 'nanoid';
 
-import type { AppEntry } from './apps';
+type RenderProps = {
+  name: string;
+  assets: string[];
+  component: React.ComponentType;
+};
 
 export function renderApp(
-  appEntry: AppEntry,
-  appComponent: React.ComponentType,
+  { name, assets, component }: RenderProps,
   props: Record<string, unknown> = {}
 ) {
-  const { name, assets } = appEntry;
-  const html = renderSsrComponent(name, appComponent, props);
+  const html = renderSsrComponent(name, component, props);
   return { html, assets };
 }
 

package/server/parts/swagger.ts

@@ -0,0 +1,58 @@
+import path from 'path';
+import fs from 'fs';
+import type { FastifyInstance } from 'fastify';
+import fastifySwagger from '@fastify/swagger';
+import fastifySwaggerUi from '@fastify/swagger-ui';
+
+// Setup automatic OpenAPI specification compilation and enable
+// Swagger UI at the `/api` route
+export async function setupSwagger(app: FastifyInstance) {
+  let appInfo: {
+    name?: string;
+    description?: string;
+    version?: string;
+    homepage?: string;
+    repository?: string | { url?: string };
+  } = {};
+
+  try {
+    const packageJson = fs.readFileSync(
+      path.join(process.cwd(), 'package.json'),
+      { encoding: 'utf-8' }
+    );
+    appInfo = JSON.parse(packageJson);
+  } catch (e) {
+    // We only use package.json info to setup Swagger info and links,
+    // if we are unable to load them -- that's fine
+  }
+
+  const homepage =
+    appInfo.homepage ||
+    (typeof appInfo.repository === 'string'
+      ? appInfo.repository
+      : appInfo.repository?.url);
+
+  await app.register(fastifySwagger, {
+    openapi: {
+      info: {
+        title: appInfo.name ?? 'Nerest micro frontend',
+        description: appInfo.description,
+        version: appInfo.version ?? '',
+        contact: homepage
+          ? {
+              name: 'Homepage',
+              url: homepage,
+            }
+          : undefined,
+      },
+      externalDocs: {
+        url: 'https://github.com/nerestjs/nerest',
+        description: 'Built with Nerest',
+      },
+    },
+  });
+
+  await app.register(fastifySwaggerUi, {
+    routePrefix: '/api',
+  });
+}

package/server/production.ts

@@ -0,0 +1,105 @@
+// This is the nerest production server entrypoint
+import path from 'path';
+import fs from 'fs/promises';
+
+import fastify from 'fastify';
+import type { RouteShorthandOptions } from 'fastify';
+
+import type { AppEntry } from './parts/apps';
+import { renderApp } from './parts/render';
+import { setupSwagger } from './parts/swagger';
+import { validator } from './parts/validator';
+import { renderPreviewPage } from './parts/preview';
+
+// TODO: refactor to merge the similar parts between production and development server?
+async function runProductionServer() {
+  const root = process.cwd();
+
+  // TODO: error handling for file reading
+  const apps = JSON.parse(
+    await fs.readFile(path.join(root, 'build/nerest-manifest.json'), {
+      encoding: 'utf-8',
+    })
+  ) as Record<string, AppEntry>;
+
+  const components = import.meta.glob('/apps/*/index.tsx', {
+    import: 'default',
+    eager: true,
+  }) as Record<string, React.ComponentType>;
+
+  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);
+
+  for (const appEntry of Object.values(apps)) {
+    const { name, examples, schema, assets } = appEntry;
+    const component = components[`/apps/${name}/index.tsx`];
+
+    const routeOptions: RouteShorthandOptions = {};
+
+    // TODO: report error if schema is missing, unless this app is client-only
+    // TODO: disallow apps without schemas in production build
+    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,
+        // TODO: do we need to mix in examples like in the development server?
+        body: schema,
+      };
+    }
+
+    // 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>
+      )
+    );
+
+    for (const [exampleName, example] of Object.entries(examples)) {
+      // 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 { html, assets: outAssets } = renderApp(
+            {
+              name,
+              assets,
+              component,
+            },
+            example as Record<string, unknown>
+          );
+
+          reply.type('text/html');
+
+          return renderPreviewPage(html, outAssets);
+        }
+      );
+    }
+  }
+
+  // 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/dist/client/entry.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/client/entry.js

@@ -1,3 +0,0 @@
-const apps = import.meta.glob('/apps/*/index.tsx', { import: 'default' });
-console.log(apps);
-export {};

package/dist/server/app-parts/assets.d.ts

@@ -1,2 +0,0 @@
-import type { Manifest } from 'vite';
-export declare function loadAppAssets(manifest: Manifest, appName: string): string[];

package/dist/server/app-parts/assets.js

@@ -1,15 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.loadAppAssets = void 0;
-// TODO: this is not as simple in the real world
-const publicPath = process.env.PUBLIC_PATH ?? 'http://0.0.0.0:3000/';
-// Extracts the list of assets for a given app from the manifest file
-function loadAppAssets(manifest, appName) {
-    const entries = Object.entries(manifest);
-    // TODO: handling errors and potentially missing entries
-    const clientEntryJs = entries.find(([_, entry]) => entry.isEntry)?.[1].file;
-    const appCss = entries.find(([name, _]) => name.includes(`/${appName}/index.tsx`))?.[1]
-        .css ?? [];
-    return [clientEntryJs, ...appCss].map((x) => publicPath + x);
-}
-exports.loadAppAssets = loadAppAssets;

package/dist/server/app-parts/preview.js

@@ -1,27 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.renderPreviewPage = void 0;
-function renderPreviewPage(html, assets) {
-    const { scripts, styles } = mapAssets(assets);
-    return `
-  <html>
-  <head>
-    ${styles.join('\n')}
-  </head>
-  <body>
-    ${html}
-    ${scripts.join('\n')}
-  </body>
-  </html>
-  `;
-}
-exports.renderPreviewPage = renderPreviewPage;
-function mapAssets(assets) {
-    const scripts = assets
-        .filter((src) => src.endsWith('.js'))
-        .map((src) => `<script type="module" src="${src}"></script>`);
-    const styles = assets
-        .filter((src) => src.endsWith('.css'))
-        .map((src) => `<link rel="stylesheet" href="${src}">`);
-    return { scripts, styles };
-}

package/dist/server/assets.d.ts

@@ -1 +0,0 @@
-export declare function getAppAssets(appName: string, root: string): Promise<string[]>;

package/dist/server/assets.js

@@ -1,28 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.getAppAssets = void 0;
-const path_1 = __importDefault(require("path"));
-const promises_1 = __importDefault(require("fs/promises"));
-// TODO: way more complicated in the real world
-const publicPath = process.env.PUBLIC_PATH ?? 'http://127.0.0.1:3000/';
-async function getAppAssets(appName, root) {
-    const manifest = await loadManifest(root);
-    const assets = extractAssetsFromManifest(manifest, appName);
-    return assets.map((x) => publicPath + x);
-}
-exports.getAppAssets = getAppAssets;
-async function loadManifest(root) {
-    const manifestPath = path_1.default.join(root, 'dist', 'manifest.json');
-    const manifestData = await promises_1.default.readFile(manifestPath, { encoding: 'utf8' });
-    return JSON.parse(manifestData);
-}
-function extractAssetsFromManifest(manifest, appName) {
-    const entries = Object.entries(manifest);
-    const clientEntryJs = entries.find(([_, entry]) => entry.isEntry)?.[1].file;
-    const appCss = entries.find(([name, _]) => name.includes(`/${appName}/index.tsx`))?.[1]
-        .css ?? [];
-    return [clientEntryJs, ...appCss];
-}

package/dist/server/entry.d.ts

@@ -1,2 +0,0 @@
-import React from 'react';
-export declare function renderSsrComponent(appName: string, AppComponent: React.ComponentType, props?: Record<string, unknown>): string;