1fe Server Reference

1fe Server Reference

The 1fe/server package exposes a function oneFEServer that returns an express server instance. This reference page will list the configuration options available.

Simple Usage Example

import oneFEServer from "@devhub/1fe-server";

const app = oneFEServer({
  mode: "production",
  environment: "production",
  orgName: "My Organization",
  configManagement: {
    url: "https://my-cdn.net/production/live-configuration.json",
    refreshMs: 30 * 1000,
  },
  shellBundleUrl: "https://my-cdn.net/production/shell.js",
});

app.listen(3001, () => {
  console.log(`Server listening at http://localhost:3001`);
});

mode

Type: 'development' | 'preproduction' | 'production'

What type of environment is this? The 1fe runtime will use this information to determine certain behaviors, such as loading certain development tooling within the shell.

environment

Type: string

What is the name of your environment? This is used for certain capabilities such as fetching a widget’s runtime configurations.

orgName

Type: string

The name of your organization. This will be used as the default page title and for the X-Powered-By header.

configManagement

Type

type EcosystemConfigs<T> = { url: string } | { get: () => Promise<T> };

type OneFEConfigManagement = {
  widgetVersions: EcosystemConfigs<WidgetVersion[]>;
  libraryVersions: EcosystemConfigs<LibraryVersions>;
  dynamicConfigs: EcosystemConfigs<OneFEDynamicConfigs>;
  refreshMs?: number;
};

The configManagement object defines how 1fe fetches and manages the three core live configurations that power the platform’s dynamic capabilities.

Configuration Options

• widgetVersions: Controls which widget bundle versions are live in each environment

  • url: URL endpoint that returns widget version mappings
  • get: Custom function that returns a Promise resolving to widget versions

• libraryVersions: Manages externalized library versions provided by the shell

  • url: URL endpoint that returns library version mappings
  • get: Custom function that returns a Promise resolving to library versions

• dynamicConfigs: Provides widget/plugin runtime behaviors, build-time configurations, and common settings

  • url: URL endpoint that returns dynamic configuration object
  • get: Custom function that returns a Promise resolving to dynamic configs

• refreshMs (optional): The interval in milliseconds to refresh all live configurations. Defaults to 30 seconds.

Configuration Examples

URL-based Configuration (Recommended for production):

export const configManagement: OneFEConfigManagement = {
  widgetVersions: {
    url: `https://cdn.example.com/${ENVIRONMENT}/configs/widget-versions.json`,
  },
  libraryVersions: {
    url: `https://cdn.example.com/${ENVIRONMENT}/configs/lib-versions.json`,
  },
  dynamicConfigs: {
    url: `https://cdn.example.com/${ENVIRONMENT}/configs/live.json`,
  },
  refreshMs: 30 * 1000, // 30 seconds
};

Function-based Configuration (Useful for database integration):

export const configManagement: OneFEConfigManagement = {
  widgetVersions: {
    get: async () => {
      // Custom logic to fetch from database, Azure App Config, etc.
      return await getWidgetVersionsFromDatabase();
    },
  },
  libraryVersions: {
    url: `https://cdn.example.com/${ENVIRONMENT}/configs/lib-versions.json`,
  },
  dynamicConfigs: {
    url: `https://cdn.example.com/${ENVIRONMENT}/configs/live.json`,
  },
  refreshMs: 30 * 1000,
};

See Live Configurations for detailed information about what each configuration contains and how they work together.

shellBundleUrl

Type: string

The URL to fetch the shell bundle from. This should be a URL to the bundle that consumes 1fe/shell.

server

Type

type OneFEServer = {
  playground?: boolean;
  knownRoutes: string[];
};

• playground (optional): Whether or not to enable the playground. Defaults to false.
• knownRoutes: An array of known routes that 1fe/server will use for plugin and 404 detection.

csp (optional)

Type

type CSPPerEnvironment = {
  scriptSrc?: string[];
  connectSrc?: string[];
  imgSrc?: string[];
  objectSrc?: string[];
  frameSrc?: string[];
  styleSrc?: string[];
  frameAncestors?: string[];
  mediaSrc?: string[];
  workerSrc?: string[];
  formAction?: string[];
  fontSrc?: string[];
};

type OneFECSP = {
  defaultCSP: {
    enforced?: CSPPerEnvironment;
    reportOnly?: CSPPerEnvironment;
  };
};

• csp.defaultCSP.enforced (optional): Content-Security-Policy to enforce in runtime.
• csp.defaultCSP.reportOnly (optional): report-only Content-Security-Policy.