PWA-sovellus

React-sovelluksen voi määritellä ns. PWA-sovellukseksi (Progressive Web Application), joka käyttäytyy mobiililaitteilla lisättäessä samalla tavoin kuin sovelluskaupasta asennetut sovellukset. Erona sovelluskaupasta asennettuun sovellukseen on se, että sovellusta lisätään menemällä sovelluksen kotisivuille ja hyväksymällä sovelluksen lisääminen aloitusnäyttöön.

Esimerkiksi Chromessa PWA-sovelluksen asennusta tarjotaan kun:

käyttäjä on napauttanut sivulla vähintään kerran,
käyttäjä on ollut sivulla vähintään 30 sekuntia,
sivusto jaetaan HTTPS-protokollan kautta ja
sivustolle on määritelty manifest-tiedot.

Sovelluksen julkaisussa voidaan vaikuttaa tästä listasta kahteen viimeiseen kohtaan eli julkaistaan sivusto HTTPS-protokollaa tukevalla sivustolla ja määritellään sovellukselle vaatimukset täyttävät manifest-tiedot.

Seuraavat vaiheet mukailevat seuraavia artikkeleita:

PWA-lisäosan asennus Vite-projektiin

Aloitetaan PWA-sovelluksen määrittely sillä, että asennetaan Vite-projektiin PWA-toiminnallisuuden lisäävä lisäosa. Suorita seuraava komento projektikansiossa:

npm install -D workbox-window vite-plugin-pwa

Edellä olevassa komennossa -D asentaa paketit kehitysaikaisiksi riippuvuuksiksi (devDependencies). React-projektien kanssa tarvitaan myös workbox-window-paketti. Monissa muissa kehitysympäristöissä riittää pelkän vite-plugin-pwa-paketin asennus.

manifest.json

manifest.json ja nimensä mukaisesti JSON-muotoinen tiedosto, jossa kerrotaan web-sovelluksen tiedot, kuten esimerkiksi sovelluksen nimi ja ikonit. Virallinen määritelmä määrittelee pitkän listan asioita, jotka sovelluksesta voidaan kertoa. PWA-sovelluksessa näistä ei tarvitse määritellä kaikkia, PWA-sovelluksen kannalta pakolliset ainoastaan pakolliset tarvitsee määritellä.

Luo projektin pääkansioon (eli samaan kansioon missä on index.html-tiedosto) uusi tiedosto, anna sen nimeksi manifest.json ja liitä sen sisällöksi seuraavat rivit:

{
  "name": "Lemon Clicker",
  "short_name": "Lemonade",
  "start_url": "/",
  "scope": "/",
  "display": "standalone",
  "orientation": "portrait",
  "theme_color": "#EBEBEB",
  "background_color": "#EBEBEB"
}

name määrittelee, millä nimellä sovellus näkyy esim. sovellusvalikossa.
short_name määrittelee, millä nimellä sovellus näkyy esim. sovellusvalikoissa, jos name-määreessä oleva nimi on liian pitkä esitettäväksi.
start_url määrittelee mistä osoitteesta web-sovellus käynnistyy.
scope määrittelee missä osoiteavaruudessa sovelluksen sallitaan navigoivan. Jos käyttäjä avaa sivun, joka on scope-arvon ulkopuolella, avataan sivu normaaliin web-selainnäkymään. Esimerkkikoodin arvolla sallitaan liikkuminen domain-osoitteen sisällä.
display määrittelee näyttömoodin eli sen, kuinka paljon selaimen käyttöliittymää näytetään. standalone-arvo määrittelee sovelluksen käyttäytymään omana sovelluksena.
orientation määrittelee miten sovellusta ensisijaisesti käytetään (vaakatasossa vai pystytasossa).
theme_color määrittelee sovelluksen oletusteemavärin, tässä tapauksessa määritelty samaksi kuin sovelluksen taustaväri. Tämä vaikuttaa mm. siihen, miten järjestelmä näyttää sovelluksen.
background_color määrittelee taustavärin, jota käytetään ennen kuin sovelluksen tyylitiedosto on ehditty ladata. Tämä arvo kannattaa olla sama kuin sovelluksen tyylimääritteissä määritelty taustaväri.

Edellä lisätystä manifest.json-määrittelystä puuttuu kokonaan ikonimäärittelyt, jotka ovat PWA-sovelluksen käytön kannalta pakolliset. Niiden määrittely jätetään seuraavassa vaiheessa käytettävälle sovellukselle.

Sovelluksen ikonit

Sovelluksen ikonit ovat harvoin olemassa, vaan ne joutuu erikseen tekemässä. Haasteelliseksi ikonien teon tekee se, että niitä pitäisi olla usemapaan eri kokoa, jotta ne toimivat optimaalisesti eri laitteilla. Ikonit kannattaa tehdä joko palvelun tai sovelluksen avulla.

Tehdään ikonit käyttämällä pwa-asset-generator -sovellusta. Suorita seuraava komento projektin pääkansiossa:

