Come utilizzare la baseline nel tuo progetto

1. Introduzione

Baseline è un'iniziativa che fornisce messaggi più chiari sulle funzionalità web interoperabili e sicure da utilizzare oggi. Grazie ai progressi degli strumenti di Baseline, ora puoi utilizzare Baseline direttamente nei tuoi progetti come query Browserslist, in modo che la toolchain possa modificare l'output del codice in base al target di Baseline che scegli.

In questo codelab imparerai a utilizzare Baseline in un progetto di esempio e a configurarlo per selezionare un target di Baseline specifico. Potrai anche osservare come cambia l'output della toolchain del progetto a seconda del target di Baseline selezionato.

2. Configurare la demo sulla macchina locale

Per prima cosa, vai all'applicazione terminale che preferisci, clona il repository della demo e poi inserisci la directory del progetto:

git clone git@github.com:GoogleChromeLabs/baseline-demos.git
cd baseline-demos/tooling/webpack

A questo punto, la demo avrà già integrato Baseline, ma ti consigliamo di dare un'occhiata a un commit che ti consenta di iniziare da zero:

git checkout d3793f25

Una volta clonato il repository, la demo può essere avviata. Questo progetto utilizza nvm per gestire il controllo delle versioni di Node. Se hai installato a livello globale una versione di Node relativamente recente, probabilmente non devi completare questo passaggio, ma se utilizzi nvm, esegui i seguenti comandi:

nvm install
nvm use

Da qui, installa i pacchetti del progetto:

npm install

Se vuoi vedere la demo, esegui il seguente comando:

npm start

Poi vai a http://localhost:8080. La demo è un elenco di schede filtrabili utilizzando un campo modulo nella parte superiore della pagina. L'app stessa utilizza un mix di funzionalità che hanno raggiunto una soglia di Baseline.

Al termine della demo, vai al terminale e premi Ctrl+C per interrompere l'esecuzione della demo in qualsiasi momento.

3. Come integrare Baseline nel progetto

Questa demo non specifica una configurazione Browserslist all'inizio. Browserslist è una sintassi di query compatta che indica alle toolchain quali versioni minime del browser devono essere supportate. Ad esempio, l'utilizzo di una query di last 3 years specificherà un'ampia gamma di target. In questa demo, specificheremo una query Browserslist che si allinea ai target di Baseline che puoi utilizzare nella tua toolchain. I target di Baseline possono essere di uno dei seguenti tipi:

  • Target in movimento, che si aggiornano nel tempo man mano che vengono rilasciati nuovi browser:
    • Baseline Newly available, che allinea le funzionalità interoperabili implementate nel set di browser principali in qualsiasi momento dal presente a 30 mesi fa.
    • Baseline Widely available, che include le funzionalità interoperabili implementate nel set di browser principali da 30 o più mesi fa.
  • Target fissi, che rappresentano le versioni del browser in un punto fisso nel tempo. Questi sono espressi come anni dal 2016 all'anno corrente.

Per iniziare, selezioneremo il target di Baseline Widely available in movimento per il progetto. Per farlo, apri package.json e aggiungi quanto segue:

"browserslist": "baseline widely available"

4. Osservare le modifiche nell'output del codice selezionando target di Baseline diversi

Hai appena selezionato Baseline Widely available come target per il progetto demo. Poi, dovrai creare il progetto:

npm run build

C'è un sacco di output aggiuntivo perché l'opzione debug per @babel/preset-env è specificata come true in babel.config.js del progetto. Per prima cosa, prendi nota delle dimensioni di CSS e JavaScript nelle statistiche del bundler:

assets by status 213 KiB [emitted]
  asset js/home.5f3c5480.js 208 KiB [emitted] [immutable] [minimized] (name: home) 2 related assets
  asset css/home.20db50ef.css 3.64 KiB [emitted] [immutable] (name: home) 1 related asset
  asset index.html 564 bytes [emitted]

Tieni presente che il bundle JavaScript è 208 KiB e il CSS è 3, 64 KiB. Questo perché il progetto utilizza core-js per i polyfill JavaScript e autoprefixer per applicare prefissi specifici del fornitore per le proprietà CSS che non sono ancora completamente interoperabili. Sia core-js sia autoprefixer sono interessati dalla query Browserslist di Baseline selezionata.

Un'altra cosa da tenere presente nell'output è il modo in cui la query Browserslist per Baseline Widely available viene tradotta in una query Browserslist. Nel tuo progetto, sarà simile a questa:

Using targets: {
  "chrome": "108",
  "edge": "108",
  "firefox": "108",
  "ios": "16",
  "safari": "16"
}

Prendi nota dei polyfill inseriti da core-js nell'output di build:

