Skip to content

Principles for building web applications

In most cases we encounter the same issues and problems when building web applications. These principles are here to guide us, increase our overall quality, and to help us build together.

Purpose

Our principles for building web applications are relevant for development and product teams at Gjensidige. These principles focuses on what is relevant for a front-end developer in our teams. The best outcome is when everyone at Gjensidige knows and adopts them.

The purpose of these principles are not to police you, but to remove any confusion or discussion about how/what to do within or across teams. They also make sure that the codebases across Gjensidige are aligned and easier for others to inherit. See them as a guide. And please discuss them with us on Slack at #frontend.

When it comes to more specific code standards, or library recommendations, use Slack to discuss this openly. We have decided to not have such super-detailed principles, we believe you and your team, with the support of the front-end community at Gjensidige, are capable of resolving this in the best way for your specific case.

If you see the need, feel free to add your own team principles, building further on these.

Measuring programming progress by lines of code is like measuring aircraft building progress by weight.

- Bill Gates

Our Principles

Ideas, change requests, or comments?

We are always open for discussions, ideas and comments about our principles.

Visit #frontend in Slack
  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
    • But don't use the deprecated create-react-app (CRA).
  3. Have you considered Preact?
  4. Use TypeScript
  5. WCAG-compliant
  6. Our applications are simple to run
    • Store mock data alongside our projects so they can be run locally without much hassle.
  7. Prefer to bundle using Vite
  8. 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 sooner than later) stale/deprecated/end-of-life libraries, like moment.js, node-sass, ++
  9. 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.
  10. 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.
  11. 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.
  12. We have automated tests
  13. Need routing? We suggest using React Router
    • Both BrowserRouting and HashRouting works in Application Portal, the former is preferred.
  14. Clear plan for state management
    • If using state management outside of what React offers, you should look into small and powerful Zustand, or Valtio, or use the older Redux Toolkit
  15. Use our log and error handler
    • The /api-tools/ endpoint is deprecated
  16. Your app is observable
    • Add observability in the front-end, using Faro.
  17. 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
  18. 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).
  19. 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.
  20. 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.
  21. 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).
  22. Support most users
  23. 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.
  24. 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.
  25. 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.
  26. 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.
  27. 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.

Candidate Principles

These principles are work in progress, they might or might not be promoted as main principles.

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.

Front-end Forum

Front-end Forum is a low-key gathering of the front-end developers in Gjensidige, where we share our latest projects and challenges.

Universal design through code

Developers have a particular responsibility for universal design. Here's what to consider, what to look for, and how to improve your apps accessibility through code.

Principles for automated testing

Automated testing for web applications can help catch errors before they happen, but they take time to create and maintain. Here's our guidelines to help you create a healthy test suit.

Supported browsers

Our list of supported browsers and operating systems is the minimum requirement. The following list is supported for all components in our component library and should be supported for all applications – from all teams.

Local component libraries

All product teams may create their own component libraries with components tailored to their individual needs.

Get started with Core

New to our design system? Whether you're a designer or developer, you'll find everything you need to know in our documentation in Storybook.

Contribute to Core

See our step-by-step guide on how to add new or improved components to our library.