For å få tid til mer kvalitativt innsiktsarbeid i den travle, smidige produktutviklingshverdagen: Fokuser på innsiktsøyeblikket!

Det er tungt å innrømme, men vi må være ærlige. Vi gjør ikke kvalitativ innsikt så ofte som vi skulle ønske. For i den smidige hverdagen vår hvor ting leveres kontinuerlig og avgjørelser tas hyppig, kan klassiske metoder for innsikt føles som et tungt, gammeldags beist som stagnerer fart og flyt i digital produktutvikling. Likevel vet vi at vi trenger den kvalitative innsikten! Den er sentral for at vi kan gjøre jobben vår best mulig. Så hva skal til for at vi gjør det oftere? Vi tror nøkkelen ligger i å fokusere på gullet i kvalitativ innsikt: Selve innsiktsøyeblikket.

Hvorfor gjør vi kvalitativ innsikt, egentlig?

Du vet ikke når det treffer deg. Innsiktsøyeblikket. Det sitatet fra brukeren som treffer deg midt i hjertet. Den kommentaren som gir deg en idé. Det innspillet som plutselig gir deg et helt nytt perspektiv. Den historien som får engasjementet ditt til å flamme. Alle disse små øyeblikkene er grunnen til at vi må gjøre det viktige kvalitative innsiktsarbeidet. For det er akkurat der og da – i øyeblikket – at innsikt oppstår og vi lærer noe som vi faktisk kan bruke når vi designer.

Vi har et stort indre bibliotek av innsiktsøyeblikk som har endret oss. For eksempel hun som fortalte om følelsen av å miste kontroll og mening når hun plutselig sto uten jobb og kollegaer, og som ærlig delte følelser gjennom gråt. Eller den brukertesten hvor han som er blind demonstrerte hvor j*vla frustrerende det er å ikke få gjennomført helt grunnleggende, og tilsynelatende enkle, ting som å sjekke når neste buss går.

Slike øyeblikk får en gjennom førstehåndserfaring. Du må oppleve dem selv for å virkelig bli påvirket. Gjenfortelling eller videreformidling av innsikt utløser ikke samme styrke av følelser i oss. Det gir ikke samme mulighet for empati og forståelse, og det gir ikke like dype inntrykk. Og veldig ofte, så er det nettopp dette vi – oss som driver med produktutvikling – trenger for å forstå hvorfor og hvordan noe bør gjøres. Det hjelper oss med å prioritere og få eierskap. Det er viktig for hele teamet.

Barrierer for “den korrekte prosess”

Så ja. Vi vet det godt! Kvalitativ innsikt er skikkelig verdifullt. Men det eksisterer mange barrierer mellom oss og dette gullet. Dette kan være en av grunnene til at vi ofte havner i det Ida Aalen kaller for “byggefella”, hvor det produseres masse med bakgrunn i lite og mangelfull innsikt.

Så hva er disse barrierene? Det har faggruppen vår i Bekk – “kontinuerlig læring” – snakket mye om i høst. I det daglige sitter de fleste av oss ute i tverrfaglige produktteam som fokuserer på forbedring av levende, digitale løsninger hos norske bedrifter. Mange av oss kjenner på to hovedutfordringer: Forarbeid og etterarbeid krever (for) mye. Når vi endelig tar oss tid til kvalitativ innsikt, er det lett å havne i byggefellas strake motsetning, “analysefella”, hvor ting bearbeides og dokumenteres i det evige. Vi er skolert opp til at den klassiske innsiktsprosessen skal være grundig og omfattende i alle ledd. Stoltheten vår ønsker å gjøre ting riktig og nøye!

Det er kanskje litt ironisk at det som står i veien for flere innsiktsøyeblikk i hverdagen, er at det går med for mye tid til alt som skjer før og etter selve øyeblikket…

Hvordan få til godt (nok) innsiktsarbeid i den travle hverdagen?

Ikke overraskende foreslår vi å redusere tiden som brukes på forberedelser og etterarbeid! Øk heller tiden og hyppigheten på innsiktsøyeblikkene - for hele teamet. Jobb for å gjøre innsiktsarbeid til en rutine, ikke et event.

Få bukt med barrieren “forarbeid”

