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
Frontastic provides you with dedicated directories for your project code.
These directories follow the naming scheme
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.
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
means "Platform as a Service" and as such, our plaform code resides there.
Especially interesting are the directories
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
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
sub-directory, please consult the Patching Frontastic section at the end of
Each of the mentioned directories contains the same source code directory
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/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)
$ yarn run storybook
This will startup storybook and you are ready to go.
TODO: Specify pre-conditions (versions), verify this procedure is correct and
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.
Working in Development
- Local back-end for front-end (VM)
- Build pipeline (Ant)
IDE & integration
Testing (local, staging)
- Deployments (build + release)
- Patching Frontastic