Philosophy

Here we describe some basic concepts to guide us while developing Wasp.

Wasp is specification

We want Wasp to read like specification as much as possible.

This means it should be designed to describe how we think when we are describing how web app should work, instead of us trying to describe it in the way web stack / language / Wasp works.

This also means that we prefer Wasp being declarative over imperative.

Specification over implementation

We want to express as much of the web app through specification as possible.

This means that we prefer having code in Wasp rather than in other languages (js, html, css, ...) that Wasp can't understand.

On the other hand, we also don't want to bloat Wasp too much, so not everything should be in Wasp! This rule/concept is not so easy to figure out, it requires careful balancing.

Don't reinvent the wheel

If there is already a good way to do something, let's use that instead of coming up with our own solution.

This can directly conflict with "Specification over implementation" concept, e.g. we don't want to reinvent how to style web components when there is css and other solutions, we want to use them instead, and while this means we are doing this "outside" of Wasp (that is conflict), that is still ok.

Another example: Instead of reinventing web components, it is probably better to support defining components in React/Vue/... .

Compile time vs run time

When we say compile time, we refer to Wasp, when we say run time, we refer to generated code.

Since we are generating code that looks nice, we also have to think about its maintainability and how it is used in run time! This is not only important for the case when user ejects, but also for the case when user uses generated code in custom code that is being used in Wasp.

For example, take entity-list. Which config options do we put in compile time, and which in run time? If we put them all in run time, we end up building a library -> user would not write such code, with so many redundant options. If we put all of them in compile time (Wasp), then in run time you can't change anything, and you might need to. So, it makes sense to put some of them in compile time, some in run time, and some in both! One trick is to also have compile time option that enables certain option in runtime (makes it available).

If you go back to "Wasp is specification", it starts making sense: if dev is thinking "I need a list that can be toggled as editable or not", then we want to have compile time option "conditionallyEditable" which when set on true will generate component that has prop "editable" which can be set to true or false. If not, component will never have that prop nor code needed to support it. On the other and, if we have "editable" option in compile time set to true, generated component would have code for editing, but will not have prop for toggling it.

TODO: Expand and simplify this document.