Publicación

Ahora que has creado un archivo de declaración siguiendo los pasos de esta guía, es hora de publicarlo en npm. Hay dos formas principales de publicar tus archivos de declaración en npm:

1. Incluyéndolos en tu paquete npm
2. Publicándolos en la organización @types en npm.

Si tus tipos son generados por tu código fuente, publica los tipos con tu código fuente. Tanto los proyectos TypeScript como JavaScript pueden generar tipos mediante declaration.

De lo contrario, recomendamos enviar los tipos a DefinitelyTyped, que los publicará en la organización @types en npm.

Incluir declaraciones en tu paquete npm

Si tu paquete tiene un archivo .js principal, también necesitarás indicar el archivo de declaración principal en tu archivo package.json. Establece la propiedad types para que apunte a tu archivo de declaración empaquetado. Por ejemplo:

json
{
  "name": "awesome",
  "author": "Vandelay Industries",
  "version": "1.0.0",
  "main": "./lib/main.js",
  "types": "./lib/main.d.ts"
}

Ten en cuenta que el campo "typings" es sinónimo de types, y también podría usarse.

Dependencias

Todas las dependencias son gestionadas por npm. Asegúrate de que todos los paquetes de declaración de los que dependes estén marcados apropiadamente en la sección "dependencies" de tu package.json. Por ejemplo, imagina que creamos un paquete que usaba Browserify y TypeScript.

json
{
  "name": "browserify-typescript-extension",
  "author": "Vandelay Industries",
  "version": "1.0.0",
  "main": "./lib/main.js",
  "types": "./lib/main.d.ts",
  "dependencies": {
    "browserify": "latest",
    "@types/browserify": "latest",
    "typescript": "next"
  }
}

Aquí, nuestro paquete depende de los paquetes browserify y typescript. browserify no incluye sus archivos de declaración con sus paquetes npm, por lo que necesitábamos depender de @types/browserify para sus declaraciones. typescript, por otro lado, empaqueta sus archivos de declaración, por lo que no hubo necesidad de dependencias adicionales.

Nuestro paquete expone declaraciones de cada uno de ellos, por lo que cualquier usuario de nuestro paquete browserify-typescript-extension también necesita tener estas dependencias. Por esa razón, usamos "dependencies" y no "devDependencies", porque de lo contrario nuestros consumidores habrían necesitado instalar manualmente esos paquetes. Si solo hubiéramos escrito una aplicación de línea de comandos y no esperáramos que nuestro paquete se usara como una biblioteca, podríamos haber usado devDependencies.

Señales de alerta

/// <reference path="..." />

No uses /// <reference path="..." /> en tus archivos de declaración.

ts
/// <reference path="../typescript/lib/typescriptServices.d.ts" />
....

Sí usa /// <reference types="..." /> en su lugar.

ts
/// <reference types="typescript" />
....

Asegúrate de revisar la sección Consumir dependencias para obtener más información.

Empaquetar declaraciones dependientes

Si tus definiciones de tipo dependen de otro paquete:

• No lo combines con el tuyo, mantén cada uno en su propio archivo.
• No copies las declaraciones en tu paquete tampoco.
• Sí depende del paquete de declaración de tipos de npm si no empaqueta sus archivos de declaración.

Selección de versión con typesVersions

Cuando TypeScript abre un archivo package.json para averiguar qué archivos necesita leer, primero mira un campo llamado typesVersions.

Redirecciones de carpetas (usando *)

Un package.json con un campo typesVersions podría verse así:

json
{
  "name": "package-name",
  "version": "1.0.0",
  "types": "./index.d.ts",
  "typesVersions": {
    ">=3.1": { "*": ["ts3.1/*"] }
  }
}

Este package.json le dice a TypeScript que primero verifique la versión actual de TypeScript. Si es 3.1 o posterior, TypeScript calcula la ruta que has importado relativa al paquete y lee desde la carpeta ts3.1 del paquete.

Eso es lo que significa ese { "*": ["ts3.1/*"] }: si estás familiarizado con el mapeo de rutas, funciona exactamente así.

En el ejemplo anterior, si estamos importando desde "package-name", TypeScript intentará resolver desde [...]/node_modules/package-name/ts3.1/index.d.ts (y otras rutas relevantes) cuando se ejecute en TypeScript 3.1. Si importamos desde package-name/foo, intentaremos buscar [...]/node_modules/package-name/ts3.1/foo.d.ts y [...]/node_modules/package-name/ts3.1/foo/index.d.ts.

¿Qué pasa si no estamos ejecutando TypeScript 3.1 en este ejemplo? Bueno, si ninguno de los campos en typesVersions coincide, TypeScript recurre al campo types, por lo que aquí TypeScript 3.0 y anteriores serán redirigidos a [...]/node_modules/package-name/index.d.ts.

Redirecciones de archivos

Cuando solo deseas cambiar la resolución para un único archivo a la vez, puedes decirle a TypeScript el archivo que debe resolverse de manera diferente pasando los nombres de archivo exactos:

json
{
  "name": "package-name",
  "version": "1.0.0",
  "types": "./index.d.ts",
  "typesVersions": {
    "<4.0": { "index.d.ts": ["index.v3.d.ts"] }
  }
}

En TypeScript 4.0 y superior, una importación de "package-name" se resolvería a ./index.d.ts y para 3.9 e inferior a "./index.v3.d.ts.

Ten en cuenta que las redirecciones solo afectan la API externa de un paquete; la resolución de importaciones dentro de un proyecto no se ve afectada por typesVersions. Por ejemplo, un archivo d.ts en el ejemplo anterior que contenga import * as foo from "./index" seguirá mapeando a index.d.ts, no a index.v3.d.ts, mientras que otro paquete que importe import * as foo from "package-name" sí obtendrá index.v3.d.ts.

Comportamiento de coincidencia

La forma en que TypeScript decide si una versión del compilador y el lenguaje coinciden es usando los rangos semver de Node.

Múltiples campos

typesVersions puede admitir múltiples campos donde cada nombre de campo se especifica mediante el rango con el que coincidir.

{
  "name": "package-name",
  "version": "1.0",
  "types": "./index.d.ts",
  "typesVersions": {
    ">=3.2": { "*": ["ts3.2/*"] },
    ">=3.1": { "*": ["ts3.1/*"] }
  }
}

Dado que los rangos tienen el potencial de superponerse, determinar qué redirección se aplica depende del orden. Esto significa que en el ejemplo anterior, aunque tanto el comparador >=3.2 como el >=3.1 admiten TypeScript 3.2 y superior, invertir el orden podría tener un comportamiento diferente, por lo que la muestra anterior no sería equivalente a la siguiente.

{
  "name": "package-name",
  "version": "1.0",
  "types": "./index.d.ts",
  "typesVersions": {
    // NOTA: ¡esto no funciona!
    ">=3.1": { "*": ["ts3.1/*"] },
    ">=3.2": { "*": ["ts3.2/*"] }
  }
}

Publicar en @types

Los paquetes bajo la organización @types se publican automáticamente desde DefinitelyTyped utilizando la herramienta types-publisher. Para que tus declaraciones se publiquen como un paquete @types, envía una pull request a DefinitelyTyped. Puedes encontrar más detalles en la página de pautas de contribución.