Et konkret tiltak for å redusere forarbeidsbarrieren, er å rekruttere kontinuerlig og automatisk slik at dere ofte har noen å snakke med. Da går det mindre tid til selve rekrutteringen, i tillegg vil hyppigheten av intervjuene føre til gode, innarbeidede rutiner for samtykkehåndtering og kommunikasjon. Siden dere har jevn tilgang på folk å snakke med, blir hvert intervju også mindre “kritisk”. Det gjør ikke noe om dere ikke får besvart alle spørsmål i ett enkeltintervju, for dere har mange flere foran dere! Og da trengs det kanskje heller ikke like mye forberedelser før hver prat gjennom detaljerte intervjumaler. Når det ikke er så farlig å få besvart alle spørsmålene deres, får brukeren også mer plass til å fortelle sin historie og snakke om det de synes er viktig. Og slik blir det ofte fine, uforutsette innsiktsøyeblikk av!

En sentral forutsetning for å få til dette er selvfølgelig at man har et sikkert og effektivt verktøy for å rekruttere på denne måten. Dette kan for eksempel være via en løsning teamet lager selv eller via spesialtjenester for rekruttering som UX Signals.

Reduser etterarbeid med analyse og dokumentasjon

Innsikten vi er på jakt etter i et smidig produktteam skal hjelpe oss å ta gode valg underveis i produktutviklingen. Hva er det neste vi prioriterer å lage? Er denne funksjonaliteten viktigere å bygge enn denne? Når vi tar slike avgjørelser, er det sjeldent nødvendig at innsikten er nøysomt og omfattende dokumentert.

Det er selvfølgelig situasjoner der dokumentasjon av innsikt er selve målet, for eksempel hvis en skal lage en rapport som underlag til ledelsesbeslutninger. Men sånn i hverdagen til et produktteam, hvorfor trenger vi egentlig denne innsikten? Hvis det er for at teamet kontinuerlig skal ta gode valg i produktutviklingen – og hvis teamet jevnlig opplever innsiktsøyeblikk – trenger vi da å ha alle detaljer dokumentert?

Oppsummer effektivt rett etterpå

Sett av maks 30 minutter rett etter et intervju til å oppsummere det viktigste som kom frem. Analyser og dokumenter med en gang. “Token ring” er en metodikk vi har lært av Kari Hamnes som man for eksempel kan bruke til dette: Ta runden rundt bordet og la hver og en av de som observerte innsikten nevne et nøkkelfunn de sitter igjen med. En person noterer disse i en felles oppsummering. En skal ikke gjenta det samme som noen andre har sagt, men en kan utbrodere på andres punkter. Resultatet av denne øvelsen, er at man sitter igjen med en oppsummering som inneholder det aller viktigste og som alle har eierskap til.

Analyse på tvers av intervjuer

Hvis innsiktsarbeidet blir en vane i hverdagen for teamet, kan det innimellom være nyttig å ta seg tid til å se over oppsummeringene sammen. Hva har vi lært? Ser vi noen tydelige fellestrekk? Når vi tar et helhetlig perspektiv, endrer det vår forståelse?

Har vi god tid, kan den klassiske affinity-mappingen være fin å bruke: Å få alle innsiktsnuggets ut på post-is eller et digitalt whiteboard. Flytte på lapper og sitater. Sammen lete metodisk etter funn. Gjøre analyseprosessen litt mer “korrekt”.

Uansett hvordan ditt team løser det, vil vi trekke frem at det viktigste ikke er det som står skrevet ned et sted. Det viktigste er den kunnskapen og empatien hvert teammedlem sitter med, og hvordan dere velger å omsette dette i det dere lager. Så om dere ikke har tid til den store “korrekte prosessen”, så har vi god erfaring med at en time felles lesestund i teamet og lavterskel refleksjon sammen gir også mye forståelse og innsikt!

Samle på flere innsiktsøyeblikk

Øk verdien av, og senk terskelen for, det kvalitative innsiktsarbeidet med å legge mest vekt på det aller viktigste: Innsiktsøyeblikket. Gjør innsiktsarbeidet til en naturlig del av teamhverdagen for å fylle "innsiktsbanken" til hver enkelt, og for å skape felles forståelse av hva teamet bør lage og hvorfor. Lytt til folks historier og la innsiktsøyeblikkene påvirke alle de små og store valgene dere tar hver dag.

