Questa pagina è stata tradotta dall'API Cloud Translation.

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 negli strumenti di Baseline, ora puoi utilizzare Baseline direttamente nei tuoi progetti come query Browserslist, in modo che la tua toolchain possa modificare l'output del codice in base al target Baseline che scegli.

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

2. Configura la demo sulla tua macchina locale

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

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

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 94f12e34

Una volta clonato il repository, è possibile avviare la demo. Questo progetto utilizza nvm per gestire il controllo delle versioni di Node. Se hai installato una versione ragionevolmente recente di Node a livello globale, probabilmente non devi completare questo passaggio. Tuttavia, 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 questo comando:

npm start

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

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 di Browserslist all'inizio. Browserslist è una sintassi di query compatta che indica alle toolchain le versioni minime dei browser che devono essere supportate. Ad esempio, l'utilizzo di una query di last 3 years specificherà un'ampia gamma di target. In questa demo utilizzeremo un pacchetto npm denominato browserslist-config-baseline per specificare una query Browserslist che sia in linea con i target Baseline che puoi utilizzare nella tua toolchain.

Per iniziare, installa browserslist-config-baseline nel seguente modo:

npm install browserslist-config-baseline --save-dev

Una volta installato, questo pacchetto ti consente di specificare una query extends Browserslist nel tuo progetto che viene risolta in un elenco di browser di base. Questi target di base possono essere uno dei seguenti:

Target dinamici, che vengono aggiornati nel tempo man mano che vengono rilasciati nuovi browser:
- Baseline Newly available, che allinea le funzionalità interoperabili implementate nei browser principali in qualsiasi momento dal presente a 30 mesi fa.
- Baseline ampiamente disponibile, che include funzionalità interoperabili implementate nei browser principali da almeno 30 mesi.
Target fissi, che rappresentano le versioni del browser in un momento fisso. Questi valori sono espressi in anni dal 2016 all'anno corrente.

Per iniziare, utilizzeremo browserslist-config-baseline per selezionare il target di base mobile ampiamente disponibile per il progetto. Per farlo, apri package.json e aggiungi quanto segue:

"browserslist": "extends browserslist-config-baseline"

4. Osserva le modifiche nell'output del codice selezionando target di base diversi

Hai appena selezionato la base di riferimento ampiamente disponibile come target per il progetto dimostrativo. A questo punto, devi creare il progetto:

npm run build

C'è molto output aggiuntivo perché l'opzione debug per @babel/preset-env è specificata come true in babel.config.js del progetto. Innanzitutto, annota le 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. Perché questo 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 che autoprefixer sono interessati da browserslist-config-baseline.

Un altro aspetto dell'output a cui prestare attenzione è il modo in cui la query Browserslist per Baseline Widely available viene tradotta in una query Browserslist. Nel tuo progetto, sarà simile a questo:

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

Nota i polyfill inseriti da core-js nell'output della 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 base. Supponiamo che la tua applicazione debba supportare un insieme di browser molto meno recenti a causa di uno SLA più rigoroso. Se questo fosse il tuo caso, probabilmente selezioneresti un target più conservativo. Nel file package.json, modifica la configurazione di Browserslist in modo che rifletta quanto segue:

"browserslist": "extends browserslist-config-baseline/2016"

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

npm run build

Innanzitutto, 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 all'aggiunta di altri prefissi del fornitore da parte di autoprefixer in base al target di riferimento del 2016. Tieni presente anche la modifica alla query Browserslist:

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

Rispetto alla destinazione Baseline ampiamente disponibile, queste versioni del browser sono molto, molto precedenti, tanto che la versione di Edge a cui viene fatto riferimento in questo caso è pre-Chromium.

Anche i polyfill inseriti da core-js cambieranno, il che è molto più di quando è stata selezionata la base di riferimento ampiamente disponibile 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 base può avere un impatto significativo sulla trasformazione dell'applicazione da parte della toolchain del progetto. L'applicazione in questo esempio è molto semplice e non include molte funzionalità all'avanguardia per l'esperienza degli sviluppatori in React o nell'applicazione stessa. Per applicazioni molto più complesse, potresti aspettarti risultati molto diversi, forse anche più in termini di polyfill, trasformazioni e altre fonti di codice aggiuntivo per conformarsi al target Baseline che scegli.

5. Targeting dei browser downstream con browserslist-config-baseline

Per riepilogare, il set di browser principale a cui si rivolge 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 i cosiddetti "browser downstream". Questi browser sono quelli i cui motori derivano da un browser nel set di browser principali, il più delle volte Chromium. tra cui Opera, Samsung Internet e altri. Puoi configurare browserslist-config-baseline per il targeting nel file package.json nel seguente modo:

"browserslist": "extends browserslist-config-baseline/with-downstream"

Questo ha come target i browser downstream in conformità al target Baseline ampiamente disponibile. Per vedere come viene risolta una query Browserslist, ricompila il progetto:

npm start

Quindi, annota la modifica nella 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": "extends browserslist-config-baseline/with-downstream/2016"

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

browserslist-config-baseline è uno strumento pratico per i bundler e altre parti della toolchain, ma anche altri strumenti, come i linter che hanno adottato i target di base come parte della loro configurazione, sono utili.

Un buon esempio di supporto di Linter per Baseline include ESLint, che, nell'ambito del linting CSS, fornisce una regola use-baseline che utilizza @eslint/css e consente di scegliere come target Baseline Newly, Baseline Widely available o Baseline years. Nel pacchetto della community @html-eslint/eslint-plugin è presente anche una regola simile che ti consente di fare lo stesso per le funzionalità HTML nel file eslint.config.js:

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"
      }]
    }
  }
];

Ci sono alcuni aspetti da notare in questa configurazione:

Entrambi i pacchetti di linting HTML e CSS utilizzano una regola use-baseline ed è impostata su Disponibile su larga scala utilizzando l'opzione di configurazione available: "widely".
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 in precedenza, ma per visualizzare l'output del linter da solo, puoi eseguire il seguente comando:

npm run lint

L'output visualizzato 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

Come puoi vedere, l'utilizzo di browserslist-config-baseline nel tuo progetto richiede una certa conoscenza degli strumenti di compilazione e di Browserslist sottostanti, ma l'inserimento nei tuoi progetti dovrebbe essere possibile con un po' di lavoro. Il vantaggio principale del suo utilizzo è che non devi più pensare ai browser che supporti in termini di numeri di versione, ma piuttosto a un target di base che fa il lavoro più 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 base sta iniziando a essere visualizzato anche in altri strumenti di bundling. Ad esempio, Vite, che utilizza Rollup in background, ora ha come target per impostazione predefinita i browser Baseline ampiamente disponibili a partire dalla versione 7.

Indipendentemente dal modo in cui decidi di procedere, l'introduzione di browserslist-config-baseline nella toolchain del tuo progetto e la selezione di un target di base adatto a te ti consentono di scegliere come target i browser in modo più semplice e affidabile.