Skip to main content

Utvikler

Kom i gang med Indeks i prosjektet ditt. Velg teknologi under, så tilpasser guiden seg.

Velg teknologi​

Installasjon​

1. Fonter og CDN-tilkobling​

Legg til SB1-fontene i <head> i HTML-dokumentet ditt. Monorepo-generatoren gjør dette automatisk.

Indeks henter fonter, CSS, web components og ikon-SVG-er fra cdn.sparebank1.no ved runtime. Legg derfor en preconnect øverst i <head> — da rekker nettleseren DNS-oppslag, TLS-handshake og tilkobling før den første ressursen faktisk skal lastes, og du sparer ventetid på den kritiske gjengivingsstien.

<!-- Koble til CDN tidlig — før fonter, CSS og web components lastes. -->
<link rel="preconnect" href="https://cdn.sparebank1.no" crossorigin />

<link rel="stylesheet" href="https://cdn.sparebank1.no/fonts/v1.css" />

crossorigin er nødvendig fordi fontene lastes med CORS; uten det åpner nettleseren en egen tilkobling for dem og preconnect-en blir bortkastet.

2. Styling​

Importer CSS-en fra CDN inn i hoved-CSS-filen din, og legg ix-body-klassen på <body>. CDN-URL-en er den samme på tvers av SB1-applikasjoner, så nettleseren kan gjenbruke samme cachede CSS.

@import url('https://cdn.sparebank1.no/indeks/css/0.22.1/index.css');
<body class="ix-body">

Du får komponentstyling, utility-klasser og designtokens i samme pakke.

3. Web components​

Last inn web components-scriptet fra CDN i index.html.

@sb1/indeks-react er et tynt lag oppå web components og rendrer <ix-*>-elementer internt, så scriptet må være lastet for at React-komponentene skal virke.

<script type="module" src="https://cdn.sparebank1.no/indeks/web/0.22.1/index.js"></script>

3a. TypeScript-typer (valgfritt)​

Bruker du TypeScript? Installer @sb1/indeks-web som devDependency for å få TS-kjennskap til <ix-field> og andre ix-*-elementer. Runtime lastes fortsatt fra CDN (steg 3), så pakken havner ikke i produksjonsbundlen.

npm install --save-dev @sb1/indeks-web

Aktiver typene ved å legge pakken i tsconfig.json:

{
  "compilerOptions": {
    "types": ["@sb1/indeks-web"]
  }
}

Pakken bruker declare global for å utvide HTMLElementTagNameMap og JSX.IntrinsicElements. TypeScript plukker bare opp dette hvis pakken er listet i types eller importert.

3b. Autocomplete i editor (valgfritt)​

Få forslag på klassenavn og CSS-variabler når du skriver. VSCode-utvidelser gir dette — men krever to utvidelser (ingen enkelt-utvidelse dekker begge):

Legg til workspace-konfig som peker til CSS-filen i @sb1/indeks-css. Siden tokens og utils er inlinet i index.css, er det bare én fil å peke til:

// .vscode/settings.json
{
  "css.styleSheets": [
    "node_modules/@sb1/indeks-css/dist/npm/index.css"
  ],
  "cssVariables.lookupFiles": [
    "node_modules/@sb1/indeks-css/dist/npm/index.css"
  ]
}

Anbefal utvidelsene for alle team-medlemmer:

// .vscode/extensions.json
{
  "recommendations": [
    "ecmel.vscode-html-css",
    "vunguyentuan.vscode-css-variables"
  ]
}

Reload VSCode-vinduet etter npm install for at utvidelsene skal plukke opp filen. Autocomplete virker på rene string-literaler — clsx(...) og template-strings mister delvis støtte. Andre editorer (Cursor, WebStorm, Zed) har tilsvarende utvidelser fra sine markedsplasser.

4. React-komponenter​

Installer React-pakken:

npm install @sb1/indeks-react

Importer komponentene der du skal bruke dem:

import { Button, Text } from '@sb1/indeks-react';
function App() {
    return (
        <div>
            <Text>Innhold</Text>
            <Button>Klikk meg</Button>
        </div>
    );
}

4a. Testoppsett​

Skriver du tester mot komponentene, trenger du én import i testoppsettet:

// vitest.setup.ts
import '@sb1/indeks-web';

Flere av skjemakomponentene får label-koblingen og ARIA-attributtene sine fra web-komponenten når den mounter. Registrerer du den ikke i testene, finner ikke getByRole feltene dine.

Testing går gjennom oppsettet, hvordan du spør etter feltene, og hva som virker uten web components.

5. Hold CDN-URL-er i takt​

