Extensions

Extensions is a grouping for static (i.e., not event-driven) API. extensions accepts plugins as keys in a JavaScript object. extensions are initialized with a set of default features.

Manipulating extensions

To get currently mounted extensions, API provides method getExtensions which returns an immutable object which contains extensions as properties of an object. Being an immutable object, there is no direct way to modify it. If a component or application need to add an extension, the API provides method setExtension, which takes the scoping key of the new extension and its content.

// Application 1 ⤵
microlcApi.setExtension({ getUserName: () => 'John Doe' })

// Application 2 ⤵
const userNameGetter = microlcApi.getExtensions().getUserName
console.log(userNameGetter())
// output: "John Doe"

getExtensions

export interface MicrolcApi<T extends BaseExtension> {
  readonly getExtensions: () => Readonly<Partial<T>>
  // ...rest of the API
}

setExtension

export interface MicrolcApi<T extends BaseExtension> {
  readonly setExtension: (key: keyof T, value: T[keyof T]) => Readonly<T>
  // ...rest of the API
}

Base extension

type BaseExtension = Record<string, unknown> & {
  css: { /*...*/ }
  head: { /*...*/ }
  json: { /*...*/ }
  language: { /*...*/ }
}

css.setStyle

export type BaseExtension = Record<string, unknown> & {
  css: {
    setStyle: (styles: CSSConfig) => void
  }
}

interface CSSConfig {
  global?: Record<string, string | number>
  nodes?: Record<string, Record<string, string | number>>
}

head.setIcon can be used to inject styling in micro-lc applications.

head.setIcon

export type BaseExtension = Record<string, unknown> & {
  head: {
    setIcon: (attrs: Partial<Pick<HTMLLinkElement, 'sizes' | 'href' | 'type'>>) => void
  }
}

head.setIcon can be used to set a link tag for favicon relation.

caution

Be aware that any application with integration mode parcel can override this setting.

head.setTitle

export type BaseExtension = Record<string, unknown> & {
  head: {
    setTitle: (title: string) => void
  }
}

head.setTitle can be used to set a title tag.

caution

Be aware that any application with integration mode parcel can override this setting.

json.fetcher

export type BaseExtension = Record<string, unknown> & {
  json: {
    fetcher: (url: string, init?: RequestInit) => Promise<unknown>
  }
}

json.fetcher can be used to download a JSON or YAML resource. It performs a GET request including an Accept header with the following value:

Accept: application/json,text/x-json,application/yaml,application/x-yaml,text/yaml

The response is interpreted according to Content-Type header vale and then parsed as a JSON or a YAML accordingly.

caution

Be aware that YAML parsing requires an extra ~38 KB of dynamic import to be added to the total bundle size.

and an Accept-Language header matching either the browser current language or any language that has been set via micro-lc API using the setLanguage method. When the required language is expressed ad aa-AA, an extra generic language is added with a quality factor. On en-US the header would be

Accept-Language: en-US, en;q=0.5

This header can be leveraged in server content negotiation.

The RequestInit type is the standard fetch option type where Accept and Accept-Language headers cannot be overridden.

json.validator

export type BaseExtension = Record<string, unknown> & {
  json: {
    validator: <S>(json: unknown, schema: SchemaOptions, opts?: JsonCatcherOptions<S>) => Promise<S>
  }
}

type SchemaOptions = Ajv.SchemaObject | {
  id: string
  parts: Ajv.SchemaObject[]
}

interface JsonCatcherOptions<S> {
  defaultValue?: S
  file?: string
}

caution

This method works only in development mode. In production mode, simply proxies of the provided JSON.

json.validator can be used to validate a JSON value against a schema using Ajv.

In case validation goes wrong, the return value would be the input object itself or, if you like to override it, the default value provided in opts.defaultValue. To better understand validation errors, messages can be scoped with opts.file.

language.getLanguage

export type BaseExtension = Record<string, unknown> & {
  language: {
    getLanguage: () => string
  }
}

language.getLanguage can be used to retrieve current application language according to rfc5646 specification.

language.setLanguage

export type BaseExtension = Record<string, unknown> & {
  language: {
    setLanguage: (lang: string) => void
  }
}

language.setLanguage can be used to set current application language to a valid rfc5646 specification tag.

caution

Be aware that, given the static nature of micro-lc APi extensions, language.setLanguage can be used to dynamically change language, but it will trigger a full micro-lc config reload and update. This feature is required to properly re-negotiate a translated configuration file.

Refer to reactive communication section for event-driven alternatives, but keep in mind that micro-lc will use language extension to perform any language-related operation.