Tässä artikkelissa perehdytään AI Commercen frontend-kansiorakenteeseen, kehitysympäristöön ja siihen, miten hyödynnetään yhteistä koodipohjaa useille kaupoille. Artikkelin tavoitteena on antaa integraatiopartnereille selkeä käsitys siitä, miten frontend on järjestetty ja mitä tiedostoja sekä dev dependencies -paketteja projektissa käytetään.

Noudattamalla alla olevia ohjeita voit hallita tehokkaammin AI Commercen käyttöliittymän kehitystä, ymmärtää versiohallinnan periaatteita ja varmistaa, että koodi pysyy turvallisena ja helposti ylläpidettävänä.

Frontendin tiedostorakenne ja keskeiset hakemistot

• /assets/ – Tiedostot, jotka tulevat projektin juureen, kuten robots.txt ja favicon.ico. Tuotantoon siirtyessä noindex on poistettava robots.txt-tiedostosta.
• /dist/ – Viten ja AI Commercen SSR-pluginin generoimat JS- ja CSS-tiedostot, jotka päätyvät S3:een ja Lambdaan.
• /node_modules/ – Kolmannen osapuolen kirjastot, listattuna package.json-tiedostossa. Uusia kirjastoja lisätään vain Code Ownerin toimesta.
• /src/ – Varsinainen sovelluskoodi:
  • /src/app – Frontendin ydintoiminnallisuudet, esim. router, evästeet ja muut harvemmin päivitettävät koodit.
  • /src/ext – Kolmansien osapuolien skriptit, muun muassa chattien ja Builderion kaltaisten upotusten koodit, jotka on konvertoitu AI Commercen ympäristöön sopiviksi.
  • /src/lib/ – Toiminnallisuuksia, joita voidaan muokata kauppakohtaisesti. Esimerkkinä Configuration.js, jossa määritellään esimerkiksi logoRatio.
  • /src/modals/ – Erilaisia uudelleenkäytettäviä modaalikomponentteja.
  • /src/pages/ – Sovelluksen sivutiedostot (routing), joilla luodaan esimerkiksi /product/[slug] -tyyppisiä dynaamisia polkuja.
  • /src/popups/ – Erilaiset popup-komponentit.
  • /src/renderer/ – Palvelinpään renderöintiin (SSR) liittyvät tiedostot kuten App.svelte, +onBeforeRender.js, +onRenderHtml.js ja +onRenderClient.js.
  • /src/ssr/ – AI Commercen omat SSR-tiedostot, jotka on tarkoitettu kevyeksi palvelinpään renderöintiratkaisuksi.
  • /src/styles/ – Tyylitiedostot (global.css, dynamic.css, common.css). Suositus on pitää suurin osa tyyleistä komponenttikohtaisina, mutta esimerkiksi yleiset HTML- tai dynaamiset sisällöt kannattaa tyylitellä näissä tiedostoissa.

Dev-dependencies ja niiden tarkoitus

Projektissa käytetään vain välttämättömiä kirjastoja, jotka on lukittu package.json-tiedostoon. Näin varmistetaan koodin turvallisuus ja tehokkuus. Vain Code Ownerit voivat päivittää tai lisätä uusia kirjastoja. Seuraavat paketit löytyvät package.jsonin devDependencies-osiosta:

• @sveltejs/vite-plugin-svelte (3.1.1) – Mahdollistaa Svelte-komponenttien käytön Vite-projektissa.
• cross-env (7.0.3) – Alustariippumaton ympäristömuuttujien asetus.
• dotenv (16.4.5) – Lataa .env-tiedoston muuttujat process.env:iin build- tai ajon aikana.
• eslint (^9.14.0) – Lint-työkalu JavaScript/TypeScript-koodiin.
• eslint-plugin-svelte (2.46.0) – ESLint-tuki Svelte-tiedostoille.
• sass (^1.86.3) – SCSS-/Sass-tiedostojen kääntäjä CSS:ksi.
• serverless-prune-plugin (2.1.0) – Serverless-laajennus vanhojen deploy-versioiden poistamiseen AWS:ssä.
• svelte (4.2.19) – Svelte-kirjasto kehitysvaiheessa, käännetään buildin yhteydessä.
• svelte-preprocess (^6.0.3) – Mahdollistaa esimerkiksi SCSS:n ja TypeScriptin käytön .svelte-tiedostoissa.
• vite-plugin-compression (0.5.1) – Lisää gzip- tai brotli-pakkauksen buildattuihin tiedostoihin.
• vite-plugin-dynamic-import (1.5.0) – Dynaamiset importit Vite-projekteissa (esim. lazy load -routet).

.env.local

Ympäristömuuttujia säilytetään .env.local-tiedostossa. Täällä määritellään esimerkiksi yhteyspisteet backendille ja kuvapalvelimille. VITE_-prefiksillä merkityt muuttujat ovat näkyvillä myös selaimessa, joten älä tallenna niihin arkaluontoista dataa.

• VITE_BACKEND_HOST – Backendin host-nimi (esim. localhost tai boeing.com).
• VITE_DEV_IMAGE_URL – CDN- tai kuvapalvelimen osoite, josta kuvat ladataan kehitysympäristössä.
• VITE_LANGUAGE_CODE – Oletuskielen kielikoodi (esim. fi). Käytetään route-mappien valitsemiseen.

Linterit ja muut konfiguraatiot

eslint.config.js määrittelee lintersäännöt, joilla koodi pidetään yhtenäisenä ja mahdolliset virheet tai käyttämättömät muuttujat paljastetaan ajoissa. Muuta konfiguraatiota hallitaan tiedostoissa serverless.yml ja vite.config.*.js, jotka ovat AI Commercen ydintiimin ylläpitämiä ja lukittu Code Ownerien taakse.

Kieliversioiden hallinta

languageMap.js, routeMap.js, routeMapGenerator.js, routeTranslations.js ja routeTranslator.js vastaavat kielikohtaisista reittikartoista. Uusien kielten lisääminen tapahtuu AI Commercen toimesta, jolloin valmiit kartat ja reittimäärittelyt jaetaan kaikille kaupoille automaattisesti.

S3Fallback ja reitityksen varmuusratkaisut

s3Fallback.js käsittelee niitä tapauksia, joissa haetulle reitille ei löydy suoraa vastausta. Ensin tarkistetaan, löytyykö polulle reitti front-endistä. Jos ei, koitetaan uudelleen S3-tasolla. Mikäli reittiä ei sieltäkään löydy, palautetaan HTTP 404 -koodi. Tällä turvataan mm. Googlelle oikeanlainen statuskoodi sivuja indeksöitäessä.

Yhteenveto

AI Commercen frontend noudattaa selkeää kansiorakennetta, joka helpottaa eri kauppojen ylläpitoa ja uudelleenkäyttöä. Kaikki yleiset parannukset ja bugikorjaukset tehdään ensisijaisesti main-haaraan, josta ne valuvat automaattisesti eri kaupoille. Dev dependencies on pidetty minimissä, jotta projekti on kevyt, turvallinen ja helppo päivittää. Toivottavasti tämä ohje auttaa ymmärtämään, miten voit työskennellä tehokkaasti AI Commercen frontendin parissa.