Design Principles

This document contains some guidelines used by maintainers and contributors to take some decissions regarding framework development

Where to place React components and tools?

There are two different places to place our components and tools:

The main frontity package

Like <Head>, <Global>, connect, decode, error, styled...
The specific packages like @frontity/component and @frontity/hooks:

Like <Image>, <Iframe>, <Switch>.

The guidelines to know which component or tool should go to which place are:

Using components and tools in the main package are mandatory

What this means is that Frontity devs should not use an external tool instead of this components/tools. If they do so, Frontity may not work as expected.
Components and tools in the specific packages are our recommended, but no required

What this means is these components/tools are nice things we release to make their life easier, but they are not required for the framework and alternative components/tools can be used in their place.

Some examples:

Devs should not use the <Helmet> component of react-helmet instead of <Head>.
Devs should not use their own state manager instead of connect.
Devs should not use their own CSS solution instead of our styled, css and <Global>.
Devs should use our fetch tool instead of importing axios or superagent to make sure different package don't add redundant libraries for the same purpose increasing the final bundle size unnecessarily. Apart from that, our fetch works both in the client and in the server.
Devs should use our error tool because it will output normalized messages that will get removed in production reducing the final bundle size.
Devs should use our decode tool because it is optimized for both the server and the client and importing a library like he will increase the bundle size unnecessarily.
Devs can choose to use our <Image> or <Iframe> components because they add lazy load and it's important for the performance, but they can create their own components if they prefer.
Devs can choose to use our <Switch> component because it makes routing easier, but they can create their own components if they prefer.
Devs can choose to use our useInView because it's a nice hook, but they can create their own hook if they prefer. Actually, this is now deprecated in favor of react-intersection-observer.