Hva med deg og teamet ditt? Hvilke innsiktsøyeblikk har endret dere? 

Innsiktsøyeblikket: Gullet i kvalitativ research

Storybook tilbyr en rå, interaktiv playground for å teste ulike props, men det kommer med en pris: med det følger en tvangstrøye av et design. 

Ved å kombinere React Live og litt strengkonkatenering kan du lage en løsning du har full kontroll over, samtidig som du gir brukerne dine en effektiv måte å få oversikt over en komponents muligheter.

Hva består en playground av?

Det jeg hadde lyst på var en playground, som lot meg teste ulike props og å se hvordan komponenten ville se ut, lignende det Storybook tilbyr:

Vi hadde valgt bort Storybook til fordel for fleksibilitet, og måtte derfor lage noe tilsvarende på egenhånd. Så hvordan bygger du noe sånt fra scratch?

Vi kan dele det opp i noen enklere funksjonaliteter:

Forhåndsvisning av komponent

Kodeeditor

Endre komponenten via skjema

Generere skjema utifra props

Forhåndsvisning og kodeeditor

La oss starte med React Live, som huker av for to krav. Det er et bibliotek som tilbyr både forhåndsvisning av kode og en kodeeditor. Koden som blir vist er styrt av code-propen i LiveProvider:

Her er hvordan dette ser ut rendret på en side:

Når koden endres, oppdateres forhåndsvisningen. Det skjer også om en bruker endrer på teksten i editoren. 

Men vi ønsker ikke å tvinge brukerne til å skrive ut alle varianter selv via editoren. Så hvordan kan vi endre koden utenfor selve kodeeditoren?

Hvordan endre på komponenten med et skjema

Siden forhåndsvisningen automatisk endrer seg når koden i LiveProvider endrer seg, trenger vi bare å sette koden for LiveProvider i en variabel, så vi senere kan oppdatere den:

Vi kan så lage en variabel componentProps for å holde styr på props. Vi lager det som et objekt, så vi kan holde styr på hvilken prop som har hvilken verdi. Her initert med variant og children:



Vi kan så oppdatere code-variabelen når componentProps endres. Dette gjør vi via en useEffect.

Siden LiveProvider tar imot en streng, gjør vi om objektet til en streng med key-value-par. Så putter vi den strengen i komponentnavnet for å rendre komponenten riktig:

Her er resultatet:

Vi har nå gått fra å hardkode en streng, til å danne strengen via props definert i et objekt. Resultatet er det samme, men omskrivningen vår gjør det lettere for oss å legge til noe viktig: interaktivitet.

Hvordan får vi til interaktivitet?

For å få til interaktivitet bruker vi et skjemaelement som vil oppdatere componentProps. Vi lager en handler handlePropChange som tar imot propnavnet vi vil oppdatere og den nye verdien.

Her legger vi handleren på en select:

Nå har vi fått til interaktivitet for en av propsene våre:



Men ulike komponenter vil ha ulike inputs avhengig av props. Hvordan kan vi generere skjemaelementer basert på props?

Generere skjema utifra props

En måte er å definere hvilke props en knapp har, og hvilke verdier vi ønsker å vise frem. Legg merke til at vi også definerer type, som vi vil bruke for å switche hvilket skjema-element vi rendrer verdiene i:

Etter å ha definert typer, kan vi switche over props og rendre passende skjema-elementer, her med eksempel select og text-input:

Her er resultatet:

Avsluttende ord

En playground er et utrolig nyttig verktøy som effektivt demonstrerer mulighetene til en komponent. Med bruk av React Live og litt streng-konkatenering, har vi sett hvor langt vi kan ta funksjonaliteten.

Over har jeg vist en basal løsning for å få prinsippene frem, men her er noen forslag til videre forbedringer:

Flytt playgroundProps ut i egen fil for oversiktlighet

Legg også til inititialProps, for bedre startpunkt over hva komponenten kan gjøre

Ikke rendre children som en prop, men mellom opening- og closing tag.

Støtt sammensatte komponenter

Finn en automagisk måte å hente ut komponenter sine props (det har dessverre ikke jeg funnet, så rop ut om du finner en løsning!)

💛 Denne playgrounden er inspirert av Enturs playground. Tusen takk til Magnus Rand som pekte meg i retning av hvordan deres var lagd, så jeg kunne lage min egen versjon.

