@nerest/nerest 0.1.0 → 1.5.0

package/build/configs/vite-logger.development.ts

@@ -0,0 +1,30 @@
+// https://vite.dev/config/shared-options.html#customlogger
+import { createLogger } from 'vite';
+
+const logger = createLogger();
+
+const loggerError = logger.error;
+logger.error = (msg, options) => {
+  if (typeof msg === 'string' && !isIgnoredError(msg)) {
+    loggerError(msg, options);
+  }
+};
+
+export default logger;
+
+// These are errors expected in development that we don't need to log.
+// If the error message includes all markers from a set, it is suppressed
+const ignoredErrors = [
+  // Hook files are optional, but in development vite logs an error even though
+  // we suppress the exception. Silence these logs manually.
+  ['cannot find entry point module', 'props.ts'],
+  ['cannot find entry point module', 'runtime.ts'],
+];
+
+function isIgnoredError(msg: string) {
+  for (const markers of ignoredErrors) {
+    if (markers.every((m) => msg.includes(m))) {
+      return true;
+    }
+  }
+}

package/build/index.ts

@@ -1,105 +1,82 @@
 import path from 'path';
 import fs from 'fs/promises';
-import { existsSync } from 'fs';
 
 import { build } from 'vite';
-import type { InlineConfig } from 'vite';
-import { viteExternalsPlugin } from 'vite-plugin-externals';
 
-import { loadApps } from '../server/parts/apps.js';
-import type { BuildConfiguration } from '../schemas/nerest-build.schema.js';
-import { excludes } from './excludes/index.js';
+import { loadBuildConfig } from '../server/loaders/build.js';
+import { loadApps } from '../server/loaders/apps.js';
+import type { Project } from '../server/loaders/project.js';
+import { loadProject } from '../server/loaders/project.js';
+import {
+  viteConfigProductionClient,
+  viteConfigProductionServer,
+} from './configs/production.js';
 
 export async function buildMicroFrontend() {
   const root = process.cwd();
-  const staticPath = process.env.NEREST_STATIC_PATH;
+  const staticPath = prepareStaticPath();
 
-  // 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'
-    );
-  }
+  // Read build customizations from nerest/build.json
+  const buildConfig = await loadBuildConfig(root);
 
-  const buildConfig = await readBuildConfig(root);
+  // Read project meta info from package.json
+  const project = await loadProject(root);
 
   // Build client
-  // TODO: extract shared parts between build/index.ts and server/index.ts
-  // into a shared config
-  const clientConfig: InlineConfig = {
+  const clientViteConfig = await viteConfigProductionClient({
     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]`,
-        },
-      },
-    },
-    resolve: {
-      // excludes - map buildConfig.excludes packages to an empty module
-      alias: excludes(buildConfig?.excludes),
-    },
-    plugins: [
-      // externals - map buildConfig.externals packages to a global variable on window
-      viteExternalsPlugin(buildConfig?.externals, { useWindow: false }),
-    ],
-  };
-
+    base: staticPath,
+    buildConfig,
+    project,
+  });
   console.log('Producing production client build...');
-  await build(clientConfig);
+  await build(clientViteConfig);
 
+  // Create nerest-manifest.json that production server reads on startup
   console.log('Producing Nerest manifest file...');
-  await buildAppsManifest(root, staticPath);
+  await createNerestManifest(root, staticPath, project);
 
-  // Build server using the client manifest
-  const serverConfig: InlineConfig = {
+  // Build server
+  const serverViteConfig = await viteConfigProductionServer({
     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`,
-        },
-      },
-    },
-  };
-
+    base: staticPath,
+    buildConfig,
+    project,
+  });
   console.log('Producing production server build...');
-  await build(serverConfig);
+  await build(serverViteConfig);
 }
 
