@nerest/nerest 0.0.2 → 0.0.4

package/README.md

@@ -12,9 +12,12 @@ npm i --save @nerest/nerest react react-dom
 
 ## Points of Interest
 
-- SSR server entry: [server/index.ts](server/index.ts)
+- SSR server entry:
+  - Development: [server/development.ts](server/development.ts)
+  - Production: [server/production.ts](server/production.ts)
 - Hydrating client entry: [client/index.ts](client/index.ts)
 - CLI entry: [bin/index.ts](bin/index.ts)
+- Production build script: [build/index.ts](build/index.ts)
 
 ## Conventions
 
@@ -30,6 +33,30 @@ The app directory may contain an `examples` subdirectory with example JSON files
 
 The app directory should contain a `schema.json` file that describes the schema of a request body for this specific app in the [JSON Schema language](https://json-schema.org/). All requests sent to this app, and app examples from the `examples` subdirectory will be validated against this schema. `ajv` and `ajv-formats` are used for validation, so all JSON Schema features implemented by them are supported.
 
+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`.
+
+## 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://github.com/nerestjs/harness) repository.
+
+### Environment Variables
+
+#### Buildtime
+
+- `NEREST_STATIC_PATH` is required for production build and must contain the URL of where the client static assets will be deployed. It lets the server-side renderer return their paths in the assets field of the response.
+
+#### Runtime
+
+All environment variables prefixed with `NEREST_` will be bundled with your app during buildtime. You can access them in the code using the special `import.meta.env` object. For example, `import.meta.env.NEREST_SOMEVAR` will be statically replaced during buildtime with the value of this environment variable on the build machine.
+
+### JSON Configuration
+
+TODO
+
+### Runtime Hooks
+
+TODO
+
 ## Development
 
 Run the build script to build the framework.
@@ -39,4 +66,4 @@ npm install
 npm run build
 ```
 
-Use [nerest-harness](https://github.com/nerestjs/harness) with `npm link` to test changes locally.
+Use [nerest-harness](https://github.com/nerestjs/harness) to test changes locally.

package/bin/build.ts

@@ -0,0 +1,8 @@
+import { buildMicroFrontend } from '../build';
+
+// Produce the production build of the Nerest micro frontend
+export async function build() {
+  console.log('Nerest is preparing production build...');
+  await buildMicroFrontend();
+  console.log('Nerest build is finished');
+}

package/bin/index.ts

@@ -1,9 +1,15 @@
 #!/usr/bin/env node
 // All executions of `nerest <command>` get routed through here
+import 'dotenv/config';
+
+import { build } from './build';
 import { watch } from './watch';
 
+// TODO: add CLI help and manual, maybe use a CLI framework like oclif
 async function cliEntry(args: string[]) {
-  if (args[0] === 'watch') {
+  if (args[0] === 'build') {
+    await build();
+  } else if (args[0] === 'watch') {
     await watch();
   }
 }

package/bin/watch.ts

@@ -1,18 +1,9 @@
-import { createServer } from '../server';
+import { runDevelopmentServer } from '../server/development';
 
 // Start dev server in watch mode, that restarts on file change
 // and rebuilds the client static files
 export async function watch() {
   // TODO: will be replaced with nerest logger
   console.log('Starting Nerest watch...');
-
-  const { app } = await createServer();
-
-  // 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');
+  await runDevelopmentServer();
 }

package/build/index.ts

@@ -0,0 +1,82 @@
+import path from 'path';
+import fs from 'fs/promises';
+
+import vite from 'vite';
+import type { InlineConfig } from 'vite';
+
+import { loadApps } from '../server/parts/apps';
+
+export async function buildMicroFrontend() {
+  const root = process.cwd();
+  const staticPath = process.env.NEREST_STATIC_PATH;
+
+  // TODO: The path where the client files are deployed is built-in during
+  // the initial build, but the client scripts aren't using it, so maybe it should
+  // be a runtime env variable for the server instead?
+  if (!staticPath) {
+    throw new Error(
+      'NEREST_STATIC_PATH environment variable is not set but is required for the production build'
+    );
+  }
+
+  // Build client
+  // TODO: extract shared parts between build/index.ts and server/index.ts
+  // into a shared config
+  const clientConfig: InlineConfig = {
+    root,
+    appType: 'custom',
+    envPrefix: 'NEREST_',
+    build: {
+      // Manifest is needed to report used assets in SSR handles
+      manifest: true,
+      modulePreload: false,
+      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]`,
+        },
+      },
+    },
+  };
+
+  console.log('Producing production client build...');
+  await vite.build(clientConfig);
+
+  console.log('Producing Nerest manifest file...');
+  await buildAppsManifest(root, staticPath);
+
+  // Build server using the client manifest
+  const serverConfig: InlineConfig = {
+    root,
+    appType: 'custom',
+    envPrefix: 'NEREST_',
+    build: {
+      emptyOutDir: false,
+      modulePreload: false,
+      // This is an important setting for producing a server build
+      ssr: true,
+      rollupOptions: {
+        input: '/node_modules/@nerest/nerest/server/production.ts',
+        output: {
+          dir: 'build',
+          entryFileNames: `server.mjs`,
+        },
+      },
+    },
+  };
+
+  console.log('Producing production server build...');
+  await vite.build(serverConfig);
+}
+
+async function buildAppsManifest(root: string, staticPath: string) {
+  const apps = await loadApps(root, staticPath);
+  await fs.writeFile(
+    path.join(root, 'build/nerest-manifest.json'),
+    JSON.stringify(apps),
+    { encoding: 'utf-8' }
+  );
+}

package/dist/bin/build.d.ts

@@ -0,0 +1 @@
+export declare function build(): Promise<void>;

package/dist/bin/build.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.build = void 0;
+const build_1 = require("../build");
+// Produce the production build of the Nerest micro frontend
+async function build() {
+    console.log('Nerest is preparing production build...');
+    await (0, build_1.buildMicroFrontend)();
+    console.log('Nerest build is finished');
+}
+exports.build = build;

package/dist/bin/index.d.ts

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-export {};
+import 'dotenv/config';

package/dist/bin/index.js

@@ -2,9 +2,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 // All executions of `nerest <command>` get routed through here
+require("dotenv/config");
+const build_1 = require("./build");
 const watch_1 = require("./watch");
+// TODO: add CLI help and manual, maybe use a CLI framework like oclif
 async function cliEntry(args) {
-    if (args[0] === 'watch') {
+    if (args[0] === 'build') {
+        await (0, build_1.build)();
+    }
+    else if (args[0] === 'watch') {
         await (0, watch_1.watch)();
     }
 }

package/dist/bin/watch.js

@@ -1,18 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.watch = void 0;
-const server_1 = require("../server");
+const development_1 = require("../server/development");
 // Start dev server in watch mode, that restarts on file change
 // and rebuilds the client static files
 async function watch() {
     // TODO: will be replaced with nerest logger
     console.log('Starting Nerest watch...');
-    const { app } = await (0, server_1.createServer)();
-    // 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');
+    await (0, development_1.runDevelopmentServer)();
 }
 exports.watch = watch;

package/dist/build/index.d.ts

@@ -0,0 +1 @@
+export declare function buildMicroFrontend(): Promise<void>;

package/dist/build/index.js

@@ -0,0 +1,72 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildMicroFrontend = void 0;
+const path_1 = __importDefault(require("path"));
+const promises_1 = __importDefault(require("fs/promises"));
+const vite_1 = __importDefault(require("vite"));
+const apps_1 = require("../server/parts/apps");
+async function buildMicroFrontend() {
+    const root = process.cwd();
+    const staticPath = process.env.NEREST_STATIC_PATH;
+    // TODO: The path where the client files are deployed is built-in during
+    // the initial build, but the client scripts aren't using it, so maybe it should
+    // be a runtime env variable for the server instead?
+    if (!staticPath) {
+        throw new Error('NEREST_STATIC_PATH environment variable is not set but is required for the production build');
+    }
+    // Build client
+    // TODO: extract shared parts between build/index.ts and server/index.ts
+    // into a shared config
+    const clientConfig = {
+        root,
+        appType: 'custom',
+        envPrefix: 'NEREST_',
+        build: {
+            // Manifest is needed to report used assets in SSR handles
+            manifest: true,
+            modulePreload: false,
+            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]`,
+                },
+            },
+        },
+    };
+    console.log('Producing production client build...');
+    await vite_1.default.build(clientConfig);
+    console.log('Producing Nerest manifest file...');
+    await buildAppsManifest(root, staticPath);
+    // Build server using the client manifest
+    const serverConfig = {
+        root,
+        appType: 'custom',
+        envPrefix: 'NEREST_',
+        build: {
+            emptyOutDir: false,
+            modulePreload: false,
+            // This is an important setting for producing a server build
+            ssr: true,
+            rollupOptions: {
+                input: '/node_modules/@nerest/nerest/server/production.ts',
+                output: {
+                    dir: 'build',
+                    entryFileNames: `server.mjs`,
+                },
+            },
+        },
+    };
+    console.log('Producing production server build...');
+    await vite_1.default.build(serverConfig);
+}
+exports.buildMicroFrontend = buildMicroFrontend;
+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' });
+}

