Available options

miyagi works without setting any configuration by analyzing your files and guessing the correct template engine and template files extension. If this does not work or you want to customize it further, miyagi offers many configuration options.

`assets`

Settings for assets that miyagi serves (independently from your components).

`root`

default: ""
type: string|object

This setting can be helpful if assets are located in another folder, e.g. public/assets, but they should actually be served from assets/. In that case you could set this option to public.

It is also possible to define this for each NODE_ENV via an object like this:

{
  "development": "some/folder",
  "production": ""
}

`css`

default: null
type: object

Can either be a string, an array of strings or an object with your NODE_ENVs as key and a string or array as values:

{
  "development": ["src/reset.css", "src/theme.css"],
  "production": ["dist/index.css"]
}

This would serve different assets based on your NODE_ENV.

`customProperties`

default:

{
  "files": [],
  "prefixes": {
    "color": "color",
    "typo": "typo",
    "spacing": "spacing"
  }
}

type: object

This object is used to generate your automated styleguide.

More information about automated styleguides.

`folder`

default: null
type: string|array|object

If you need miyagi to serve static assets (like images, SVGs, etc.), you can define one or multiple folders here.

Can either be a string, an array of strings or an object with your NODE_ENVs as key and a string or array as values:

{
  "development": ["svgs", "templates"],
  "production": ["templates"]
}

This would serve different assets based on your NODE_ENV.

`js`

default: null
type: string|array|object

This would be the most complex way to define this option:

{
  "development": [
    {
      "src": "src/index.js",
      "defer": false,
      "async": false,
      "type": null,
      "position": "head"
    }
  ],
  "production": [{ … }]
}

This would serve different assets based on your NODE_ENV ("development" or "production" in this case). It can be simplified to by omitting the node envs, not using an array or simply using a string (for the source file).

Please also refer to How to: Adding JS files.

`manifest`

default: null
type: string

If you create CSS and JS files with hashes and have therefore a manifest file, you can set this here and then use the same keys of the manifest file for your CSS and JS files in assets.css and assets.js. miyagi will then resolve these.

`build`

Settings for creating a static build.

`basePath`

default: /
type: string

If you deploy your build into a subfolder instead of the root folder, set this option to the path of the subfolder.

`folder`

default: "build/"
type: string

The folder where your build files will be saved. Use --folder when using as a cli argument.

`outputFile`

default: false
type: boolean

Defines if an output.json file (containing all paths to the standalone views of a component) should be created.

`components`

`folder`

default: "src"
type: string

The folder where your components live.

`ignores`

default: ["node_modules", ".git", "package.json", "package-lock.json", ".miyagi.js"]
type: array

miyagi ignores these folders and files when looking for your components.

When setting a value, it is added to the default value and does not overwrite it.

`lang`

default: "en"
type: string

Used to determine the language of components. This will set the value for the lang attribute.

`renderInIframe`

default: { default: false, except: [] }
type: object

Determines if variants on the component view should be rendered in an iframe or not. Rendering in iframe makes sense when for example the component depends on media queries or has elements which are positioned fixed. If you have small components with a box-shadow for example, you might not want to render them inside an iframe, since the box-shadow would be cut off. Please also note that extensive usage of iframes slows down the page. So if you have a lot of variants, it might be better to not render the variants in iframes.

except accepts globs. Its meaning depends on the value of default. So, if by default variants are rendered in an iframe, components that match one of the globs from the except array, are not rendered in an iframe. If default is false, these components are rendered in an iframe.

Note: After the load and DOMContentLoaded events of the iframes have been fired, their height is set to the height of the variant inside the iframe if it is smaller than the window. That way it is basically not noticable that the variant is rendered inside an iframe. In case that the variant is higher than the window, the iframe will have the same height as the window and be scrollable. After the load event the height will not be updated anymore when the height of the variant changes. This is necessary to avoid resize loops.

`textDirection`

default: "ltr"
type: string

Used to determine the value of the dir attribute on the <html> element.

Note: This only applies the text direction of the components, not if miyagi itself

engine

instance

default null

See Extending template engine

name

default: null
type: string
required: true

The name of your template engine (see supported template engines)

options

default: null
type: object

These options are passed to the rendering function of your template engine. You can use that for setting a custom namespace e.g..