Du trenger ikke Storybook for å lage en playground

Pull request, backlog, Kotlin og Kafka...

Hva betyr ordene, og hvorfor har utviklere så vanskelig med å snakke så alle forstår? Hobbyprosjektet Teknisk ordbok prøver å gjøre hverdagen litt lettere for ikke-teknologene i teamet ditt.

Hva er Teknisk ordbok?

Teknisk ordbok er en liten nettside som har som mål å gjøre hverdagen litt enklere for ikke-teknologer. Mange team i dag er kryssfunksjonelle, det vil si at man har utviklere, jurister, produktledere, teamledere og designere i samme team. Alle disse rollene skal jobbe godt sammen og til det må man kommunisere med et språk som alle forstår.

Uheldigvis kommer man ikke alltid unna å bruke tekniske begreper når man skal forklare en problemstilling, spesielt hvis flertallet av et møte består av utviklere. Teknisk ordbok er derfor et forsøk på å forklare en del av disse tekniske begrepene utviklere bruker på en enkel måte.

Motivasjon og inspirasjon

Motivasjon og inspirasjon til løsningen kom når min kone gikk fra en lederstilling i en del av bedriften og over i en produktlederrolle som plutselig skulle jobbe i et team med utviklere. 

Hun fortalte ofte at hun var helt utslitt av lange møter der utviklerne snakket over hodet på henne. Hun sendte meg ofte spørsmål som hva betyr event-drevet arkitektur eller hva er webhooks? 

Siden problemløsing er en stor del av min jobb som utvikler tenkte jeg at det måtte være en måte å samle alle disse ordene. Jeg har selv erfart ikke-teknologer i møter som nikker som om de forstår alt som blir sagt, bare for å si etter møte at det ikke var alt de forsto. 

Tech-stack

Nettsiden er skrevet i Typescript og med rammeverket Remix. Intensjonen har vært å holde kompleksiteten på et minimum, så her finnes ingen database, bare en hardkodet typescript-fil med et Javascript-objekt som holder på alle ordene og beskrivelsene som er lagt inn. Styling gjøres via Tailwind.



Innholdet er i stor grad "skrevet" av ChatGPT 3.5. Jeg har gitt ChatGPT et prompt og matet ChatGPT med tekniske ord. ChatGPT har så returnert en ikke-teknisk forklaring på ordet som jeg så har lagt inn i det hardkodete objektet.

Status

Status på løsningen er at det finnes mange ord der som forhåpentligvis har enkle forklaringer. I tillegg finnes det noen scenarioer som er forklart på en ikke-teknisk måte. For eksempel, hvordan integrere mot andre tjenester, hva er testdrevet utvikling?, og andre spørsmål.

Jeg legger inn nye ord i løsningen etter hvert som jeg selv hører tekniske ord vi bruker i møter. I tillegg har jeg en liste med ting som hadde vært kult å implementere på sikt.



Oppsummert

Vi som teknologer har et særlig ansvar når vi snakker i møter. Vi bør etterstrebe å gjøre oss forstått på en måte så alle i møtet forstår oss, men vi kommer ikke alltid unna å bruke tekniske ord og uttrykk. Hobbyprosjektet mitt, Teknisk ordbok har som mål å ta ned barrieren mellom teknologer og ikke-teknologer. 

Så om du kjenner noen som kunne hatt nytte av å lære seg noen nye ord, så er det bare å like og dele som ungdommen sier! 



Her finner du løsningen Teknisk ordbok



Hobbyprosjekt: Teknisk ordbok for ikke-teknologer

Hvordan får du med deg alle de ansatte i bedriften når nye interne arbeidsverktøy skal innføres eller erstattes? Her får du noen tips til hvordan du kan innføre nye verktøy uten å skape masse støy og friksjon

Innføring av nye interne arbeidsverktøy i en bedrift kan ofte være en kilde til frustrasjon blant ansatte. Dette vil spesielt være tilfelle hvis de ansatte vegrer seg for endring. De ansatte mener at systemene de har i dag fungerer og hvis de tenker at slik det alltid har vært gjort fortsatt fungerer.

