TypeScript Mapeo de rutas paths

paths es una opción de configuración en tsconfig.json que se utiliza para configurar alias de rutas de módulos.

Permite que las rutas de importación sean más concisas, manteniendo al mismo tiempo una estructura de código clara y organizada.


Diagrama SVG: cómo funciona el mapeo de rutas Fondo Título Cómo funciona el mapeo de rutas paths Importación original Ruta de importación original import Button from "../../components/Button" Flecha Después del mapeo de rutas Importar con alias import Button from "@/components/Button" Flecha tsconfig paths Configuración Parte inferior: opciones de configuración Opción de configuración paths Configuración 1 baseUrl Ruta base Configuración 2 paths Alias de ruta Configuración 3 rootDirs Directorios raíz Marcador de flecha

¿Por qué se necesita el mapeo de rutas?

A medida que el proyecto crece, los directorios de archivos se vuelven cada vez más profundos.

Usar rutas relativas para importar archivos (como ../../../components/Button) hace que el código sea difícil de leer y mantener.

El mapeo de rutas nos permite usar alias (como @/components/Button) en lugar de las largas rutas relativas.

Alias:Los alias de ruta hacen que las rutas de importación sean más concisas y facilitan el ajuste de la estructura del proyecto.


Configuración básica

Configura paths y baseUrl en tsconfig.json.

tsconfig.json

{
    "compilerOptions": {
        // Ruta base: directorio raíz de todos los alias de ruta
        "baseUrl": ".",

        // Configuración del mapeo de rutas
        "paths": {
            // Alias que comienzan con @/, apuntando al directorio src
            "@/*": ["src/*"],

            // Alias que comienzan con @components
            "@components/*": ["src/components/*"],

            // Alias que comienzan con @utils
            "@utils/*": ["src/utils/*"],

            // Alias que comienzan con @services
            "@services/*": ["src/services/*"],

            // Alias que comienzan con @assets
            "@assets/*": ["src/assets/*"],

            // Alias que comienzan con @types
            "@types/*": ["src/types/*"]
        }
    }
}

baseUrl:Después de configurar baseUrl, las rutas en paths se resolverán de forma relativa a este directorio.


Usar alias de ruta

Una vez completada la configuración, puedes usar alias para importar módulos en el código.

src/components/Button.tsx

// Importar usando alias de ruta
import { Button } from '@/components/Button';
import { User } from '@types/user';
import { fetchUser } from '@services/userApi';
import { formatDate } from '@utils/date';

// Importar estilos
import styles from '@/components/Button.module.css';

// Importar imágenes
import logo from '@assets/logo.png';

// Usar el módulo importado
const handleClick = () => {
    console.log('Clic en botón');
};

const userButton = new Button({
    text: 'Usuario',
    onClick: handleClick
});

console.log('Componente cargado correctamente');

Sintaxis:En la configuración de paths se usa * como comodín; al importar, * coincide con la ruta real.


Configuración de alias en Webpack

Si usas Webpack, también necesitas configurar resolve.alias para admitir el tiempo de ejecución.

webpack.config.js

// Importar el módulo webpack
const path = require('path');

// Configuración de Webpack
module.exports = {
    // Otras configuraciones...
    resolve: {
        // Configuración de alias de ruta, debe mantenerse consistente con tsconfig.json
        alias: {
            // Alias que comienzan con @
            '@': path.resolve(__dirname, 'src'),

            // Otros alias
            '@components': path.resolve(__dirname, 'src/components'),
            '@utils': path.resolve(__dirname, 'src/utils'),
            '@services': path.resolve(__dirname, 'src/services'),
            '@types': path.resolve(__dirname, 'src/types'),
            '@assets': path.resolve(__dirname, 'src/assets')
        },

        // Extensiones de archivo
        extensions: ['.ts', '.tsx', '.js', '.jsx', '.json']
    }
};

Consistencia en tiempo de ejecución:La configuración de alias de Webpack debe coincidir con la configuración de paths de TypeScript; de lo contrario, se producirán errores de módulo no encontrado en tiempo de ejecución.


Configuración de Vite

Al usar Vite, es necesario configurar tanto en tsconfig.json como en vite.config.ts.

vite.config.ts

// Importar el módulo vite
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import path from 'path';

// Configuración de Vite
export default defineConfig({
    plugins: [react()],

    // Configuración de alias de ruta
    resolve: {
        alias: {
            '@': path.resolve(__dirname, './src'),
            '@components': path.resolve(__dirname, './src/components'),
            '@utils': path.resolve(__dirname, './src/utils'),
            '@services': path.resolve(__dirname, './src/services'),
            '@types': path.resolve(__dirname, './src/types'),
            '@assets': path.resolve(__dirname, './src/assets')
        }
    }
});

Vite:Vite usa Rollup como motor de empaquetado, por lo que debes configurar los alias en resolve.alias.


Configuración de rutas para múltiples proyectos

En proyectos Monorepo, se pueden configurar alias de ruta entre paquetes.

tsconfig.json (Monorepo)

{
    "compilerOptions": {
        // Ruta base
        "baseUrl": ".",

        // Mapeo de rutas, admite referencias entre paquetes
        "paths": {
            // Referenciar módulos del paquete actual
            "@/*": ["src/*"],

            // Referenciar módulos de otros paquetes
            "@my-ui/button": ["packages/ui-button/src/index.ts"],
            "@my-ui/modal": ["packages/ui-modal/src/index.ts"],
            "@my-utils/date": ["packages/utils-date/src/index.ts"],
            "@my-hooks/useFetch": ["packages/hooks-use-fetch/src/index.ts"]
        }
    }
}

Monorepo:En proyectos Monorepo, paths puede referenciar rutas de código fuente de otros paquetes.


Consideraciones

  • baseUrl obligatorio:paths debe usarse junto con baseUrl
  • Coincidencia con comodines:Usa * para coincidir con cualquier ruta
  • Mantener la consistencia:La configuración de Webpack/Vite debe mantenerse consistente con tsconfig
  • Rutas relativas:Las rutas en paths son relativas a baseUrl

Buenas prácticas:Usar alias de ruta puede hacer que el código sea más conciso, pero no abuses de ellos; se recomienda unificar las convenciones de nomenclatura.


Resumen

El mapeo de rutas es una herramienta importante para gestionar las rutas de importación en proyectos TypeScript.

  • paths:Configurar alias de ruta
  • baseUrl:Establecer ruta base
  • Comodín:Usa * para coincidir con cualquier carácter
  • Herramienta de compilación:Webpack/Vite requieren configuración sincronizada

Recomendación:Establece alias de ruta para los directorios comunes, mejorando la legibilidad y el mantenimiento del código.

Otras extensiones