@sb1/indeks-css og @sb1/indeks-web versjonslåses til samme versjon som @sb1/indeks-react. Når Dependabot bumper React-pakken i package.json, må CDN-URL-ene i index.html og CSS-filene dine oppdateres til samme versjon — ellers kjører nettleseren en annen versjon av CSS og web components enn React-komponentene forventer.

Scriptet indeks-react sync-cdn oppdaterer URL-ene til å matche versjonen du har installert. Legg til to scripts i package.json:

{
  "scripts": {
    "prebuild": "indeks-react sync-cdn --check",
    "sync-indeks": "indeks-react sync-cdn"
  }
}
  • prebuild kjører før hver npm run build og feiler hvis URL-ene ikke matcher installert versjon. Dette er med vilje: hvis builden auto-fikser dette, vil det som deployes kunne bruke andre klasser enn det du har testet lokalt. La utvikleren se feilen og kjøre sync eksplisitt.
  • sync-indeks kjører du selv etter en dependency-bump — eller når prebuild feiler. Den oppdaterer filene, du commit-er endringene og kjører builden på nytt.

Hva utskriften betyr​

Kommandoen skiller mellom tre utfall, så du alltid ser hva den faktisk fant:

  • Alle N CDN-URL-er i M fil(er) bruker samme versjon … — den fant URL-er, og alle peker på installert versjon.
  • Fant ingen CDN-URL-er … — den fant ingenting å synce. Importerer du fra npm i stedet er det som forventet, og da kan du fjerne prebuild/sync-indeks. Ellers skriver den ut et ferdig CDN-oppsett med installert versjon, klart til å lime inn.
  • Ulik versjon: N av M URL(er) … peker ikke på <versjon>. — URL-ene står på en annen versjon, og utskriften viser hvilken versjon hver URL gikk fra og til.

Til slutt kommer en kort Pakkestatus for de tre versjonslåste pakkene: hvilken versjon som er i bruk, om den hentes fra CDN eller npm, om du er på siste versjon på npm, og om CDN-en har artefaktene for versjonen ennå. Nettverksoppslagene er «best effort» — de påvirker aldri exit-koden, og --offline hopper over dem.

Ligger du bak siste versjon på npm, skriver Pakkestatus ut kommandoen ferdig utfylt:

npm install @sb1/indeks-react@0.23.0 && npm run sync-indeks

Kommandoen oppgraderer aldri avhengigheten selv, og den skriver aldri en URL du ikke har installert — da ville nettleseren kjørt CSS og web components fra en annen versjon enn React-koden i bundlen. Derfor må npm install komme først. Scriptnavnet plukkes fra package.json din, så du får navnet du selv har valgt.

Krev at CDN-URL-ene finnes​

Uten funn returnerer --check 0, fordi et npm-basert prosjekt legitimt har null CDN-URL-er. Vet prosjektet ditt at det bruker CDN, skru på --require-urls — da fanger du også at noen fjerner <link>-tagen:

{
  "scripts": {
    "prebuild": "indeks-react sync-cdn --check --require-urls"
  }
}

URL-er på den gamle formen …/indeks/css/<versjon>.css migreres til …/indeks/css/<versjon>/index.css — den flate formen finnes ikke på CDN-en. @sb1/indeks-tokens og @sb1/indeks-utils har egne versjoner og skrives aldri om; de rapporteres bare, siden innholdet deres allerede ligger inne i indeks-css.

Typisk flyt etter en Dependabot-bump:

npm install          # ny indeks-react-versjon låst i package-lock
npm run build        # prebuild feiler: ulik versjon
npm run sync-indeks  # URL-ene oppdateres
git add -A && git commit -m "sync CDN til <versjon>"
npm run build        # passer nå

Vi anbefaler npm install --ignore-scripts av sikkerhetsgrunner, og det hopper over alle lifecycle-hooks — derfor kan vi ikke sette dette opp som postinstall. CDN-sync må hektes på en kommando du eksplisitt kjører.

Installere via npm i stedet for CDN​

@sb1/indeks-css og @sb1/indeks-web finnes også på npm, men vi anbefaler CDN. Med CDN deler alle SB1-applikasjoner samme URL, så nettleseren kan gjenbruke cachen på tvers av apper — brukerne slipper å laste ned CSS og web components på nytt når de bytter mellom SB1-tjenester.

Hvis du likevel vil bundle det selv (f.eks. intern app uten CDN-tilgang):

npm install @sb1/indeks-css @sb1/indeks-web

Hva nå?​

Teknisk struktur​

De fleste trenger ikke å forholde seg til dette, men du kan lese videre hvis du er spesielt interessert.

Indeks er bygget opp av 5 pakker:

  • indeks-tokens
  • indeks-utils
  • indeks-css
  • indeks-web
  • indeks-react

Vi har også en mappe med dokumentasjonen og en eksempel-app vi bruker til å teste.

Rapporter feil på denne siden