npx pwa-asset-generator ./src/assets/lemon-big.svg ./public/icons -f -b "#EBEBEB" -m ./manifest.json -i 
./index.html -v /icons

Edellä oleva komento on pitkä ja se voi kopioinnin yhteydessä jakautua useammalle riville. Varmista, että annat komennon yhdellä rivillä.

Komennolle annetaan pitkä lista määritteitä, niiden merkitys on seuraava:

./src/assets/lemon-big.svg määrittelee kuvan, josta ikonit muodostetaan.
./public/icons määrittelee kansion, jonne ikonit luodaan.
-f määrittelee, että sovellukselle luodaan ja kytketään favicon-ikoni.
-b "#EBEBEB" määrittelee kuvan taustalla käytettävän taustavärin, sama kuin sovelluksen taustaväri.
-m ./manifest.json määrittelee muokattavan manifest.json-tiedoston sijainnin.
-i ./index.html määrittelee muokattavan index.html-tiedoston sijainnin.
-v /icons määrittelee ikonin linkityksissä käytettävän polun, yliajaa oletuspolun.

Suorituksen jälkeen public/icons-kansioon ilmestyi monta ikonia, manifest.json-tiedostoon lisättiin ikonimääritykset ja index.html-tiedostoon lisättiin monta ikonimääritystä.

Projektin PWA-määritykset

Seuraavaksi kytketään projektiin PWA-lisäosa sekä edellä määritellyt manifest-määritykset.

Muokkaa projektin pääkansiossa olevaa vite.config.js-tiedostoa seuraavasti:

Lisää tiedoston alkuun seuraavat import-tuonnit:

import { VitePWA } from "vite-plugin-pwa";
import manifest from './manifest.json';

Muuta defineConfig-määrittely seuraavanlaiseksi:
```
export default defineConfig({
  plugins: [react(),
            VitePWA({ manifest: manifest })],
})
```
Tämä lisää Viten PWA-lisäosan osaksi projektia ja antaa määrityksiksi aikaisemmin määrittelemämme manifest.json-määritykset.

Projektin rakentaminen

Nyt kaikki asetukset on tehty, jotta voimme rakentaa julkaistava versio (build) sovelluksesta. Tämä tapahtuu seuraavalla komennolla:

npm run build

Komennon rakentaa julkaistavan version sovelluksesta ja lopullinen versio löytyy suorituksen jälkeen projektikansion dist-kansion alta.

dist/assets-kansio sisältää kaikki src/assets-kansiosta linkitetyt tiedostot sekä sovelluksen JavaScript-koodin ja CSS-tyylimääritteet kummatkin yhteen tiedostoon koostettuna.

dist/icons-kansio sisältää kaikki public/icons-kansion alla olevat sovelluksen ikonit.

dist-kansio sisältää seuraavat tiedostot:

index.html on hyvin pitkälle sama kuin projektikansion index.html-tiedosto, build-vaiheessa siihen on lisätty linkitykset rakentamisen yhteydessä muodostettuihin tiedostoihin.
manifest.webmanifest on hyvin pitkälle sama mitä edellä defineConfig-määrittelyn kautta määriteltiin.
registerSW.js, sw.js ja workbox-xxxxxxxx.js tiedostot ovat rakentamisen yhteydessä lisättyjä tiedostoja. Ne muodostavat sovelluksen ns. Service Worker -kokonaisuuden. Service Worker on sovelluksen taustalla oleva sovelluksen osa, joka huolehtii taustalla muun muassa sovelluksen uuden version lataamisesta.

Tämä on kätevää esimerkiksi PWA-sovelluksissa, jotka on asennettu mobiililaitteelle sovelluksena. Tällöin itse sovellus käynnistyy nopeasti käyttäen sitä versiota, joka laitteen muistiin on tallennettu. Kun sovellusta käytetään, käy Service Worker taustalla lataamassa uudemman version laitteelle. Oletusmäärityksillä uutta, ladattua versiota käytetään sovelluksen seuraavalla käynnistyskerralla.

Rakennetun projektin esikatselu

Ennen kuin sovellusta lähdetään julkaisemaan, kannattaa rakennettu versio esikatsella ensin omalla laitteella. Tämä tapahtuu komennolla:

npm run preview

Tämä komento tulostaa seuraavan kaltaisen tulostuksen:

> lemon-clicker@0.0.0 preview
> vite preview

  ➜  Local:   http://localhost:4173/
  ➜  Network: use --host to expose

Komento käynnistää paikallisesti toimivan web-palvelimen, joka näkyy tulostuksen ilmoittamassa osoitteessa. Kun menet selaimella tuohon osoitteeseen, niin näet sovelluksesta sen rakennetun version.

Huomaa, että preview-toiminnolla toimiva sivusto on tarkoitettu ainoastaan rakennetun sovelluksen esikatseluun, sitä ei ole tarkoitettu julkaisumenetelmäksi.

Muutosten vienti versiohallintaan

Viedään viimeisimmät muutokset versiohallintaan.

git add .
git commit -m "lisää PWA-lisäosan ja sen määritykset"

lisää PWA-lisäosan ja sen määritykset -commit

React 101