Principles for building web applications

1. Use Gjensidige's design system
   • Read more about Builders Core
   • It's expected that you contribute to our libraries when there is something that is missing, or does not work as expected.
   • Reach out to the team on Slack.
2. Use React
3. Use TypeScript
4. WCAG-compliant
   • There's more details on this on our dedicated universal design-page.
5. Our applications are simple to run
   • Store mock data alongside our projects so they can be run locally without much hassle.
6. Prefer to bundle using Vite
7. Keep your dependencies in check
   • Use exact versioning for dependencies to keep your builds deterministic: npm config set save-exact=true. Use dependabot for keeping them up-to-date.
   • Actively look for and eliminate any security issues.
   • Replace deprecated functionality and libraries sooner than later.
   • Refrain from using (and make a plan for migration) stale/deprecated/end-of-life libraries, like moment.js
8. Follow the principle of least power
   • Don't rely on old React packages that does something you can do using our design system or in JS/CSS (like react-animate-height).
   • Do not use javascript for something you can solve using css or html.
   • Do not use aria for something you can solve with correct semantic html.
9. Have a clear linting-strategy
   • Using your preferred combination of ESlint, prettier, or BiomeJS, oxc, etc.
   • Linted code helps minimize errors and confusion, and having it installed in your IDE makes for a good DX.
   • Your team decides which specific rules makes sense for you. In general, being too strict might make the team lose speed, while being too lose can introduce confusion.
10. Sane commit messages
    • Some teams use conventional commits to make their commits human and machine readable. This is not required, but all teams should strive for some form and consistency, and having descriptive messages.
11. We have automated tests
    • Study our Testing Principles
12. Need routing? Use React Router
    • Both BrowserRouting and HashRouting works in Application Portal, the former is preferred.
13. Clear plan for state management
    • If using state management outside of what React offers, use Redux Toolkit
14. Use our log and error handler
    • The /api-tools/ endpoint is deprecated
15. Your app is observable
    • Add observability in the front-end, using Faro.
16. We create shared libraries
    • For the code that we can share across our own applications
    • When one of our libraries or components seem to be beneficial for other teams than our own, we contribute it to our Core Libraries
17. Runs on GAP, stored on our CDN
    • Gjensidige infrastructure run on the Gjensidige Application Platform. You can reach the team responsible over at Slack on #gap.
    • Your app should be uploaded to our CDN, it should use a manifest-file that points to each used asset, each asset should be named with a unique pattern for each release/deployment (since our CDN-server will store assets, not manifest-files, in cache in a very strong way depending on filename).
18. Use Storybook
    • Or use similar "code becomes docs"-tools, to document and isolate your components.
    • Store other documentation for your code in a suitable format for your team, be it docosaurus, Storybook, Confluence, readme-files, or as GitHub wikis.
    • Try and unify the collection of docs so it is easier to get started with your project.
19. Consider Analytics, Personalization
    • Gjensidige has many experts within the fields of Analytics and Personalization. Use them to make sure your app is compliant, when relevant. Web apps needs to implement analytics, but also support personalization.
20. Separation of concerns
    • Your app is layered (or divided) in such a way that each part handles one task, and hands over to other tasks when it is done.
    • A single function should not validate a form and write to the database and present a message to the user, these are three separate functions (or more).
21. Support most users
    • See our list of supported browsers
22. Have a README.md in your project root
    • (and also in each folder when working with mono-repoes)
    • This should explain the purpose of the app
    • Clearly state ownership
    • Link to Grafana and other relevant toolings for debugging the app
    • Detail requirements for building the app locally - this should list everything from Node-version to any required system variables.
    • Consider adding information on how to create a first PR, how to deploy/release.
23. Bundle packages with your app
    • Preferred over adding additional scripts to external URLs.
    • Using external CDNs opens for more vulnerabilities, bypasses code-scanning, decreases experienced performance for end-users, and could potentially crash your app.
24. Code in English
    • For Slack and code, which are used across multiple countries and languages, we highly recommend sticking to English.
    • Even if multiple persons in a communication are Norwegian speaking, future users might find the conversation useful and in need of the information.
    • Teams may choose to deviate from this in internal channels, team-channels, wiki-spaces and documentations, and even code.
25. Comment code in a sane way
    • Don't explain obvious code, like what a simple line does if it is possible to derive it from just reading the code.
    • Do explain in a comment if one must re-read the line of code more than once to understand what it does.
    • Use the naming of functions to explain what it does, eliminating the need for comments.
    • Name variables/constants in such a way that it explains what it contains.
    • When code is deviant, or does something in a peculiar way, it is nice to explain why you did it that way.
    • Refrain from littering the code with "TODO: this should be refactored" as it rarely is revisited, and spending the time directly is a better investment.
26. Fail gracefully on API calls
    • Expect APIs to not respond (or be slow).
    • Notify kindly, fail gracefully.
    • Let the user know what happened, how it affects them, and how they can solve it.

The core principles are limited, and we are considering many more principles, but also want to give enough room for flexibility and for each team to solve problems as they see fit. However, these are not adopted principles, they might be, and if applicable for you they can help building better apps and user experiences.

1. Use bun for installing dependencies and building the node_modules folder as it is much faster than npm
2. Prefer a mono-repo structure for apps before having multiple repoes as technical depth will be harder to monitor and solve otherwise.
3. It is better to write long and  self-explainatory code than complex and short code.
   • Stringing too many  functions together decreases readability, refrain from doing things like .map().sort().split().join().map() and rather create functions that can with its name explain what it does.
   • Code that is easy to understand will more often live longer, be adopted and maintained by new members of the team, and get updates, than complex and hard to read code.