I en stadig mer digitalisert verden vil det være prosesser i en bedrift som kan få et nytt liv ved digitalisering og tekniske løft. Hvordan passer du på å få med deg både de tekniske kjepphestene i bedriften, samtidig som de ansatte som misliker endring også skal bli med? Kommunikasjon! Har du en god strategi for hvordan du skal kommunisere ut endringer, og samtidig en god plan for hvordan du skal ta i mot og bearbeide tilbakemeldinger underveis så vil du stå godt rigget for å gjøre de nødvendige endringene som skal til for at du får med deg alle brukerne.

Forklar veikartet for brukerne dine

Når du som produktleder, team lead, prosjektleder eller annen tittel vet at det vil komme større endringer til ansatte så er det en gylden anledning til å inkludere brukerne i bedriften fra starten av. Ikke vent med å lansere løsningen i et big bang. Få inn noen betabrukere tidlig og lytt til verdifull innsikt fra de som til slutt skal bruke systemet.

Jo tidligere de ansatte føler at de er en del av utviklingsprosessen jo mindre støy vil det generere og mer forståelse vil brukerne kunne gi deg. Selv om teamet jobber med kontinuerlige leveranser så kan man fint forklare overordnet når teamet skal jobbe med ulike deler av løsningen i det store bildet.

Det trenger ikke være så avansert å komme i gang. Inviter de mest entusiastiske ansatte og gi de tidlig tilgang. Ofte vet ikke brukerne helt hva de ønsker seg, men gi dem noe konkret tidlig og du vil som regel få mye og god innsikt i hva brukerne ønsker seg på sikt. Det er til syvende og sist brukerne som faktisk skal bruke løsningen, og bedriften er godt tjent med å ha fornøyde ansatte som liker de nye verktøyene de skal bruke.

Gjør det enkelt å gi tilbakemeldinger

Når man sitter i et utviklingsteam er det lett å glemme at kommunikasjonen må gå begge veier. Teamet må enkelt kommunisere endringer, spørsmål og få avklaringer fra brukerne, og samtidig må brukerne ha en enkel måte å kontakte teamet. Ikke la det være vanskelig for brukerne å gi tilbakemeldinger, da går du glipp av mye god innsikt fra de som til syvende og sist skal bruke systemene dere utvikler. La brukerne kontakte teamet direkte på Teams/Slack/osv. Sett opp et skjema i løsningen som brukerne kan melde direkte til teamet. Akkurat hvilken teknisk rigg dere går for er ikke så farlig. Det viktigste er at det er enkelt å gi tilbakemeldinger.

Kommuniser alle endringer i relevante kanaler

Det vil skje endringer i løsningene man utvikler hele tiden. Når utviklerne leverer ny funksjonalitet kan man enten samle opp en post i uken som forklarer det viktigste som har kommet og dele det på Teams/Slack/osv., eller la utviklerne selv dele funksjonalitet de har levert. Utviklerne vil da få et større eierskap til levert funksjonalitet og bli bedre kjent med brukerne.

Vær ærlig når teamet tar feil

Noen ganger tar teamet feil. Det er i stor grad essensen av å drive kontinuerlig utvikling der man hele tiden måler effekten av det man gjør, og er åpen for tilbakemeldinger hele veien under utviklingsløpet. Når teamet lærer at de har bommet må man ikke prøve å skylde på brukerne, men være helt ærlig på at man har bommet, takke for ny og verdifull innsikt og så implementere de relevante endringene som må på plass. De ansatte vil da forstå at det nytter å komme med tilbakemeldinger og de vil føle at de blir tatt på alvor under utviklingsprosessen.

Løs noen lavthengende frukter også - Skaff deg goodwill

Det er viktig å ha fokus på de store linjene og fremtidig uthenting av gevinst, men ikke la det bli det eneste dere fokuserer på. Dersom man migrer seg bort fra et gammelt system, så ta dere tid til å lytte til hvilke utfordringer brukerne har i dag. Ikke bare fokuser på hvordan det nye systemet skal løse alle brukerens problemer i fremtiden. Prøv å identifisere noen lavthengende frukter som vil være enkle for teamet å implementere med ny løsning og vis at dere tar brukerens tilbakemeldinger på alvor. Et par lavthengende frukter kan være det som skal til for å få med seg de brukerne som er averse for endringer, og det vil gi teamet mye goodwill når vanskeligere prioriteringer må tas i fremtiden.

Konklusjon