package/dist/server/development.d.ts

@@ -0,0 +1 @@
+export declare function runDevelopmentServer(): Promise<void>;

package/dist/server/{index.js → development.js}

@@ -3,19 +3,18 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createServer = void 0;
-// This is the nerest server entrypoint
+exports.runDevelopmentServer = void 0;
+// This is the nerest development server entrypoint
 const path_1 = __importDefault(require("path"));
 const vite_1 = __importDefault(require("vite"));
 const fastify_1 = __importDefault(require("fastify"));
 const static_1 = __importDefault(require("@fastify/static"));
-const apps_1 = require("./apps");
-const render_1 = require("./render");
-const preview_1 = require("./preview");
-const validator_1 = require("./validator");
-// TODO: this turned out to be a dev server, production server
-// will most likely be implemented separately
-async function createServer() {
+const apps_1 = require("./parts/apps");
+const render_1 = require("./parts/render");
+const preview_1 = require("./parts/preview");
+const validator_1 = require("./parts/validator");
+const swagger_1 = require("./parts/swagger");
+async function runDevelopmentServer() {
     const root = process.cwd();
     // TODO: move build config into a separate file
     // TODO: look at @vitejs/plugin-react (everything seems fine without it though)
@@ -23,6 +22,7 @@ async function createServer() {
     const config = {
         root,
         appType: 'custom',
+        envPrefix: 'NEREST_',
         server: { middlewareMode: true },
         build: {
             // Manifest is needed to report used assets in SSR handles
@@ -33,18 +33,25 @@ 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
     // TODO: this should probably be moved from here
     await startClientBuildWatcher(config);
     // Load app entries following the `apps/{name}/index.tsx` convention
-    const apps = await (0, apps_1.loadApps)(root);
+    // TODO: remove hardcoded port
+    const apps = await (0, apps_1.loadApps)(root, 'http://0.0.0.0:3000/');
     // Start vite server that will be rendering SSR components
     const viteSsr = await vite_1.default.createServer(config);
     const app = (0, fastify_1.default)();
@@ -52,14 +59,22 @@ async function createServer() {
     // we can use both to validate request bodies and examples against
     // app schemas
     app.setValidatorCompiler(({ schema }) => validator_1.validator.compile(schema));
+    await (0, swagger_1.setupSwagger)(app);
     for (const appEntry of Object.values(apps)) {
         const { name, entry, examples, schema } = appEntry;
         const routeOptions = {};
-        // 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,
+                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
@@ -69,7 +84,11 @@ async function createServer() {
             const ssrComponent = await viteSsr.ssrLoadModule(entry, {
                 fixStacktrace: true,
             });
-            return (0, render_1.renderApp)(appEntry, ssrComponent.default, request.body);
+            return (0, render_1.renderApp)({
+                name,
+                assets: appEntry.assets,
+                component: ssrComponent.default,
+            }, request.body);
         });
         for (const [exampleName, example] of Object.entries(examples)) {
             // Validate example against schema when specified
@@ -79,19 +98,30 @@ 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 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 } = (0, render_1.renderApp)(appEntry, ssrComponent.default, example);
+                const { html, assets } = (0, render_1.renderApp)({
+                    name,
+                    assets: appEntry.assets,
+                    component: ssrComponent.default,
+                }, example);
                 reply.type('text/html');
                 return (0, preview_1.renderPreviewPage)(html, assets);
             });
         }
     }
     // TODO: only do this locally, load from CDN in production
-    app.register(static_1.default, {
-        root: path_1.default.join(root, 'dist'),
+    await app.register(static_1.default, {
+        root: path_1.default.join(root, 'build'),
         // TODO: maybe use @fastify/cors instead
         setHeaders(res) {
             res.setHeader('Access-Control-Allow-Origin', '*');
@@ -99,9 +129,14 @@ async function createServer() {
             res.setHeader('Access-Control-Allow-Headers', 'X-Requested-With, content-type, Authorization');
         },
     });
-    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');
 }
-exports.createServer = createServer;
+exports.runDevelopmentServer = runDevelopmentServer;
 // TODO: this should probably be moved from here
 async function startClientBuildWatcher(config) {
     const watcher = (await vite_1.default.build(config));

package/dist/server/loaders/assets.d.ts

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

package/dist/server/loaders/assets.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadAppAssets = void 0;
+// Extracts the list of assets for a given app from the manifest file
+function loadAppAssets(appName, manifest, staticPath) {
+    // 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);
+}
+exports.loadAppAssets = loadAppAssets;

package/dist/server/loaders/manifest.d.ts

@@ -0,0 +1 @@
+export declare function loadAppManifest(root: string): Promise<any>;

package/dist/server/loaders/manifest.js

@@ -0,0 +1,17 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadAppManifest = void 0;
+const path_1 = __importDefault(require("path"));
+const promises_1 = __importDefault(require("fs/promises"));
+// Manifest is used to provide assets list for every app
+// for use with SSR
+async function loadAppManifest(root) {
+    // TODO: error handling
+    const manifestPath = path_1.default.join(root, 'build', 'manifest.json');
+    const manifestData = await promises_1.default.readFile(manifestPath, { encoding: 'utf8' });
+    return JSON.parse(manifestData);
+}
+exports.loadAppManifest = loadAppManifest;

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

@@ -6,6 +6,6 @@ export type AppEntry = {
     examples: Record<string, unknown>;
     schema: Record<string, unknown> | null;
 };
-export declare function loadApps(root: string): Promise<{
+export declare function loadApps(root: string, deployedStaticPath: string): Promise<{
     [k: string]: AppEntry;
 }>;

package/dist/server/{apps.js → parts/apps.js}

@@ -6,26 +6,27 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.loadApps = void 0;
 const path_1 = __importDefault(require("path"));
 const promises_1 = __importDefault(require("fs/promises"));
-const assets_1 = require("./app-parts/assets");
-const examples_1 = require("./app-parts/examples");
-const schema_1 = require("./app-parts/schema");
+const assets_1 = require("../loaders/assets");
+const examples_1 = require("../loaders/examples");
+const schema_1 = require("../loaders/schema");
+const manifest_1 = require("../loaders/manifest");
 // Build the record of the available apps by convention
 // apps -> /apps/{name}/index.tsx
 // examples -> /apps/{name}/examples/{example}.json
-async function loadApps(root) {
+async function loadApps(root, deployedStaticPath) {
     const appsRoot = path_1.default.join(root, 'apps');
-    const manifest = await loadManifest(root);
+    const manifest = await (0, manifest_1.loadAppManifest)(root);
     const appsDirs = (await promises_1.default.readdir(appsRoot, { withFileTypes: true }))
         .filter((d) => d.isDirectory())
         .map((d) => d.name);
     const apps = [];
     for (const appDir of appsDirs) {
-        apps.push(await loadApp(appsRoot, appDir, manifest));
+        apps.push(await loadApp(appsRoot, appDir, manifest, deployedStaticPath));
     }
     return Object.fromEntries(apps);
 }
 exports.loadApps = loadApps;
-async function loadApp(appsRoot, name, manifest) {
+async function loadApp(appsRoot, name, manifest, deployedStaticPath) {
     // TODO: report problems with loading entries, assets and/or examples
     const appRoot = path_1.default.join(appsRoot, name);
     return [
@@ -34,17 +35,9 @@ async function loadApp(appsRoot, name, manifest) {
             name,
             root: appRoot,
             entry: path_1.default.join(appRoot, 'index.tsx'),
-            assets: (0, assets_1.loadAppAssets)(manifest, name),
+            assets: (0, assets_1.loadAppAssets)(name, manifest, deployedStaticPath),
             examples: await (0, examples_1.loadAppExamples)(appRoot),
             schema: await (0, schema_1.loadAppSchema)(appRoot),
         },
     ];
 }
-// Manifest is used to provide assets list for every app
-// for use with SSR
-async function loadManifest(root) {
-    // TODO: error handling
-    const manifestPath = path_1.default.join(root, 'dist', 'manifest.json');
-    const manifestData = await promises_1.default.readFile(manifestPath, { encoding: 'utf8' });
-    return JSON.parse(manifestData);
-}

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

@@ -0,0 +1,11 @@
+import React from 'react';
+type RenderProps = {
+    name: string;
+    assets: string[];
+    component: React.ComponentType;
+};
+export declare function renderApp({ name, assets, component }: RenderProps, props?: Record<string, unknown>): {
+    html: string;
+    assets: string[];
+};
+export {};

package/dist/server/{render.js → parts/render.js}

@@ -7,9 +7,8 @@ exports.renderApp = void 0;
 const react_1 = __importDefault(require("react"));
 const server_1 = require("react-dom/server");
 const nanoid_1 = require("nanoid");
-function renderApp(appEntry, appComponent, props = {}) {
-    const { name, assets } = appEntry;
-    const html = renderSsrComponent(name, appComponent, props);
+function renderApp({ name, assets, component }, props = {}) {
+    const html = renderSsrComponent(name, component, props);
     return { html, assets };
 }
 exports.renderApp = renderApp;

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

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