-async function buildAppsManifest(root: string, staticPath: string) {
+async function createNerestManifest(
+  root: string,
+  staticPath: string,
+  project: Project
+) {
   const apps = await loadApps(root, staticPath);
   await fs.writeFile(
     path.join(root, 'build/nerest-manifest.json'),
-    JSON.stringify(apps),
-    { encoding: 'utf-8' }
+    JSON.stringify({ project, apps }),
+    'utf-8'
   );
 }
 
-// TODO: error handling
-async function readBuildConfig(root: string) {
-  const configPath = path.join(root, 'nerest-build.json');
-  if (existsSync(configPath)) {
-    const content = await fs.readFile(configPath, { encoding: 'utf-8' });
-    return JSON.parse(content) as BuildConfiguration;
+function prepareStaticPath() {
+  let staticPath = process.env.STATIC_PATH;
+
+  // The path where the client files are deployed is embedded
+  // during the initial build.
+  // TODO: handle error if STATIC_PATH isn't a valid base URL
+  if (!staticPath) {
+    throw new Error(
+      'STATIC_PATH environment variable is not set but is required for the production build'
+    );
   }
+
+  // Static path is a directory URI. To be treated as such by node:url,
+  // it has to end with a trailing slash
+  if (!staticPath.endsWith('/')) {
+    staticPath += '/';
+  }
+
+  return staticPath;
 }

package/client/index.ts

@@ -10,8 +10,10 @@ import ReactDOM from 'react-dom/client';
 const modules = import.meta.glob('/apps/*/index.tsx', { import: 'default' });
 
 async function runHydration() {
-  for (const container of document.querySelectorAll('div[data-app-name]')) {
-    const appName = container.getAttribute('data-app-name');
+  for (const container of document.querySelectorAll(
+    `div[data-project-name="${import.meta.env.NEREST_PROJECT_NAME}"]`
+  )) {
+    const appName = container.getAttribute(`data-app-name`);
     const appModuleLoader = modules[`/apps/${appName}/index.tsx`];
 
     if (!appModuleLoader || container.hasAttribute('data-app-hydrated')) {
@@ -37,8 +39,18 @@ async function runHydration() {
   }
 }
 
+// Apps can only be hydrated after DOM is ready, because we need to query
+// apps' containers and their corresponding scripts.
 if (document.readyState !== 'complete') {
   document.addEventListener('DOMContentLoaded', runHydration);
 } else {
   runHydration();
 }
+
+// Entries might be self-initializing (e.g. client-only apps) or have other
+// side effects. In that case we have to load them eagerly, so that their
+// initialization code can run, even if there is nothing to hydrate.
+const clientSideEffects: string[] | undefined = JSON.parse(
+  import.meta.env.NEREST_CLIENT_SIDE_EFFECTS
+);
+clientSideEffects?.forEach((name) => modules[`/apps/${name}/index.tsx`]?.());

package/dist/bin/index.js

@@ -2,12 +2,16 @@
 // All executions of `nerest <command>` get routed through here
 import 'dotenv/config';
 import { build } from './build.js';
+import { typegen } from './typegen.js';
 import { watch } from './watch.js';
 // TODO: add CLI help and manual, maybe use a CLI framework like oclif
 async function cliEntry(args) {
     if (args[0] === 'build') {
         await build();
     }
+    else if (args[0] === 'typegen') {
+        await typegen(args.slice(1));
+    }
     else if (args[0] === 'watch') {
         await watch();
     }

package/dist/bin/typegen.d.ts

@@ -0,0 +1 @@
+export declare function typegen(globs: string[]): Promise<void>;

package/dist/bin/typegen.js

@@ -0,0 +1,31 @@
+import path from 'path';
+import fs from 'fs/promises';
+import fg from 'fast-glob';
+import { compileFromFile } from 'json-schema-to-typescript';
+// Comment at the start of every type definition file, alerting
+// developers to not modify the file by hand
+const bannerComment = `
+/**
+ * This file was automatically generated by Nerest.
+ * DO NOT MODIFY IT BY HAND. Instead, modify the source schema.json file,
+ * and run "nerest typegen" to regenerate this file.
+ */`.trim();
+// Generates a TypeScript type definition for each JSON Schema in the given globs
+export async function typegen(globs) {
+    // If no globs are provided, default to the schema.json file in each app directory
+    if (globs.length === 0) {
+        globs = ['apps/*/schema.json'];
+    }
+    const paths = await fg.glob(globs, { onlyFiles: true });
+    console.log(`Found ${paths.length} schemas, generating types...`);
+    for (const schemaPath of paths) {
+        // Turn each schema.json file into schema.d.ts
+        const typePath = schemaPath.replace('.json', '.d.ts');
+        const type = await compileFromFile(schemaPath, {
+            cwd: path.resolve(path.dirname(schemaPath)),
+            bannerComment,
+        });
+        await fs.writeFile(typePath, type, 'utf-8');
+        console.log(`${schemaPath} -> ${typePath}`);
+    }
+}

package/dist/bin/watch.js

@@ -2,7 +2,6 @@ import { runDevelopmentServer } from '../server/development.js';
 // 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...');
-    await runDevelopmentServer();
+    await runDevelopmentServer(process.env.PORT ? Number(process.env.PORT) : 3000);
 }

package/dist/build/configs/development.d.ts

@@ -0,0 +1,4 @@
+import type { InlineConfig } from 'vite';
+import type { BuildArgs } from './shared.js';
+export declare function viteConfigDevelopmentClient(args: BuildArgs): Promise<InlineConfig>;
+export declare function viteConfigDevelopmentServer(args: BuildArgs): Promise<InlineConfig>;

package/dist/build/configs/development.js

@@ -0,0 +1,53 @@
+import { viteConfigShared } from './shared.js';
+import logger from './vite-logger.development.js';
+export async function viteConfigDevelopmentClient(args) {
+    return {
+        ...(await viteConfigShared(args)),
+        build: {
+            // Manifest is needed to report used assets in SSR handles
+            manifest: true,
+            modulePreload: false,
+            watch: {},
+            rollupOptions: {
+                input: '/node_modules/@nerest/nerest/client/index.ts',
+                output: {
+                    dir: 'build/client/assets',
+                    entryFileNames: `[name].js`,
+                    chunkFileNames: `[name].js`,
+                    assetFileNames: `[name].[ext]`,
+                },
+            },
+        },
+        customLogger: logger,
+    };
+}
+export async function viteConfigDevelopmentServer(args) {
+    return {
+        ...(await viteConfigShared(args)),
+        server: {
+            // Middleware lets vite compile on the fly, providing
+            // hot reload of certain modules
+            middlewareMode: true,
+            // Origin to serve imported assets from (like images)
+            origin: new URL(args.base).origin,
+            // Run HMR WebSocket server on random port to prevent conflicts
+            // between multiple projects running simultaneously
+            hmr: { port: randomPort() },
+            // Allow requests from all hosts in development
+            allowedHosts: true,
+        },
+        // optimizeDeps is only necessary with index.html entrypoint,
+        // which we don't have
+        optimizeDeps: {
+            noDiscovery: true,
+            include: [],
+        },
+        customLogger: logger,
+    };
+}
+// Returns a random high-number port to prevent conflicts
+function randomPort() {
+    // 49152-65535 is the ephemeral port range
+    // https://datatracker.ietf.org/doc/html/rfc6335#section-6
+    return 49152 + Math.floor(Math.random() * (65535 - 49152));
+}

package/dist/build/configs/production.d.ts

@@ -0,0 +1,4 @@
+import type { InlineConfig } from 'vite';
+import type { BuildArgs } from './shared.js';
+export declare function viteConfigProductionClient(args: BuildArgs): Promise<InlineConfig>;
+export declare function viteConfigProductionServer(args: BuildArgs): Promise<InlineConfig>;

package/dist/build/configs/production.js

@@ -0,0 +1,50 @@
+import { viteExternalsPlugin } from 'vite-plugin-externals';
+import { viteConfigShared } from './shared.js';
+import { excludes } from '../excludes/index.js';
+export async function viteConfigProductionClient(args) {
+    return {
+        ...(await viteConfigShared(args)),
+        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/client/assets',
+                    entryFileNames: `[name].js`,
+                    chunkFileNames: `[name].js`,
+                    assetFileNames: `[name].[ext]`,
+                },
+            },
+        },
+        resolve: {
+            // excludes - map buildConfig.excludes packages to an empty module
+            alias: excludes(args.buildConfig?.excludes),
+        },
+        plugins: [
+            // externals - map buildConfig.externals packages to a global variable on window
+            viteExternalsPlugin(args.buildConfig?.externals, { useWindow: false }),
+        ],
+    };
+}
+export async function viteConfigProductionServer(args) {
+    return {
+        ...(await viteConfigShared(args)),
+        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`,
+                    chunkFileNames: `[name].mjs`,
+                    assetFileNames: `[name].[ext]`,
+                },
+            },
+        },
+    };
+}

package/dist/build/configs/shared.d.ts

@@ -0,0 +1,10 @@
+import type { InlineConfig } from 'vite';
+import type { BuildConfiguration } from '../../schemas/nerest-build.schema.js';
+import type { Project } from '../../server/loaders/project.js';
+export type BuildArgs = {
+    root: string;
+    base: string;
+    buildConfig: BuildConfiguration | undefined;
+    project: Project;
+};
+export declare function viteConfigShared({ root, base, buildConfig, project, }: BuildArgs): Promise<InlineConfig>;

package/dist/build/configs/shared.js

@@ -0,0 +1,24 @@
+export async function viteConfigShared({ root, base, buildConfig, project, }) {
+    // This will be available to client scripts with import.meta.env
+    process.env.NEREST_PROJECT_NAME = project.name;
+    process.env.NEREST_CLIENT_SIDE_EFFECTS = JSON.stringify(buildConfig?.clientSideEffects ?? []);
+    return {
+        root,
+        base,
+        appType: 'custom',
+        envPrefix: 'NEREST_',
+        css: {
+            postcss: {
+                // postcss plugins - import modules mentioned in buildConfig.postcss.plugins
+                plugins: await loadPostcssPlugins(buildConfig?.postcss?.plugins),
+            },
+        },
+    };
+}
+async function loadPostcssPlugins(plugins) {
+    if (!plugins) {
+        return undefined;
+    }
+    const imports = Object.entries(plugins).map(async ([name, options]) => (await import(name)).default(options));
+    return Promise.all(imports);
+}

package/dist/build/configs/vite-logger.development.d.ts

@@ -0,0 +1,2 @@
+declare const logger: import("vite").Logger;
+export default logger;

package/dist/build/configs/vite-logger.development.js

@@ -0,0 +1,25 @@
+// https://vite.dev/config/shared-options.html#customlogger
+import { createLogger } from 'vite';
+const logger = createLogger();
+const loggerError = logger.error;
+logger.error = (msg, options) => {
+    if (typeof msg === 'string' && !isIgnoredError(msg)) {
+        loggerError(msg, options);
+    }
+};
+export default logger;
+// These are errors expected in development that we don't need to log.
+// If the error message includes all markers from a set, it is suppressed
+const ignoredErrors = [
+    // Hook files are optional, but in development vite logs an error even though
+    // we suppress the exception. Silence these logs manually.
+    ['cannot find entry point module', 'props.ts'],
+    ['cannot find entry point module', 'runtime.ts'],
+];
+function isIgnoredError(msg) {
+    for (const markers of ignoredErrors) {
+        if (markers.every((m) => msg.includes(m))) {
+            return true;
+        }
+    }
+}

package/dist/build/index.js

@@ -1,85 +1,55 @@
 import path from 'path';
 import fs from 'fs/promises';
-import { existsSync } from 'fs';
 import { build } from 'vite';
-import { viteExternalsPlugin } from 'vite-plugin-externals';
-import { loadApps } from '../server/parts/apps.js';
-import { excludes } from './excludes/index.js';
+import { loadBuildConfig } from '../server/loaders/build.js';
+import { loadApps } from '../server/loaders/apps.js';
+import { loadProject } from '../server/loaders/project.js';
+import { viteConfigProductionClient, viteConfigProductionServer, } from './configs/production.js';
 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');
-    }
-    const buildConfig = await readBuildConfig(root);
+    const staticPath = prepareStaticPath();
+    // Read build customizations from nerest/build.json
+    const buildConfig = await loadBuildConfig(root);
+    // Read project meta info from package.json
+    const project = await loadProject(root);
     // Build client
-    // TODO: extract shared parts between build/index.ts and server/index.ts
-    // into a shared config
-    const clientConfig = {
+    const clientViteConfig = await viteConfigProductionClient({
         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]`,
-                },
-            },
-        },
-        resolve: {
-            // excludes - map buildConfig.excludes packages to an empty module
-            alias: excludes(buildConfig?.excludes),
-        },
-        plugins: [
-            // externals - map buildConfig.externals packages to a global variable on window
-            viteExternalsPlugin(buildConfig?.externals, { useWindow: false }),
-        ],
-    };
+        base: staticPath,
+        buildConfig,
+        project,
+    });
     console.log('Producing production client build...');