Ved å ha en god strategi for kommunikasjon med brukerne vil man kunne få mye god innsikt, redusere friksjon og skape et godt grunnlag for samarbeid når nye IT-løsninger skal lanseres for de ansatte i en bedrift. Ikke vent til man er "ferdig" med å kommunisere at nå kommer det endringer. Få med dere de ansatte tidlig i prosessen, la dem ta eierskap til løsningene de selv skal bruke og la dem være med i utformingen av dem. Lytt til den innsikten de sitter på, guide dem hvis teamet ser nye og mer effektive måter å løse et problem på, og vær en lagspiller i alle faser av implementasjonen av nye løsninger.

Da vil du stå godt rigget for fornøyde brukere som tas på alvor og det vil være enklere å få med seg alle ansatte når nye IT-løsninger skal innføres i bedriften.



Systemet har rett - Brukerne tar feil

Storybook offers an awesome, interactive playground to test different props, but at a price: with it comes a straitjacket of a design. 

By combining React Live and some string concatenation, you can create a solution that you have full control over, while giving your users an efficient way to get an overview of a component's capabilities.

What does a playground consist of?

Lets start with what I wanted: I wanted something that allows me to test props and dynamically see how it affects the component's behavior and style, similar to what Storybook offers:

We had opted out of Storybook in favor of flexibility, and therefore had to create something similar on our own. The example seems pretty complex - how do you build something like that from scratch?

We can break it down into some simpler functionalities: 

Component preview 

Code editor 

Change the component via form 

Generate form based on props

Preview and code editor

Lets start with React Live, which checks two boxes. It is a library that provides both component preview and a code editor. The code that is displayed is controlled by the code prop in LiveProvider:

Here's how this looks rendered on a page:

When the code changes, the preview is updated. It also happens if a user changes the text in the editor. 

But we don't want to force users to type all variants themselves via the editor. So how can we change the code outside of the code editor itself?

How to change the component with a form

Since the preview automatically changes when the code in the LiveProvider changes, we just need to put the code for the LiveProvider in a variable so we can later update it:

We can then create a variable componentProps to keep track of the props. We make it an object, so we can keep track of which prop has which value. 

Here initiated with variant and children:

We can then update the code variable when componentProps changes. We do this via a useEffect.

Since the LiveProvider accepts a string, we turn the object into a string of key-value pairs. Then we put that string in the component name to render the component correctly:

Here's the result:

We have now gone from hard-coding a string, to forming the string via props defined in an object. The result is the same, but our rewriting makes it easier for us to to add the next crucial thing: interactivity.

How to we add interactivity?

To achieve interactivity, we use a form element that will update componentProps. We create a handler handlePropChange that accepts the prop name we want to update and the new value.

Here we put the handler on a select:

Now when we change value in select, we also change the preview of the component:

But different components will have different inputs depending on the props. How can we generate form elements based on props?

Generate form based on props

One way to generate form elements based on props is to put the information in an object. We define which values are possible to be displayed, and which form input we want to use to change the values. Notice that we have defined type, which we will use to switch which form element we render the values ​​in:

After defining types, we can switch over props and render appropriate form elements, here with for example select and text-input:

Here's the result:

Final words

A playground is an incredibly useful tool that effectively demonstrates the capabilities of a component. Using React Live and some string concatenation, we've seen how far we can take the functionality.

Above I have shown a basic solution to get the principles across, but here are some suggestions for further improvements:

Move playgroundProps out into a separate file for clarity 

Also add initialProps, for a better starting point of what the component can do 

Do not return children as a prop, but between the opening and closing tag. 

Support composite components 

Find an automagical way to extract components' props (unfortunately I haven't found that, so shout out if you find a solution!)

💛 This playground is inspired by Enturs playground. Huge thanks to Magnus Rand who pointed me in the direction of how theirs was made, so I could make my own version.

You don't need Storybook to make a playground

Are you a part of a development team working with React, TypeScript, and REST APIs? If so, you've likely encountered the challenge of maintaining consistent data types across the applications.

When it comes to API design and development, choices made may not always be obvious to other team members. Good documentation becomes essential, especially when you're not the sole consumer of your API.



Imagine a scenario where the backend automatically synchronizes with the frontend types, tedious tasks like manually creating types and reducing bugs caused by typos are eliminated, and the risk of breaking the frontend due to API changes is reduced. There are various methods to achieve these advantages, such as using Remix, GraphQL, or TypeScript monorepos. However, these may not be suitable options if your backend and frontend speak different languages.



