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.
Measuring programming progress by lines of code is like measuring aircraft building progress by weight.
Purpose
Our principles for building web applications are relevant for development and product teams at Gjensidige. It's expected of you to follow them, and to help us iterate on them. These are not set in stone, and are driven by our community.
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. 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 no specific principles for so detailed questions, and we believe you, your team, with the support of the frontend 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 code guidelines for your team.
Ideas, change requests, or comments?
We are always open for discussions, ideas and comments about our principles.
Our Principles
1. Use TypeScript
2. Use React
3. Use @gjensidige/core components and libraries
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 us on Slack.
Unless you have a well defined reason for other options.
5. Use React Router (if applicable)
6. Have a clear plan for state management
If using state management outside of what React offers, use Redux Toolkit
7. Use our log and error handler
8. Keep your dependencies in check and up to date
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.
9. Use our ESLint with prettier integration and conventional commits
We use conventional commits to make our commits human and machine readable. We use @gjensidige/eslint-config-core for a shared and recognisable code standards across our codebases.
When it comes to filenames and folder structure, use Core as an inspiration, but feel free to deviate, as long as you keep it consistent within your codebase and across your team.
10. Our applications are simple to run and test
We store mock data alongside our projects so they can be run locally without much hassle.
PS: Mock data should never contain sensitive or secret values (like passwords, SSN, etc.).
11. We have automated tests
We see no meaning in setting a specific coverage goal. The test suite should be sufficient enough that a new developer can make a change. If the tests go green, the build can be shipped to production without any manual verification:
-
Unit testing with jest (or Vitest)
-
Cypress for feature tests
-
All tests shall be able to run on CI
12. Follow the principle of least power
Do not use javascript for something you can solve using css or html. Do not use css for something you can solve with html. Do not use aria for something you can solve with correct semantic html.
13. Use Storybook (or similar "code becomes docs"-tools) to document and isolate our components
14. We create shared libraries for the code that we can share across our 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
15. WCAG compliant
There's more details on this on our dedicated universal design-page.
16. Stored on our CDN
Modern parts of Gjensidige infrastructure run on the Gjensidige Application Platform - or GAP for short. 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 in cache in a very strong way depending on filename).
17. 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.