--- order: 7 section: features title: Asset description: >- Dichiara campi asset validati con field.asset(), applica vincoli a percorsi e formati e risolvili in URL pubblici in fase di lettura. noindex: false canonicalPath: /it/docs/assets --- Scribe gestisce gli asset statici (attualmente le immagini) come riferimenti di prima classe dichiarati nello schema, anziché come semplici stringhe libere. Il principio fondamentale è che **i componenti non costruiscono mai gli URL degli asset concatenando stringhe.** Il frontmatter archivia un *riferimento di origine* canonico, mentre il runtime lo risolve nell'*URL servito* durante il caricamento. Questa singola indirezione permette di introdurre `publicPath`, CDN e content hashing tramite una semplice configurazione, evitando migrazioni del codice. रूम

Configuration

Il gruppo di configurazione `assets` dichiara dove risiedono i file di origine e come vengono serviti. L'opzione semplice `assetsDir` funziona ancora come alias deprecato per `{ dir: assetsDir }`. ```ts export default defineConfig({ // ... assets: { dir: "public", // where source files live on disk, relative to rootDir. Default "public". publicPath: "/", // URL prefix they are served under. A path ("/static/") or a CDN origin. Default "/". managedDirs: ["/blog-images"], // extra Scribe-owned web-path roots not covered by any field.asset() }, }); ``` `publicPath` segue la convenzione di webpack e Vite per questo concetto. Le voci in `managedDirs` sono **directory radice di origine**, ovvero cartelle referenziate nei corpi MDX che non sono legate a uno specifico campo asset. रूम

`field.asset()`

```ts import { field } from "scribe-cms"; const garmentSchema = z.object({ title: field.translatable(z.string()), productImage: field.asset({ dir: "/try-on/garments", // value must live under this web path formats: ["webp"], // extension allowlist maxKB: 150, // size budget (warning) optional: false, // default }), }); ``` Come per `field.relation()`, **i vincoli si trovano nell'oggetto delle opzioni e non in metodi Zod concatenati**. La concatenazione clona lo schema e perde i metadati. I campi asset sono sempre strutturali, perciò i percorsi non vengono mai inviati al traduttore. | Opzione | Tipo | Significato | | --- | --- | --- | | `dir` | `string` | Prefisso del percorso web sotto cui deve trovarsi il valore. Dichiara anche una radice gestita. | | `template` | `string` | Modello di percorso derivato, ad esempio `"/try-on/garments/{slug}/product.webp"`. `{slug}` è lo slug inglese della voce. Quando è impostato, il campo nel frontmatter può essere omesso del tutto e il loader lo compila automaticamente. Un valore esplicito sovrascrive il modello (utile per la condivisione intenzionale tra più voci). | | `formats` | `string[]` | Estensioni consentite (in minuscolo e senza punto). La violazione genera un avviso di convalida. | | `maxKB` | `number` | Limite di dimensione del file. La violazione genera un avviso di convalida. | | `optional` | `boolean` | Il campo può essere assente (ha senso solo senza `template`). Se il valore è presente ma il file manca, si verifica comunque un errore. | Il valore nel frontmatter è un **percorso web relativo alla radice** all'interno di `assets.dir`, come ad esempio `/try-on/garments/denim-flare/product.webp`. Segue la stessa convenzione di una normale stringa per un'immagine e non usa nuovi schemi URI. Su disco, il frontmatter archivia il riferimento di origine (o nulla, se usa un modello). Gli URL risolti esistono solo nell'output a runtime. Le esportazioni statiche o grezze e il traduttore vedono sempre e solo i valori di origine. रूम

Loader resolution

Quando il runtime carica un documento, analizza lo schema alla ricerca di campi asset e per ciascuno di essi: 1. Se il valore nel frontmatter è assente e il campo ha un `template`, materializza il percorso basandosi su di esso (`{slug}` diventa lo slug inglese). 2. Aggiunge il prefisso `assets.publicPath` (unito senza doppie barre. È supportato un `publicPath` con origine assoluta). In questo modo, chi consuma i dati ottiene gli URL finali senza dover effettuare chiamate aggiuntive: ```ts const garment = scribe.garment.get("denim-flare"); garment.frontmatter.productImage; // "/try-on/garments/denim-flare/product.webp" (publicPath "/") // "https://cdn.example.com/try-on/garments/denim-flare/product.webp" (CDN publicPath) ``` La risoluzione avviene dopo che i campi strutturali sono stati uniti ai documenti localizzati. Questo garantisce che ogni lingua riceva i valori risolti dall'origine inglese. रूम

`scribe.assets.url(ref)`

Una soluzione di emergenza per le immagini nel corpo MDX e per i casi ad hoc. Applica `publicPath` a un riferimento grezzo: ```ts scribe.assets.url("/blog-images/hero.webp"); // publicPath applied ``` Puoi anche fare riferimento agli asset direttamente nei corpi MDX usando il [token inline `asset`](/docs/inline-tokens), che viene risolto nello stesso modo in fase di lettura. रूम

Validation

`scribe validate` controlla i campi asset dichiarati: - **File mancante per un campo asset obbligatorio**: restituisce un errore e blocca la build (proprio come una relazione obbligatoria interrotta). - **File mancante per un campo `optional` con un valore presente**: restituisce comunque un errore. `optional` significa solo che il *campo* può essere omesso, non che un percorso dichiarato possa essere falso. - **Valore esterno alla `dir` del campo**: errore. - **Estensione non inclusa in `formats`**: avviso. - **File più grande di `maxKB`**: avviso. - I campi basati su modello convalidano il percorso *materializzato*. Il file deve esistere anche se il frontmatter omette il valore. I messaggi indicano l'attribuzione del campo, ad esempio `garment/denim-flare: productImage → /try-on/garments/denim-flare/product.webp not found`. Separatamente, le stringhe con l'aspetto di un'immagine raccolte in modo euristico dal frontmatter e dai corpi MDX vengono comunque segnalate come avvisi se mancanti. Questo garantisce la copertura delle immagini nei contenuti senza richiedere alcuna migrazione. रूम

Studio

Lo [studio](/docs/studio) mostra gli asset in sola lettura: - **L'inspector delle voci** esegue il rendering dei campi asset come anteprime dell'immagine con l'URL risolto, le dimensioni del file e la risoluzione. Un file mancante viene segnalato da un badge rosso. - **Il browser degli asset** (`/assets`) mostra una griglia di miniature per ogni radice gestita. Ogni asset è accompagnato dal relativo percorso, dimensione, risoluzione e un elenco "referenziato da" per ogni voce e campo che punta ad esso. Appositi badge segnalano gli asset non referenziati (potenziali orfani), mancanti ma referenziati, troppo pesanti e con formati non conformi. - **La visualizzazione galleria** permette a qualsiasi tipo dotato di un campo asset di mostrare il proprio elenco di voci come una griglia di schede, offrendo uno strumento di controllo qualità visivo per le immagini generate.