Development Process

This document will teach you how to develop with Frontastic. This includes:

  • Where to put your code
  • How to work with Storybook
  • Testing your code locally and remote
  • How deployments work
  • How you receive updates from Frontastic
  • How you can potentially contribute to Frontastic

Code Areas

Frontastic provides you with dedicated directories for your project code. These directories follow the naming scheme <customer>_<project>/. For example, if your customer ID is demo and the project you are working in is swiss, the according project directory is named demo_swiss/. All your project code SHOULD reside in this directory.

!!! note: Developer Project

There is one exceptional project directory which is named
`<customer>_developer/`. This contains our interactive tutorial and you can
play in it however you like.

There might be another special directory in your code repository which is named only after your customer ID (<customer>/). This directory is meant to contain general source code which is available for all of the projects in your repository. However, this mechanism is not in place yet.

These directories contain your own code. There are small exceptions of files which are generated by Frontastic (clearly mentioned at the top of the file) and some configuration files (e.g. package.json & yarn.lock which require special handling. But besides these your are basically free to do whatever you want in these directories.

Besides these, there are many additional directories under paas/. PAAS means "Platform as a Service" and as such, our plaform code resides there. Especially interesting are the directories paas/catwalk(frontastic-catwalk) and paas/libraries/common (frontastic-common). frontastic-catwalk contains the base application where your code "lives in". It also contains many front-end components which you can use and extend. The frontastic-common package contains our shared libraries, like API abstractions. Feel free to browse these directories and get inspirations, but please DO NOT CHANGE code here. If you still feel you desprately need to change code in a paas/ sub-directory, please consult the Patching Frontastic section at the end of this document.

Each of the mentioned directories contains the same source code directory stucture under src/. In your project directories, you can simply place your source code files there and they will be picked up properly by the system:

  • src/js/ contains all JavaScript code
  • src/scss/ holds the SASS code
  • src/layout/ contain static assets that are required by SCSS or JS
  • src/php/ is the home of all PHP files

Depending on what you want to achieve, you might be working on one or multiple directories. How to kickstart development and how to work in a certain area is explained in the next section.

Your Development Environment

Frontastic attempts to provide you with a unified development experience across all code areas while sticking to community standards as much as possible. Depending on which area of the project code you want to touch there are different ways for approaching the code. We therefore explain the different areas from lowest to deepest integration with the Frontastic stack.

HTML + (S)CSS + (JS)

If you only need to work in HTML, CSS and maybe small bits of JavaScript, you will not need to boot up the Frontastic Virtual Machine (VM) at all as you can work entirely in Storybook. A Storybook configuration is already shipped with Frontastic. All you need is a running Node.js environment and and Yarn. Given that you can open your project directory in a shell and run

$ yarn run storybook

This will startup storybook and you are ready to go.

TODO: Specify pre-conditions (versions), verify this procedure is correct and create paas/docs/development/storybook.md with extensive info on how to develop with Storybook.

If you are not familiar with Storybook, you can refer to more extensive information on TODO: working with Storybook.

Storybook will only guide you to reaching the borders of Frontastic integration. If you need to cross these borders - typically for integrating your code into a Tastic - you need to proceed to the next step.

JS (Tastic Development)

While much work can be done entirely outside of Frontastic, the actual integration with Frontastic requires running "back-end for front-end" in your local development environment. This is realized by booting up the Frontastic Virtual Machine, as described in the README.md at the checkout root directory. If you have not worked with a VM before, we recommend that you read about the Frontastic Virtual Machine.

Once you've got this up and running, your source code is synchronised into the machine and you will be able to call the Developer Landingpage which gives you the URLs to browse your project locally.

TODO

  1. Working in Development

  2. Storybook

  3. Local back-end for front-end (VM)
  4. Build pipeline (Ant)
  5. IDE & integration

  6. Testing (local, staging)

  7. Deployments (build + release)
  8. Patching Frontastic
  9. Contributions