In this article we will explore how you can ensure end-to-end type safety using a framework called Orval.js. The frontend is a React application written in TypeScript and the backend is a Spring-boot application written in Kotlin. However, any backend that can output an OpenAPI specification will work.



Spring Boot REST API With OpenAPI:

In the code example below we have a GET endpoint in the backend application, exposing a list of vampires from the series "What We Do in the Shadows".

The Vampire DTO (Data Transfer Object) is a data class encapsulating specific attributes of a vampire, including basic types and some enumerated types. The objective is to present the data to the frontend in the form of a contractual agreement.



To achieve this, we need to set up an openAPI configuration in the backend application, using the framework SpringDoc to generate the documentation. By including SpringDoc as a dependecy in our project's build file (Maven or Gradle), we can structure the API layer with annotations that describes the API. Utilizing annotations like @Operation, @ApiResponse, and @Tags enhances the documentation with the endpoint request method, parameters, and expected responses.



Converting OpenAPI To TypeScript:

Now that the contract of the API is generated, we only need to install Orval.js and give it some config to read the specification:

Point to the OpenAPI specification in the Orval config.

Give the directory where you want to store your newly generated interfaces, types, and endpoints a name.

Orval.js supports different frameworks. In this example, we use a data-fetching library called TanStack-query / React-query.

Set the mode to react-query in the Orval configuration, instructing it to produce hooks based on the OpenAPI specification.


With the configuration set-up, the only thing remaining is to re-run the application, and observe the magic of end-to-end type generation.





Once Orval compiles, it reads the response types defined in the backend's OpenAPI Specification and generates a TypeScript interface for the VampireDTO. In the example, all the fundamental types, an interface representing a list of abilities, and the enumeration types were successfully created.



Since we included react query mode in the Orval configuration, it has also generated an appropriate GET request as a react query hook, including the correct return type and a query key for effective caching.

Lastly, we are able to import the generated API hook useGetAllVampires() into the React component. This hook makes a http request to the backend, receiving a correctly typed list of VampireDTOs. Furthermore, as we traverse this list, TypeScript offers autocompletion for the available properties, along with their respective types.

Why It's Useful:

Consistency: It ensures that the types and hooks accurately mirror the structure of your API, reducing the chances of mismatches between frontend and backend.

Efficiency: It saves time as developers don't need to manually write and update types and hooks when the API changes.

Error Reduction: It reduces bugs because the TypeScript compiler will catch type mismatches and errors at compile time.

Maintainability: Auto-generated code is easier to maintain, especially when APIs evolve, as changes in the backend are automatically reflected on the frontend.



Potential Drawbacks:

Customization: The automatically generated react query hooks may not always fit. Therefor, additional wrapper code or modification is necessary to handle specific use cases.

Abstraction level: Developers may become too reliant on the generated code, potentially overlooking the need to understand the underlying API or the data model. This could lead to difficulties when the generated code does not work as expected.

Security concerns: Introducing any kind of third party comes with a security risk. In this case we utilize multiple frameworks, and a security exploit in any of their code can have consequences for your codebase.

Conclusion:

Hopefully, this example illustrated some pros and cons of contract-based Hopefully, this example illustrates that Orval.js can bridge the gap between a backend and frontend application written in different languages. Type generating creates a single source of truth for API interactions and leads to a more streamlined development process, fewer runtime errors, and a more maintainable codebase.



If you want to read more about this topic, check out these articles:

How to document a Spring REST API Using OpenAPI 3.0 by baeldung https://www.baeldung.com/spring-rest-openapi-documentation

Orval.js by Johannes Kettmann: https://profy.dev/article/react-openapi-typescript

Fetching data with TanStack Query by Sung-Jie Hung: https://medium.com/@notawonk/fetching-data-with-tanstack-query-react-query-1f649df3356b

12-Dec

Today's posts

Innsiktsøyeblikket: Gullet i kvalitativ research

Du trenger ikke Storybook for å lage en playground

Hobbyprosjekt: Teknisk ordbok for ikke-teknologer

Systemet har rett - Brukerne tar feil

You don't need Storybook to make a playground

End-to-end type safety with Orval.js