@docupace/ihub-config

Reusable GraphQL config extension and standalone server extracted from the Docupace GraphQL server.

Run locally

pnpm install

To run the package as a standalone GraphQL server, copy .env.example to .env, fill in the required values, and start the dev server:

cp .env.example .env
pnpm start:dev

The standalone server listens on http://localhost:4000/api/graphql.

Use as an extension in another server

import { getConfigExtension } from '@docupace/ihub-config';

Then add the returned extension to the host server's extensions array:

const configExtension = await getConfigExtension();

const serverInfo: ServerConfig = {
  instanceConfig: instanceConfig,
  extensions: [docupaceExtension, configExtension],
  port: 4000,
  createContext,
};

Extend the config extension with domain-specific providers, resolvers, etc.

import { getConfigExtension } from '@docupace/ihub-config';
import {
  DashboardPageConfigProvider,
  TablePageConfigProvider,
  AnyPageConfigProvider,
  DetailsPageConfigProvider,
} from './your-host-config-providers.js';
import { configResolvers } from './your-host-config-resolvers.js';

const APPLICATION_PREFERENCE_PREFIX = 'applicationPreference';

const applicationPreferenceResolver = async (keys, context) => {
  const data = await loadApplicationPreferences(keys, context);

  const result: Record<string, string | undefined> = {};
  keys.forEach((key) => (result[key] = undefined));
  data.records.forEach((record: { name: string; value: string }) => {
    result[record.name] = record.value;
  });

  return result;
};

const configExtension = await getConfigExtension({
  configInjectorResolvers: {
    [APPLICATION_PREFERENCE_PREFIX]: applicationPreferenceResolver,
  },
  providers: {
    DashboardPage: DashboardPageConfigProvider,
    TablePage: TablePageConfigProvider,
    AnyPage: AnyPageConfigProvider,
    DetailsPage: DetailsPageConfigProvider,
  },
  resolvers: configResolvers,
});

configInjectorResolvers

Use configInjectorResolvers to resolve template expressions embedded in config values, for example:

$${applicationPreference:timezone}

Each key in configInjectorResolvers is a template prefix, and each value is an async resolver function with this shape:

type ResolverFunction = (
  keys: string[],
  context: any,
) => Promise<Record<string, any>>;

When config processing encounters $${prefix:key}, it looks up the resolver for that prefix, batches the requested keys, and replaces the template with the resolved value. This is the right place to connect host-specific data sources such as application preferences, tenant settings, or user-scoped values.

providers

Use providers to register config processors by __typename. A provider runs after nested config values have been loaded and template expressions have been resolved, and can reshape or enrich the final config object before it is returned.

providers: {
  DashboardPage: DashboardPageConfigProvider,
  TablePage: TablePageConfigProvider,
  AnyPage: AnyPageConfigProvider,
  DetailsPage: DetailsPageConfigProvider,
}

Each provider must be a class with a processConfig method:

interface ConfigProvider {
  processConfig(config: any, configService: ConfigService, context: any): any;
}

This is useful for page-specific post-processing such as normalizing fragments, rewriting references, or deriving extra fields for a particular page type. Built-in providers are preserved and host providers are merged in on top.

resolvers

Use resolvers to extend the GraphQL API exposed by the config extension. Resolvers are provided as factories so they can receive the initialized configService instance:

const configResolvers = {
  query: ({ configService }) => ({
    pages: () => ({
      myCustomPage: async (obj: { path: string }, context: any) => {
        return await configService.getDirectConfig(obj.path, context);
      },
    }),
  }),
  mutation: ({ configService }) => ({
    pages: () => ({
      refreshCustomConfig: async () => {
        await configService.init();
        return true;
      },
    }),
  }),
};

Host query and mutation resolvers are deep-merged with the built-in config resolvers, so you can add new fields without re-declaring the entire resolver tree. If the same field exists in both places, the host resolver wins.

If you want to pass config stores programmatically instead of through environment variables, getConfigExtension also accepts configStores (usually used for tests only).

Environment variables

Config stores are discovered from environment variables grouped by prefix such as STANDARD or SITE:

• <PREFIX>_CONFIG_LOCAL_PATH
• <PREFIX>_CONFIG_REMOTE_PATH
• <PREFIX>_CONFIG_REMOTE_BRANCH
• <PREFIX>_CONFIG_PRIORITY
• <PREFIX>_CONFIG_NAME

<PREFIX>_CONFIG_PRIORITY is required for every configured store.

CONFIG_LOCAL_PATH_ROOT can be used as a fallback base path when <PREFIX>_CONFIG_LOCAL_PATH is omitted, but the store still needs enough configuration to be discovered.