search

wearewarhol / config-file

Configuration File Reader for Warhol
MIT License
1 stars 0 forks source link

readme

Config parser

This module validates project configuration objects or JSON strings and turns valid partial configuration objects into full configurations with sensible defaults. The file schema is specified in warhol.schema.json. An example:

{
  "patternLibUrl": "https://foo.com/components",
  "patternLibHeaders": {
    "DNT": "1"
  },
  "patternLibCookies": [{
    "name": "Hello",
    "value": "42",
    "expires": 9000,
    "domain": "foo.com",
    "sameSite": "Lax"
  }],
  "breakpoints": [
    1280, 1024, 800, 400, 280
  ],
  "theme": {
    "colors": {
      "colorsUrl": "https://foo.com/components/theme/colors",
      "sources": ".swatch",
      "properties": [ "background-color", "color" ]
    },
    "typography": {
      "typographyUrl": "https://foo.com/components/theme/typography",
      "sources": ".typo",
      "properties": [ "font-family", "font-size", "font-weight", "font-style" ]
    },
    "icons": {
      "iconsUrl": "https://foo.com/components/theme/icons",
      "sources": ".icon",
      "type": "font"
    }
  },
  "utils": {
    "iconsUrl": "https://foo.com/components/theme/utils",
    "sources": [
      { "type": "rule", "selector": ".align-left" },
      { "type": "rule", "selector": ".align-right" },
      { "type": "element", "selector": ".shadow", "components": [ ".foo", ".notEqualToSource" ] }
    ]
  },
  "components": [
    { "source": ".foo" },
    { "source": ".bar", "target": ".notEqualToSource" },
    { "source": ".baz", "url": "https://foo.com/components/baz" }
  ]
}

Notable revisions

Schema

Field patternLibUrl (optional, string or null, defaults to null)

URL for the pattern library's main page ("kitchen sink"), if any. Can be overruled for each component and theme configuration with their own URLs. If the pattern library URL is not specified, components and themes (or sub-sections of themes) must provide their own URLs.

Field patternLibUrlHeaders (optional, Record<string, string> or null, defaults to {})

Header to set when accessing the pattern library.

Field patternLibUrlCookies (optional, Cookie or null, defaults to [])

Cookies to set when accessing the pattern library. Cookie object type:

type Cookie = {
  name: string;
  value: string;
  path?: string;
  url?: string;
  domain?: string;
  expires?: number;
  httpOnly?: boolean;
  secure?: boolean;
  sameSite?: "Lax" | "Strict";
};

Note that the JSON schema requires the number in expires to be an integer and that it also requires either url or domain to be defined, even though both are optional properties on the resulting output type.

Field breakpoints (optional, number[] or null, defaults to [ 1000 ])

Breakpoints for the pattern library (and the production page that implements the pattern lib), controls the screen widths at which snapshots for the components are taken.

Field components (optional, ComponentDefinition[] or null, defaults to [])

List of component definitions. A component definition is an object with the following fields:

Field theme (optional, object or null, defaults to null)

Theme configuration for colors, typography and such.

Field theme.url (optional, string or null, defaults to the pattern lib URL)

Theme URL, can be overruled by the URLs specified in the theme's sub-properties.

Field theme.colors (optional, object or null, defaults to null)

Configuration for theme colors with the following fields:

The colorsUrl field is required if neither a pattern lib URL nor a theme url have been specified.

Field theme.typography (optional, object or null, defaults to null)

Configuration for theme typography with the following fields:

The typographyUrl field is required if neither a pattern lib URL nor a theme url have been specified.

Field theme.icons (optional, object or null, defaults to null)

Configuration for theme icons with the following fields:

The iconsUrl field is required if neither a pattern lib URL nor a theme url have been specified.

Field utils (optional, object or null, defaults to null)

Definitions for style utilities (classes for alignment, layout, shadows and the like).

Field utils.utilsUrl (optional, string or null, defaults to the pattern lib URL)

Utils URL, is only required if there is no top-level patternLibUrl.

Field utils.sources (required, array of objects)

Sources for utilities. Each utility is described by an object:

Field utils.components (optional, array of strings)

List of components (specified by their target selector) that this utility can apply to. Each selector must match a component's target selector (or its source selector if the component in question has no target selector).

JavaScript API

function fromObject = (input: PartialConfiguration) => Configuration

Validates a configuration object against the schema described above and fills in the default values. Throws a InvalidConfigError if the object does not conform to the schema. The error's message property contains a JSON-encoded representation of the validation error thanks to better-ajv-errors. An example:

[
  {
    "start": {
      "line": 1,
      "column": 82,
      "offset": 81
    },
    "end": {
      "line": 1,
      "column": 86,
      "offset": 85
    },
    "error": "/components/1/source: type should be string",
    "path": "/components/1/source"
  }
]

function fromJSON = (input: string) => Configuration

Parses a JSON string into an object, validates the object against the schema described above and fills in the default values. Throws a MalformedConfigError if the input is not valid JSON. Throws a InvalidConfigError like fromObject() if the object does not conform to the schema.

Exported types

Errors