How it is built

The Frontend-Kit is built with a framework agnostic approach in mind. That means it is built without the usage of a framework.
To define a component we use a collection of files, from which we compile the component.

Files

To define a component the following files are needed:

  • <component>.tsx
  • <component>.scss
  • <component>.json
  • <component>.ts optional

TypeScript XML file

The .tsx file is needed to define the resulting markup of a component. It also gives us the possibility to define variations of a component without to rewrite the whole component.

Inside the .tsx files we use plain React and write the components as simple functional components. We can use them later to pipe them through the ReactDOM method renderToStaticMarkup. This method is usual used in server side rendering contexts.
We use this method to generate for each variant config the markup from the functional component.

SCSS file

The .scss file defines the component styling.

JSON file

To generate variations of a component we need to define some kind of data, therefor we use the .jsonfile. The file needs to contain at least the following key:

  • name

All other keys are optional and are only needed if they are used by the .hbsfile.

TypeScript file

The .ts file defines the inner logic of the component. The file is optional, because there might be components which don´t needed any logic built with JavaScript.

In depth

Schema of how we generate new components and sites.

Step 1 - generate files
  • .tsx (template)
  • .scss (styling)
  • .json (configuration data)
  • .ts (components logic)
Step 2 - compile templates
compile via compileTemplates.ts
Step 3.1 - build guide sites
built with gatsby.js from src/pages/pages/*
Step 3.2 - build preview sites
built with gatsby.js from src/pages/preview/*
Step 3.3 - build overview sites
built with gatsby.js from src/pages/overview/*

Building the components

The first step is to generate the components from the given files. Therefor we use the buildComponents.js file. At first we bundle our script files with Parcel Bundler. We declared also two different bundle steps. One for the script files which got the target node and one for the Frontend-Kit.js which got the target browser.

The bundling is needed, because the scripts are all written in TypeScript.

After bundling, the script compileTemplates.ts will be executed. The script will read all components inside src/frontend-kit and writting markdown files for each component.

There will three types of markdown files be generated:

  • markdown files for the guide for each component, which contain each variant of the component
  • markdown files for each variant of each component, which contain only the markup of the component
  • markdown files for an configurable overview page which contains some selected variants of a certain component

Building the guide sites

The guide sites will be generated by Gatsby.js. Therefor we specify the template which should be used for markdown files of type guide.

Building the preview sites

The preview sites will be generated by Gatsby.js. Therefor we specify the template which should be used for markdown files of type preview.

Building the overview sites

The overview sites will be generated by Gatsby.js. Therefor we specify the template which should be used for markdown files of type overview.

Building the documentation sites

The documentation sites will be generated by Gatsby.js. Therefor we specify the template which should be use for markdown files of type documentation.

Folder structure

root
│
└───src
│   │   file011.txt
│   │   file012.txt
│   │
│   └───subfolder1
│       │   file111.txt
│       │   file112.txt
│       │   ...
│
└───scripts
│   │   This folder contains the Typescript files Gatsby uses to read the files we wrote and write the preview and guide files out of them.
│
└───static
│   │
│
└───public
│   │   file021.txt
│   │   file022.txt
│
└───dist
│   │   file021.txt
│   │   file022.txt
│
└───documentation
│   │   file021.txt
│   │   file022.txt

Development mode

During development mode we run on two terminals the following commands:

  • yarn run develop:components
  • yarn run develop:gatsby

The first will restart the development server (through nodemon) upon file changes and the second will start it.

Build mode

During build the server runs the following commands:

  • yarn
  • yarn run build:gatsby
  • yarn run build:components

The first will build the components and from that the second will build the pages.