# Development

# Technology Stack

This project was bootstrapped with Create React App (Typescript preset).

# Prerequisites

Required:

  • Node.js 10+

Recommended:

# Installation

Notice: You may also use npm instead of yarn.

  1. Install all dependencies:
yarn install
  1. Start app:
yarn start
  1. Open http://localhost:42007 to view the app in the browser.

# Available tasks

The package.json file contains other useful scripts, which you can execute using yarn <command> or npm run <command>:

Command Description
build Builds the app for production to the build folder.
format Reformat all files with prettier.
generate Generate boilerplate code (components, widgets).
lint:fix Run ESLint, apply automatic fixes if possible.
storybook:start Start Storybook
test Run tests and check test coverage.

The master branch is (manually) deployed to dashboard.darekkay.com.

# Creating a new widget

  1. Run the file generator (yarn generate Widget).
  2. Adjust the widget's properties.ts file with sane initial values.
  3. Optionally, you may create a configuration.tsx file to enable a configuration modal for the new widget.
  4. Re-scan the available widgets (yarn scan-widgets).
  5. Add mandatory widget labels (at least name) to all translation files under common/translations.
  6. Edit documentation under docs/widgets.

# Storybook

This project uses Storybook, a tool for developing UI components in isolation. It is automatically deployed here on every push to production. Every widget and every common component should provide a story in a __stories__ sub-folder.

The Storybook instance also includes some static assets for offline usage, so widgets can be tested or demonstrated locally without internet access.

  • Website/Search example: http://localhost:6006/web.html
  • Image example: http://localhost:6006/cow.jpg

# Internationalization

The react-i18next library handles internationalization. Translations are located under src/common/translations, one file per language. Currently, English (en.json) and German (de.json) translations are available.

The label keys can be viewed in a debug mode by adding debug:labels to the URL, e.g. https://dashboard.darekkay.com/?debug:labels.

Default UI language is based on the browser language and can be changed by the user in the settings dialog.

# Typography

Use CSS utility classes text-1 to text-7 to adjust font sizes. To preserve a consistent look across all widgets, use text-3 as the base size.

# Browser support

All current browsers are supported (Chrome, Firefox, Safari, Edge). IE11 is not supported, mostly due to the usage of CSS Custom Properties. I've tried using a polyfill, but the results weren't great.

# Commit message format

  • Use imperative form (e.g. "Fix" instead of "Fixed" or "Fixes").

# Changelog format

The changelog uses emojis to categorize changes. View the emoji format here.

# Code of Conduct

This project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.