-    await build(clientConfig);
+    await build(clientViteConfig);
+    // Create nerest-manifest.json that production server reads on startup
     console.log('Producing Nerest manifest file...');
-    await buildAppsManifest(root, staticPath);
-    // Build server using the client manifest
-    const serverConfig = {
+    await createNerestManifest(root, staticPath, project);
+    // Build server
+    const serverViteConfig = await viteConfigProductionServer({
         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`,
-                },
-            },
-        },
-    };
+        base: staticPath,
+        buildConfig,
+        project,
+    });
     console.log('Producing production server build...');
-    await build(serverConfig);
+    await build(serverViteConfig);
 }
-async function buildAppsManifest(root, staticPath) {
+async function createNerestManifest(root, staticPath, project) {
     const apps = await loadApps(root, staticPath);
-    await fs.writeFile(path.join(root, 'build/nerest-manifest.json'), JSON.stringify(apps), { encoding: 'utf-8' });
+    await fs.writeFile(path.join(root, 'build/nerest-manifest.json'), JSON.stringify({ project, apps }), 'utf-8');
 }
-// TODO: error handling
-async function readBuildConfig(root) {
-    const configPath = path.join(root, 'nerest-build.json');
-    if (existsSync(configPath)) {
-        const content = await fs.readFile(configPath, { encoding: 'utf-8' });
-        return JSON.parse(content);
+function prepareStaticPath() {
+    let staticPath = process.env.STATIC_PATH;
+    // The path where the client files are deployed is embedded
+    // during the initial build.
+    // TODO: handle error if STATIC_PATH isn't a valid base URL
+    if (!staticPath) {
+        throw new Error('STATIC_PATH environment variable is not set but is required for the production build');
+    }
+    // Static path is a directory URI. To be treated as such by node:url,
+    // it has to end with a trailing slash
+    if (!staticPath.endsWith('/')) {
+        staticPath += '/';
     }
+    return staticPath;
 }

package/dist/client/index.js

@@ -7,8 +7,8 @@ import ReactDOM from 'react-dom/client';
 // if needed.
 const modules = import.meta.glob('/apps/*/index.tsx', { import: 'default' });
 async function runHydration() {
-    for (const container of document.querySelectorAll('div[data-app-name]')) {
-        const appName = container.getAttribute('data-app-name');
+    for (const container of document.querySelectorAll(`div[data-project-name="${import.meta.env.NEREST_PROJECT_NAME}"]`)) {
+        const appName = container.getAttribute(`data-app-name`);
         const appModuleLoader = modules[`/apps/${appName}/index.tsx`];
         if (!appModuleLoader || container.hasAttribute('data-app-hydrated')) {
             continue;
@@ -24,9 +24,16 @@ async function runHydration() {
         ReactDOM.hydrateRoot(container, reactElement);
     }
 }
+// Apps can only be hydrated after DOM is ready, because we need to query
+// apps' containers and their corresponding scripts.
 if (document.readyState !== 'complete') {
     document.addEventListener('DOMContentLoaded', runHydration);
 }
 else {
     runHydration();
 }
+// Entries might be self-initializing (e.g. client-only apps) or have other
+// side effects. In that case we have to load them eagerly, so that their
+// initialization code can run, even if there is nothing to hydrate.
+const clientSideEffects = JSON.parse(import.meta.env.NEREST_CLIENT_SIDE_EFFECTS);
+clientSideEffects?.forEach((name) => modules[`/apps/${name}/index.tsx`]?.());

package/dist/server/development.d.ts

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