@nerest/nerest

React micro frontend framework

TODO: purpose, outline, documentation

Installation

TODO: update package

npm i --save @nerest/nerest react react-dom

Points of Interest

• SSR server entry:
  • Development: server/development.ts
  • Production: server/production.ts
• Hydrating client entry: client/index.ts
• CLI entry: bin/index.ts
• Production build script: build/index.ts

Conventions

The apps directory must contain all of the apps provided by the micro frontend. E.g. /apps/foo/index.tsx is the entrypoint component of the foo app. It becomes available as the /api/foo route of the micro frontend server.

See nerest-harness for the minimal example of a nerest micro frontend.

Examples (/examples/*.json)

The app directory may contain an examples subdirectory with example JSON files which can be used as props for the app entrypoint component. E.g. /apps/foo/examples/example-1.json becomes available as the /api/foo/examples/example-1 route of the micro frontend server.

Schema (/schema.json)

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. 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.

Props Hook (/props.ts)

The app directory may contain a props.ts module that exports a default function. If it exists, this function will be executed on the server for every incoming request, receiving the body of the request and a logger as parameters. You can use this hook to modify and return a new object, which will be passed down to the index.tsx entrypoint component instead. For example:

import type { FastifyBaseLogger } from 'fastify';

export default function (props: Props, logger: FastifyBaseLogger) {
  logger.info('Hello from props.ts!');

  return {
    ...props,
    greeting: `${props.greeting} (modified in props.ts)`,
  };
}

The exported function may be async, in which case nerest will wait for the Promise to resolve, then pass the result object to the entrypoint component.

Configuration

Different aspects of Nerest apps can be configured via environment variables, JSON configuration and runtime hooks written in TypeScript. Examples of all kinds of configuration can be viewed in the nerest-harness 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

Client

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.

Server

Additional environment variables which can be setup for a runtime:

• ENABLE_K8S_PROBES: activates additional routes /livenessProbe and /readinessProbe to check application status

JSON Configuration

You can configure the output of nerest build by placing an optional nerest-build.json configuration file in the root of the micro frontend. The full schema of this file is located in schemas/nerest-build.schema.json.

excludes: string[]

Excludes modules from the client build and replaces their imports with imports of an empty module instead. You can use this to exclude either JS or CSS modules from the final build.

"excludes": ["@scope/name"]

externals: Record<string, string>

Excludes modules from the client build and maps them to globally available constants instead. You can use this to share common dependencies between different micro frontends by exposing them on the window object. For example:

"externals": {
  "react": "window.React",
  "react-dom": "window['ReactDOM']"
}

Here react and react-dom imports will be replaced with accessing the respective window constants.

Runtime Hook

If the module nerest-runtime.ts exists in the root of the micro frontend and exports a default function, this function will be executed when the server starts, and the fastify app instance will be passed to it as its only argument. Example of nerest-runtime.ts:

import type { FastifyInstance } from 'fastify';

export default function (app: FastifyInstance) {
  console.log('Hello from nerest-runtime.ts');
}

This runtime hook can be used to adjust fastify settings, register additional plugins or add custom routes.

Logger Configuration

Nerest uses the default server-side fastify logger, enabled by default. To configure or disable it, export a logger function from the nerest-runtime.ts module. It will be called on server start, and the return value will be passed to fastify as logger configuration.

import type { FastifyServerOptions } from 'fastify';

export function logger(): FastifyServerOptions['logger'] {
  return { prettyPrint: true };
}

To disable the logger, return false from the function.

You can also supply your own logger instance. Instead of passing configuration options, pass the instance. The logger you supply must conform to the Pino interface; that is, it must have the following methods: info, error, debug, fatal, warn, trace, silent, child and a string property level.

Development

Run the build script to build the framework.

npm install
npm run build

Use nerest-harness to test changes locally.