Portalicious Guidelines

All of the below are merely guidelines. If you are in doubt about something, ask :)

File & folder structure

This is our desired file & folder structure:

app
├── components
│   └── component-name
│       ├── component-name.component.html
│       ├── component-name.component.spec.ts
│       └── component-name.component.ts
├── directives
│   ├── directive-name.directive.spec.ts
│   └── directive-name.directive.ts
├── models
│   ├── model-name.api.model.ts
│   └── model-name.model.ts
├── pages/
│   └── page-name/
│       ├── components/
|       |   └── page-specific-component/
|       |       ├── ...
│       ├── page-name.component.html
│       └── page-name.component.ts
└── services
    ├── service-name.service.spec.ts
    └── service-name.service.ts

• No new top-level (ie. direct descendants of app) folders should be added.
• Domain-specific folders should be inside app/pages
• The models folder should only contain the representation of entities that come from the backend
• A domain-specific folder (such as app/pages/payment) or a top-level component folder (such as app/components/data-table) can replicate app's top-level folder structure. For example, we could have a components and directives folder within app/pages/payments.

When creating a new component/enum/directive, where do I put it?

By default, create it close to where it would be used. (ie. create a component that is specific to payments within the payments domain).

Only move it to the equivalent top-level folder when

• It will inevitably be used by more than one domain (eg. a design atom like Button)
• It becomes used by more than one domain

Components

Creating components

Items with the 🤖 emoji happen automatically when using ng generate component.

• Delete auto-generated spec files unless they are meaningful
• 🤖 All components must be standalone
• 🤖 All components must use the "OnPush" change detection strategy, to support zoneless change detection
• 🤖 Do not create a (S)CSS file per component

General component guidelines

• Keep custom components/CSS to a minimum.
  • Use PrimeNG components whenever possible
    • A design might contain something that, with a few tweaks, could use a PrimeNG component instead of a custom one. Always prefer to push for and suggest those tweaks.
• Use the new syntax for control flow rather than structural directives
  • ie. prefer @if and @for over NgIf and NgFor
• Do not abstract by default
  • ie. only pull out a component into a separate file when you are certain it will be re-used, or when you are trying to re-use it in a different component
• Inline templates (rather than a separate HTML file) can be used for templates no longer than 10 lines

Styling

• Use Tailwind utility classes instead of (S)CSS-files-per-component
  • Follow the Tailwind recommendations for reusing styles
• Add rules to styles.scss whenever it impacts PrimeNG-components that are (potentially) used in several places
  • You can see some examples already in styles.scss
  • With very few exceptions, everything else should be taken care of with Tailwind-classes directly in the relevant components
• Keep (any) custom CSS (even with Tailwind) to a minimum
• Make sure to use "*-start/*-end" instead of "*-left/*-right" in positioning/margin properties/classes
  • This increases support for RTL in the future
  • eg. ms-0 ps-0 instead of ml-0 pl-0