0Pricing
TypeScript Academy · Lezione

Strategia per un pacchetto di tipi condivisi

Crei un pacchetto types dedicato, utilizzabile in tutto il monorepo.

Strategia per un pacchetto di tipi condivisi è una lezione TypeScript Academy gratuita su CoddyKit. Questa è la lezione 3 di 4. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento TypeScript Academy, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso TypeScript Academy include 4 lezioni in totale.

Perché usare un pacchetto di tipi condiviso?

La condivisione dei tipi tra frontend e backend elimina le divergenze tra i contratti dell'API. Un'unica fonte di verità consente di rilevare errori in fase di compilazione quando cambia la struttura dell'API.

// packages/types/src/index.ts
export interface User { id: string; name: string; email: string; }
export interface ApiResponse<T> { data: T; error?: string; }

Struttura del pacchetto

Mantenga il pacchetto dei tipi essenziale: solo esportazioni di tipi, senza logica di runtime. In questo modo il pacchetto non produce effetti collaterali ed è compatibile con il tree shaking.

packages/types/
├── src/
│   ├── index.ts      # re-exports all
│   ├── user.ts
│   ├── product.ts
│   └── api.ts
├── tsconfig.json
└── package.json

tsconfig per un pacchetto di tipi

Abiliti emitDeclarationOnly per non generare JavaScript: solo file .d.ts a cui fanno riferimento i consumer.

{
  "compilerOptions": {
    "composite": true,
    "declaration": true,
    "emitDeclarationOnly": true,
    "outDir": "./dist",
    "rootDir": "./src"
  }
}

Utilizzo del pacchetto di tipi

Faccia riferimento al pacchetto dei tipi sia nell'API sia nell'app web e importi i tipi con import type per evitare overhead a runtime.

import type { User, ApiResponse } from "@myapp/types";

async function getUser(id: string): Promise<ApiResponse<User>> {
  // ...
}

Mantenimento della sicurezza di serializzazione dei tipi

I tipi condivisi tra client e server dovrebbero includere solo valori serializzabili in JSON. Eviti gli oggetti Date e utilizzi invece string (ISO).

// Good: serialization-safe
interface Event { id: string; createdAt: string; /* ISO date */ }
// Bad: Date is not JSON-serializable
interface Event { id: string; createdAt: Date; }

Versionamento del pacchetto di tipi

Applichi il versionamento semantico al pacchetto dei tipi. Una modifica incompatibile, come la rimozione o la ridenominazione di un campo, richiede un incremento della versione major.

# Breaking change: major bump
npm version major
# Adding optional fields: minor bump
npm version minor

Generazione dei tipi da OpenAPI

Automatizzi il pacchetto dei tipi generandolo da una specifica OpenAPI con openapi-typescript. In questo modo i tipi corrispondono sempre al backend.

npx openapi-typescript ./api/openapi.yaml -o ./packages/types/src/api.ts

Utilizzo di Zod per i tipi a runtime e in fase di compilazione

Definisca i tipi con gli schemi Zod e ricavi da essi i tipi TypeScript. La validazione a runtime e i tipi statici provengono entrambi dalla stessa fonte.

import { z } from "zod";
export const UserSchema = z.object({ id: z.string(), name: z.string() });
export type User = z.infer<typeof UserSchema>;

Come evitare le dipendenze circolari

Il pacchetto dei tipi non dovrebbe importare altri pacchetti del workspace, per evitare catene di dipendenze circolari. Lo mantenga come nodo foglia nel grafo delle dipendenze.

// types/ should not import from ui/ or api/
// ui/ and api/ both import from types/

Verifica della correttezza dei tipi

Utilizzi tsd per scrivere asserzioni a livello di tipo che verifichino la conformità dei tipi condivisi alle aspettative.

import { expectType } from "tsd";
import type { User } from "@myapp/types";
expectType<User>({ id: "1", name: "Alice", email: "a@b.com" });

Riepilogo: strategia per i tipi condivisi

Un pacchetto di tipi condiviso elimina le divergenze dell'API: genera solo dichiarazioni, mantiene i tipi serializzabili in JSON, applica il versionamento semantico, può essere generato automaticamente da OpenAPI e viene testato con tsd.

Verifica rapida

Perché i tipi condivisi dell'API dovrebbero usare string invece di Date?

Che cosa ha imparato

Un pacchetto di tipi condiviso è un'unica fonte di verità per i contratti dell'API. Lo mantenga limitato alle dichiarazioni, sicuro per JSON e versionato con semver; può inoltre generarlo da OpenAPI per eliminare le divergenze tra frontend e backend.

Domande Frequenti

La lezione «Strategia per un pacchetto di tipi condivisi» è gratuita?

Sì — il testo completo di «Strategia per un pacchetto di tipi condivisi» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso TypeScript Academy, passa a CoddyKit PRO. Il corso TypeScript Academy include 4 lezioni in totale.

Cosa imparerò in «Strategia per un pacchetto di tipi condivisi»?

Crei un pacchetto types dedicato, utilizzabile in tutto il monorepo. Eserciti TypeScript Academy con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.

Ho bisogno di esperienza per iniziare TypeScript Academy?

Non è richiesta alcuna esperienza precedente. TypeScript Academy su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 3 di 4.

Quanto tempo richiede la lezione «Strategia per un pacchetto di tipi condivisi»?

La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.

Posso scrivere ed eseguire codice in questa lezione TypeScript Academy?

Sì. Ogni lezione TypeScript Academy include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.

Tutte le lezioni di questo corso

  1. Riferimenti ai progetti TypeScript
  2. Workspace pnpm con TypeScript
  3. Strategia per un pacchetto di tipi condivisi
  4. Build incrementali e cache nei monorepo
← Torna a TypeScript Academy