The corejs3 polyfill added the following polyfills:
  es.iterator.constructor { "chrome":"108", "edge":"108", "firefox":"108", "ios":"16", "safari":"16" }
  es.iterator.filter { "chrome":"108", "edge":"108", "firefox":"108", "ios":"16", "safari":"16" }
  es.iterator.map { "chrome":"108", "edge":"108", "firefox":"108", "ios":"16", "safari":"16" }

Questo output può cambiare se modifichi il target di Baseline. Supponiamo che la tua applicazione debba supportare un set di browser molto più vecchio a causa di uno SLA più rigoroso. In questo caso, probabilmente selezioneresti un target più conservativo. Nel file package.json, modifica la configurazione di Browserslist in modo che rifletta quanto segue:

"browserslist": "baseline 2016"

In questo modo viene selezionato Baseline 2016 come target e verrà tradotto in una query Browserslist. Puoi notare le differenze nell'output della toolchain dopo aver eseguito di nuovo la build:

npm run build

Per prima cosa, prendi nota della modifica delle dimensioni dei file JavaScript e CSS del progetto nelle statistiche del bundler:

assets by status 237 KiB [emitted]
  asset js/home.b228612d.js 232 KiB [emitted] [immutable] [minimized] (name: home) 2 related assets
  asset css/home.0c3e4fd7.css 3.91 KiB [emitted] [immutable] (name: home) 1 related asset
  asset index.html 564 bytes [emitted]

Noterai che le dimensioni del bundle JavaScript sono aumentate di quasi 30 KiB. Il CSS del progetto è solo leggermente più grande, grazie a autoprefixer che aggiunge più prefissi del fornitore in base al target di Baseline 2016. Prendi nota anche della modifica della query Browserslist:

Using targets: {
  "chrome": "53",
  "edge": "14",
  "firefox": "49",
  "ios": "10",
  "safari": "10"
}

Rispetto al target di Baseline Widely available, queste versioni del browser sono molto, molto precedenti, abbastanza da far sì che la versione di Edge scelta come target in questo caso sia pre-Chromium.

Anche i polyfill inseriti da core-js cambieranno, molto di più rispetto a quando è stato selezionato Baseline Widely available come target:

The corejs3 polyfill added the following polyfills:
  es.array.filter { "edge":"14" }
  es.iterator.constructor { "chrome":"53", "edge":"14", "firefox":"49", "ios":"10", "safari":"10" }
  es.iterator.filter { "chrome":"53", "edge":"14", "firefox":"49", "ios":"10", "safari":"10" }
  es.object.to-string { "edge":"14", "firefox":"49" }
  es.array.includes { "firefox":"49" }
  es.string.includes { "edge":"14" }
  es.array.map { "firefox":"49" }
  es.iterator.map { "chrome":"53", "edge":"14", "firefox":"49", "ios":"10", "safari":"10" }
  es.symbol { "edge":"14", "firefox":"49" }
  es.symbol.description { "chrome":"53", "edge":"14", "firefox":"49", "ios":"10", "safari":"10" }
  es.array.iterator { "chrome":"53", "edge":"14", "firefox":"49" }
  web.dom-collections.iterator { "chrome":"53", "edge":"14", "firefox":"49", "ios":"10", "safari":"10" }
  es.array.push { "chrome":"53", "edge":"14", "firefox":"49", "ios":"10", "safari":"10" }
  es.regexp.to-string { "edge":"14" }
  es.array.from { "edge":"14", "firefox":"49" }
  es.regexp.exec { "chrome":"53", "edge":"14", "firefox":"49", "ios":"10", "safari":"10" }
  es.regexp.test { "edge":"14" }
  es.error.cause { "chrome":"53", "edge":"14", "firefox":"49", "ios":"10", "safari":"10" }

Il punto chiave è che il target di Baseline può avere un impatto significativo sul modo in cui la tua applicazione viene trasformata dalla toolchain del progetto. L'applicazione in questo esempio è molto semplice, con poche funzionalità di esperienza di sviluppo all'avanguardia in React o nell'applicazione stessa. Per applicazioni notevolmente più complesse, potresti aspettarti risultati molto diversi, forse anche più polyfill, trasformazioni e altre origini di codice aggiuntivo per conformarsi al target di Baseline che scegli.

5. Targeting dei browser downstream

Per riepilogare, il set di browser principali che include i target di Baseline include i seguenti browser:

  • Chrome
  • Chrome su Android
  • Firefox
  • Firefox su Android
  • Edge
  • Safari su macOS
  • Safari su iOS

Tuttavia, puoi scegliere come target quelli che sono noti come "browser downstream". Questi browser sono quelli i cui motori derivano da un browser nel set di browser principali, il più delle volte Chromium. Sono inclusi browser come Opera, Samsung Internet e altri. Puoi scegliere come target questi browser oltre a quelli del set di browser principali aggiungendo with downstream a qualsiasi query Browserslist di Baseline valida:

"browserslist": "baseline widely available with downstream"

In questo modo, i browser downstream vengono scelti come target in base al target di Baseline Widely available. Per vedere come viene risolta una query Browserslist, ricrea il progetto:

npm start

Poi prendi nota della modifica della query Browserslist:

Using targets: {
  "android": "108",
  "chrome": "108",
  "edge": "108",
  "firefox": "108",
  "ios": "16",
  "opera": "94",
  "opera_mobile": "80",
  "safari": "16",
  "samsung": "21"
}

Puoi anche scegliere come target i browser downstream per anno. Ad esempio:

"browserslist": "baseline 2016 with downstream"

Con questa configurazione, la query Browserslist cambierà di conseguenza:

Using targets: {
  "android": "53",
  "chrome": "53",
  "edge": "14",
  "firefox": "49",
  "ios": "10",
  "opera": "40",
  "opera_mobile": "80",
  "safari": "10",
  "samsung": "6.2"
}

6. Linter e altri strumenti

Le query di Baseline integrate in Browserslist sono utili per strumenti come i bundler e altre parti della toolchain, ma anche altri strumenti, come i linter, che hanno adottato i target di Baseline come parte della loro configurazione, sono utili.

Un buon esempio di supporto del linter per Baseline include ESLint, che, come parte del linting CSS, fornisce una use-baseline regola utilizzando @eslint/css che consente di scegliere come target Baseline Newly, Baseline Widely available o gli anni di Baseline. Esiste anche una regola simile nel pacchetto della community @html-eslint/eslint-plugin che consente di fare lo stesso per le funzionalità HTML nel file eslint.config.js file:

export default [
  /* Omitted JS linting rules ... */
  // Lint CSS files for Baseline:
  {
    files: ["**/*.css"],
    plugins: {
      css
    },
    language: "css/css",
    rules: {
      "css/no-duplicate-imports": "error",
      // Lint CSS files to make sure they are using
      // only Baseline Widely available features:
      "css/use-baseline": ["warn", {
        available: "widely"
      }]
    },
  },
  // Lint HTML and JSX files for Baseline:
  {
    files: ["**/*.html"],
    ...html.configs["flat/recommended"],
    rules: {
      // Lint HTML files to make sure they are using
      // only Baseline Widely available features:
      "@html-eslint/use-baseline": ["warn", {
        available: "widely"
      }]
    }
  }
];

In questa configurazione ci sono alcune cose da notare:

  1. Entrambi i pacchetti di linting HTML e CSS utilizzano una regola use-baseline ed è impostata su Widely available utilizzando l'opzione di configurazione available: "widely".
  2. Per entrambi i pacchetti di linting, il livello di log per le violazioni del linter è impostato su "warn". Può essere impostato su "error" per uscire con un codice di errore per impedire la creazione di una build.

Potresti aver visto l'output del linter durante l'esecuzione di npm run build, ma per vedere l'output del linter da solo, puoi eseguire quanto segue:

npm run lint

L'output che vedrai evidenzia diversi avvisi nel CSS del progetto:

/var/www/baseline-demos/tooling/webpack-browserslist-config-baseline/src/css/normalize.css
  222:3  warning  Property 'outline' is not a widely available baseline feature  css/use-baseline

/var/www/baseline-demos/tooling/webpack-browserslist-config-baseline/src/css/styles.css
  62:3   warning  Property 'outline' is not a widely available baseline feature                                css/use-baseline
  81:23  warning  Value 'subgrid' of property 'grid-template-rows' is not a widely available baseline feature  css/use-baseline

7. In sintesi

L'utilizzo delle query di Baseline fornite da Browserslist nel tuo progetto richiede una certa comprensione degli strumenti di build sottostanti e di Browserslist stesso, ma l'atto di inserirle in un progetto è conciso. Il vantaggio principale del suo utilizzo è che non devi più pensare ai browser supportati in termini di numeri di versione, ma piuttosto a un target di Baseline che fa il lavoro pesante per te.

Inoltre, esiste una versione di questa demo che viene eseguita su Rollup e questo codelab può essere seguito in gran parte anche utilizzando questa demo.

Il supporto di Baseline sta iniziando a comparire anche in altri strumenti di bundling. Vite, ad esempio, che utilizza Rollup sotto il cofano, ora sceglie come target i browser Baseline Widely available per impostazione predefinita dalla versione 7.

In qualsiasi modo tu decida di procedere, introducendo le query di Baseline disponibili in Browserslist nel tuo progetto e selezionando un target di Baseline adatto a te, puoi scegliere come target i browser in modo più semplice e affidabile.