Referencias de proyectos en TypeScript

Las referencias de proyectos son una función que TypeScript ofrece para organizar proyectos grandes, permitiendo dividir un proyecto de TypeScript en partes más pequeñas.

Permite lograr compilación incremental, una mejor organización del código y una velocidad de compilación más rápida.


Diagrama SVG: principio de funcionamiento de las referencias de proyectos Fondo Título Principio de las referencias de proyectos Proyecto principal Proyecto principal (app) package.json tsconfig.json references: [...] Flecha Proyecto referenciado 1 Biblioteca de componentes (ui) Button, Modal, Input Proyecto referenciado 2 Biblioteca de utilidades (utils) formatDate, request Proyecto referenciado 3 Definiciones de tipos (types) User, API Response Marca de flecha

Por qué se necesitan las referencias de proyectos

A medida que el proyecto crece, un único tsconfig.json puede hacer que la compilación sea más lenta.

Las referencias de proyectos permiten dividir el proyecto en subproyectos independientes, cada uno de los cuales puede compilarse de forma independiente.

Esto no solo mejora la velocidad de compilación, sino que también proporciona una mejor manera de organizar el código.

Concepto:Las referencias de proyectos permiten que un proyecto de TypeScript haga referencia a otros proyectos, logrando compilación incremental y una mejor organización del código.


Crear un proyecto referenciado

Primero, crea el subproyecto referenciado.

packages/utils/tsconfig.json

{
    // Heredar la configuración base
    "extends": "../../tsconfig.base.json",

    // Opciones del compilador
    "compilerOptions": {
        // Directorio de salida
        "outDir": "./dist",

        // Directorio de archivos de declaración
        "declarationDir": "./dist/types",

        // Generar archivos de declaración
        "declaration": true,

        // Generar sourcemap
        "sourceMap": true,

        // Si es una biblioteca
        "composite": true
    },

    // Archivos incluidos
    "include": ["src/**/*"],

    // Archivos excluidos
    "exclude": ["node_modules", "dist", "**/*.test.ts"]
}

composite:Establécelo en true para habilitar la función de referencias de proyectos; esta es una opción obligatoria para los proyectos referenciados.


Configuración del proyecto principal

Configura references en el tsconfig.json del proyecto principal.

tsconfig.json (proyecto principal)

{
    // Heredar la configuración base
    "extends": "./tsconfig.base.json",

    // Opciones del compilador
    "compilerOptions": {
        // Directorio de salida
        "outDir": "./dist",

        // Directorio de archivos de declaración
        "declarationDir": "./dist/types",

        // Generar archivos de declaración
        "declaration": true,

        // Generar sourcemap
        "sourceMap": true
    },

    // Configuración de referencias de proyectos
    "references": [
        // Referenciar el proyecto utils
        { "path": "./packages/utils" },

        // Referenciar el proyecto ui
        { "path": "./packages/ui" },

        // Referenciar el proyecto types
        { "path": "./packages/types" }
    ],

    // Archivos incluidos
    "include": ["src/**/*"],

    // Incluir módulos de node de los que depende
    // "files": []
}

references:Cada objeto en el array especifica la ruta de un proyecto referenciado; path es relativo al proyecto actual.


Referencias de tipos

Usa los tipos del proyecto referenciado en el código.

src/index.ts

// Importar funciones de utilidad (del paquete utils)
import { formatDate, formatCurrency } from '@my-utils/format';

// Importar componentes (del paquete ui)
import { Button, Modal, Input } from '@my-ui/core';

// Importar tipos (del paquete types)
import { User, ApiResponse } from '@my-types/common';

// Definir datos de usuario
const user: User = {
    id: 1,
    name: "Alice",
    email: "alice@example.com"
};

// Formatear fecha
const dateStr = formatDate(new Date(), "YYYY-MM-DD");
console.log("Fecha: " + dateStr);

// Formatear moneda
const price = formatCurrency(999);
console.log("Precio: " + price);

// Crear interfaz de usuario
const button = new Button({
    text: "Enviar",
    variant: "primary"
});

console.log("Aplicación inicializada correctamente");

Método de importación:Las exportaciones del proyecto referenciado se pueden importar directamente y TypeScript resolverá los tipos automáticamente.


Compilación incremental

Las referencias de proyectos admiten compilación incremental, compilando solo las partes modificadas.

Comando de compilación

# Compilar todo el proyecto (incluyendo todas las referencias)
npm run build

# Compilar solo el proyecto principal (sin reconstruir dependencias)
npm run build -- --build

# Limpiar y reconstruir
npm run clean
npm run build

# Compilación incremental (recomendado)
# Después de modificar un paquete, solo recompila ese paquete y los paquetes que dependen de él
npx tsc -b packages/utils
npx tsc -b packages/ui
npx tsc -b .

Compilación incremental:Al usar la opción -b (build), TypeScript detecta automáticamente qué proyectos necesitan recompilarse.


Consideraciones importantes

  • Opción composite:El proyecto referenciado debe establecer composite: true
  • Directorio de salida:Cada proyecto necesita un directorio de salida independiente
  • Archivos de declaración:El proyecto referenciado debe generar archivos de declaración
  • Orden de compilación:Los proyectos de los que se depende deben compilarse primero

Mejores prácticas:Divide el código común en paquetes independientes y utiliza referencias de proyectos para gestionarlos, mejorando la eficiencia de compilación.


Resumen

Las referencias de proyectos son una función clave de TypeScript para gestionar proyectos grandes.

  • references:Configurar relaciones de referencias de proyectos
  • composite:Habilitar referencias de proyectos
  • Compilación incremental:Compilar solo las partes modificadas
  • Organización del código:Dividir en módulos independientes

Sugerencia:En proyectos grandes, usa referencias de proyectos para organizar el código y mejorar la eficiencia del desarrollo.

Otras extensiones