`files`

This is the configuration for your actual component files.

Each entry accepts an object with the following keys:

extension: the file extension in your components folder (type: string)
name: the name of the file in your components folder (type: string)

`css`

default:

{
  "extension": "css",
  "name": "index"
}

Note: You can use "<component>" for name if the file should have the same name as the component folder.

`docs`

default:

{
  "extension": "md",
  "name": "index"
}

`info`

default:

{
  "extension": "json",
  "name": "info"
}

`js`

default:

{
  "extension": "js",
  "name": "index"
}

Note: You can use "<component>" for name if the file should have the same name as the component folder.

`mocks`

default:

{
  "extension": "json",
  "name": "mocks"
}

`schema`

default:

{
  "extension": "json",
  "name": "schema"
}

`templates`

default:

{
  "name": "index",
  "extension": null
}

Note: You can use "<component>" for name if the file should have the same name as the component folder.

`extensions`

default: []
type: array

`projectName`

default: "miyagi"
type: string

`ui`

Settings for the web UI.

`reload`

default: true
type: boolean

Defines if your component automatically reloads after saving.

`reloadAfterChanges`

`componentAssets`

default: false
type: boolean

Defines if your component automatically reloads after the css or js file of your component has been updated.

NOTE: This is disabled by default for the case that you have a build process that bundles your components assets. These bundled files could be added to your configuration in the assets key.

`textDirection`

default: "ltr"
type: string

Defines the text direction (dir attribute on the html tag) of the miyagi UI.

NOTE: This does not set the text direction for the components. If you want to change that as well, please have a look at components.textDirection.

`theme`

default:

{
  "favicon": null, // path to a favicon
  "logo": null, // path to a logo — can be used if the same logo should be used for light and dark mode
  "mode": "light", // "light", "dark" or "auto" (means it uses the OS setting)
  "fontFamily": "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif",
  "light": {
    // theming for light mode
    "logo": null, // path to a logo
    "navigation": {
      "colorText": "hsl(0, 0%, 12%)",
      "colorBackground": "hsl(0, 0%, 86%)",
      "colorLinks": "hsl(0, 0%, 12%)",
      "colorLinksActive": "hsl(0, 0%, 96%)",
      "colorLinksActiveBackground": "hsl(0, 0%, 12%)",
      "colorSearchText": "hsl(0, 0%, 12%)",
      "colorSearchBackground": "rgba(0, 0, 0, 0.05)",
      "colorSearchBorder": "rgba(0, 0, 0, 0.25)"
    },
    "content": {
      "colorBackground": "hsl(0, 0%, 100%)",
      "colorText": "hsl(0, 0%, 12%)",
      "colorHeadline1": "hsl(0, 0%, 12%)",
      "colorHeadline2": "hsl(0, 0%, 12%)"
    }
  },
  "dark": {
    // theming for light mode
    "logo": null, // path to a logo
    "navigation": {
      "colorText": "hsl(0, 0%, 100%)",
      "colorBackground": "hsl(0, 0%, 16%)",
      "colorLinks": "hsl(0, 0%, 100%)",
      "colorLinksActive": "hsl(0, 0%, 16%)",
      "colorLinksActiveBackground": "hsl(0, 0%, 100%)",
      "colorSearchText": "hsl(0, 0%, 100%)",
      "colorSearchBackground": "rgba(255, 255, 255, 0.1)",
      "colorSearchBorder": "rgba(255, 255, 255, 0.25)"
    },
    "content": {
      "colorBackground": "hsl(0, 0%, 16%)",
      "colorText": "hsl(0, 0%, 100%)",
      "colorHeadline1": "hsl(0, 0%, 100%)",
      "colorHeadline2": "hsl(0, 0%, 100%)"
    }
  },
  "css": null, // string of CSS which gets added to miyagi and components. can be used to changed the styling of miyagi or e.g. add custom fonts defined in `fontFamily`,
  "js": null // string of JS which gets added to components
}

`validations`

Read more about validations in the Web UI section.

`accessibility`

default: true
type: boolean

`html`

default: true
type: boolean

`schema`

default: {}
type: object

This object gets passed to the instance of the schema validator AJV. See all available options. You can use this to define custom formats e.g..