Esta es la segunda versión de la Guía para desarrolladores de AWS CDK. La primera versión del CDK pasó a la etapa de mantenimiento el 1.° de junio de 2022 y no cuenta con soporte desde el 1.° de junio de 2023.

Utilización del AWS CDK en TypeScript

TypeScript es un lenguaje de cliente totalmente compatible con AWS Cloud Development Kit (AWS CDK) y se lo considera estable. Para trabajar con AWS CDK en TypeScript se utilizan herramientas conocidas, como el compilador TypeScript de Microsoft (tsc), Node.js y el administrador de paquetes de nodos (npm). También puede usar Yarn si lo prefiere, aunque en los ejemplos de esta guía se usa NPM. Los módulos que componen la Biblioteca de constructos de AWS se distribuyen a través del repositorio NPM, nuget.org.

Puede usar cualquier editor o IDE. Muchos desarrolladores de AWS CDK usan Visual Studio Code (o su equivalente de código abierto VSCodium), que tiene un excelente compatibilidad con TypeScript.

Introducción al TypeScript

Para trabajar con el AWS CDK, debe tener una cuenta de AWS y credenciales, y haber instalado Node.js y el kit de herramientas de AWS CDK. Consulte Introducción al AWS CDK.

También necesita el propio TypeScript (versión 3.8 o posterior). Si no lo tiene, puede instalarlo mediante npm.

$ npm install -g typescript

Mantenga TypeScript actualizado con un npm update -g typescript periódico.

Creación de un proyecto

Cree un nuevo proyecto AWS CDK, mediante la invocación de cdk init en un directorio vacío. Utilice la opción --language y especifique typescript:

$ mkdir my-project
$ cd my-project
$ cdk init app --language typescript

Al crear un proyecto, también se instala el módulo aws-cdk-lib y sus dependencias.

cdk init utiliza el nombre de la carpeta del proyecto para asignar un nombre a varios elementos del proyecto, incluidas las clases, las subcarpetas y los archivos. Los guiones del nombre de la carpeta se convierten en guiones bajos. Aunque, de lo contrario, el nombre debe seguir la forma de un identificador de TypeScript; por ejemplo, no debe comenzar por un número ni contener espacios.

Uso local tsc y cdk

En su mayor parte, esta guía supone que instala TypeScript y el kit de herramientas de CDK de forma global (npm install -g typescript aws-cdk) y los ejemplos de comandos proporcionados (como cdk synth) siguen esta suposición. Este enfoque facilita mantener ambos componentes actualizados y, dado que ambos adoptan un enfoque estricto en cuanto a la compatibilidad con versiones anteriores, por lo general, se corre poco riesgo si se utilizan siempre las versiones más recientes.

Algunos equipos prefieren especificar todas las dependencias dentro de cada proyecto, incluidas herramientas como el compilador TypeScript y el kit de herramientas de CDK. Esta práctica permite vincular estos componentes a versiones específicas y asegurarse de que todos los desarrolladores de su equipo (y de su entorno de CI/CD) utilicen exactamente esas versiones. Esto elimina una posible fuente de cambio, lo que ayuda a que las compilaciones y las implementaciones sean más consistentes y repetibles.

El CDK incluye dependencias tanto para TypeScript como para el kit de herramientas de CDK en las plantillas del proyecto de TypeScript package.json, por lo que si quiere utilizar este enfoque, no necesita hacer modificaciones en su proyecto. Todo lo que necesita hacer es usar comandos ligeramente diferentes para crear su aplicación y para emitir comandos cdk.

npx aws-cdk ejecuta la versión del kit de herramientas instalada localmente en el proyecto actual, si está disponible; de lo contrario, utiliza la instalación global, si la hay. Si no existe una instalación global, npx descarga una copia temporal del kit de herramientas de CDK y la ejecuta. Puede especificar una versión arbitraria del kit de herramientas de CDK mediante la sintaxis @: npx aws-cdk@2.0 --version imprime 2.0.0.

Administración de los módulos de la Biblioteca de constructos de AWS

Use el administrador de paquetes de nodo (npm) para instalar y actualizar los módulos de la Biblioteca de constructos de AWS para que sus aplicaciones los usen, así como otros paquetes que necesite. (Puede usar yarn en lugar de npm si lo prefiere). npm también instala las dependencias de esos módulos automáticamente.

La mayoría de los constructos de AWS CDK se encuentran en el paquete CDK principal, llamado aws-cdk-lib, que es una dependencia predeterminada en los nuevos proyectos creados por cdk init. Los módulos “experimentales” de la Biblioteca de constructos de AWS, en los que aún se están desarrollando los constructos de nivel superior, reciben el nombre @aws-cdk/<SERVICE-NAME>-alpha. El nombre del servicio tiene el prefijo aws-. Si no está seguro del nombre de un módulo, búsquelo en el NPM.

Por ejemplo, el siguiente comando instala el módulo experimental de AWS CodeStar.

$ npm install @aws-cdk/aws-codestar-alpha

El soporte de la Biblioteca de constructos de algunos servicios se encuentra en más de un espacio de nombres. Por ejemplo, además de aws-route53, hay tres espacios de nombres adicionales de Amazon Route 53: aws-route53-targets, aws-route53-patterns, y aws-route53resolver.

Las dependencias de su proyecto se mantienen en package.json. Puede editar este archivo para bloquear algunas o todas sus dependencias en una versión específica, o para permitir que se actualicen a versiones más recientes según determinados criterios. Esto es para actualizar las dependencias de NPM de su proyecto a la última versión permitida, de acuerdo con las reglas que especificó en package.json:

$ npm update

En TypeScript, importe módulos a su código con el mismo nombre que utilizó para instalarlos mediante NPM. Recomendamos las siguientes prácticas al importar clases de AWS CDK y módulos de la Biblioteca de constructos de AWS a sus aplicaciones. Seguir estas directrices ayudará a que su código sea coherente con el de otras aplicaciones de AWS CDK y a que sea más fácil de entender.

Administrar dependencias en TypeScript

En los proyectos CDK en TypeScript, las dependencias se especifican en el archivo package.json del directorio principal del proyecto. Los módulos principales de AWS CDK se encuentran en un único paquete NPM llamado aws-cdk-lib.

Cuando instala un paquete utilizando npm install, el NPM graba el paquete package.json por usted.

Si lo prefiere, puede usar Yarn en lugar de NPM. Sin embargo, el CDK no es compatible con el modo listo para usar de Yarn, que es el modo predeterminado en Yarn 2. Agregue lo siguiente al archivo .yarnrc.yml de su proyecto para desactivar esta característica.

nodeLinker: node-modules

Aplicaciones de CDK

A continuación, se muestra un ejemplo de un archivo package.json generado a través del comando cdk init --language typescript:

{
  "name": "my-package",
  "version": "0.1.0",
  "bin": {
    "my-package": "bin/my-package.js"
  },
  "scripts": {
    "build": "tsc",
    "watch": "tsc -w",
    "test": "jest",
    "cdk": "cdk"
  },
  "devDependencies": {
    "@types/jest": "^26.0.10",
    "@types/node": "10.17.27",
    "jest": "^26.4.2",
    "ts-jest": "^26.2.0",
    "aws-cdk": "2.16.0",
    "ts-node": "^9.0.0",
    "typescript": "~3.9.7"
  },
  "dependencies": {
    "aws-cdk-lib": "2.16.0",
    "constructs": "^10.0.0",
    "source-map-support": "^0.5.16"
  }
}

En el caso de las aplicaciones de CDK implementables, debe especificarse aws-cdk-lib en la sección dependencies de package.json. Puede utilizar un carácter (^) como especificador del número de versión para indicar que aceptará versiones posteriores a la especificada, siempre que estén dentro de la misma versión principal.

Para los constructos experimentales, especifique las versiones exactas de los módulos de la Biblioteca de constructos alfa, ya que sus API pueden cambiar. No utilice ^ ni ~, ya que las versiones posteriores de estos módulos pueden incluir cambios en la API que pueden dañar su aplicación.

Especifique las versiones de las bibliotecas y herramientas necesarias para probar su aplicación (por ejemplo, el marco de pruebas jest) en la sección devDependencies de package.json. Si lo desea, utilice ^ para especificar si se aceptan versiones posteriores compatibles.

Bibliotecas de constructos de terceros

Si está desarrollando una Biblioteca de constructos, especifique sus dependencias mediante una combinación de las secciones peerDependencies y devDependencies, como se muestra en el siguiente archivo package.json de ejemplo.

{
  "name": "my-package",
  "version": "0.0.1",
  "peerDependencies": {
    "aws-cdk-lib": "^2.14.0",
    "@aws-cdk/aws-appsync-alpha": "2.10.0-alpha",
    "constructs": "^10.0.0"
  },
  "devDependencies": {
    "aws-cdk-lib": "2.14.0",
    "@aws-cdk/aws-appsync-alpha": "2.10.0-alpha",
    "constructs": "10.0.0",
    "jsii": "^1.50.0",
    "aws-cdk": "^2.14.0"
  }
}

En peerDependencies, utilice un carácter (^) para especificar la versión más baja de aws-cdk-lib con la que funciona la biblioteca. Esto maximiza la compatibilidad de la biblioteca con una variedad de versiones de CDK. Especifique las versiones exactas de los módulos de la Biblioteca de constructos alfa, que tienen las API que pueden cambiar. El uso de peerDependencies garantiza que solo haya una copia de todas las bibliotecas de CDK en el árbol de node_modules.

En devDependencies, especifique las herramientas y bibliotecas que necesita para realizar las pruebas; si lo desea, use ^ para indicar que se aceptan versiones posteriores compatibles. Especifique de forma exacta (sin ^ o ~) las versiones más bajas de aws-cdk-lib y otros paquetes CDK con los que anuncia que su biblioteca es compatible. Esta práctica garantiza que las pruebas se ejecuten con esas versiones. De esta forma, si utiliza inadvertidamente una característica que solo se encuentra en las versiones más recientes, sus pruebas pueden detectarla.

Instalación y actualización de las dependencias

Ejecute el siguiente comando para instalar las dependencias de su proyecto.

Para actualizar los módulos instalados, se pueden utilizar los comandos anteriores npm install y yarn upgrade. Cualquiera de los dos comandos actualiza los paquetes en node_modules a las versiones más recientes que cumplen las reglas de package.json. Sin embargo, no actualizan el propio package.json, por lo que puede que desee establecer una nueva versión mínima. Si aloja su paquete en GitHub, puede configurar las actualizaciones de las versiones del Dependabot para que actualice automáticamente package.json. Como alternativa, use npm-check-updates.

Expresiones idiomáticas de AWS CDK en TypeScript

Props

Todas las clases de Bibliotecas de constructos de AWS se instancian con tres argumentos: el ámbito en el que se define el constructo (su elemento principal en el árbol de constructos), un identificador y props. Los argumentos de props son un conjunto de pares clave/valor que el constructo utiliza para configurar los recursos de AWS que crea. Otras clases y métodos también utilizan el patrón de “conjunto de atributos” como argumento.

En TypeScript, la forma de props se define mediante una interfaz que indica los argumentos obligatorios y opcionales y sus tipos. Esta interfaz se define para cada tipo de argumento props y, por lo general, es específica de un solo constructo o método. Por ejemplo, el constructo Bucket (en el módulo aws-cdk-lib/aws-s3) especifica un argumento de props que se ajusta a la interfaz BucketProps.

Si una propiedad es en sí misma un objeto, por ejemplo, la propiedad websiteRedirect de BucketProps, dicho objeto tendrá su propia interfaz a la que deberá ajustarse su forma, en este caso RedirectTarget.

Si subclasifica una clase de Biblioteca de constructos de AWS (o anula un método que utiliza un argumento similar a las props), puede heredarla de la interfaz existente para crear una nueva que especifique los accesorios nuevos que necesite el código. Cuando llama a la clase principal o al método base, normalmente puede pasar todo el argumento de props que haya recibido, ya que se ignorarán todos los atributos proporcionados en el objeto, pero no especificados en la interfaz.

Una futura versión del AWS CDK podría agregar casualmente una nueva propiedad con el nombre que utilizó para su propiedad. Transferir el valor que recibe a la cadena de herencia puede provocar un comportamiento inesperado. Es más seguro transferir una copia superficial de los props recibidos con su propiedad eliminada o establecida como undefined. Por ejemplo:

super(scope, name, {...props, encryptionKeys: undefined});

Como alternativa, nombre sus propiedades para que quede claro que pertenecen a su constructo. De esta forma, es poco probable que colisionen con propiedades en futuras versiones de AWS CDK. Si hay muchas, utilice un único objeto con el nombre apropiado para almacenarlas.

Valores faltantes

Los valores que faltan en un objeto (como las props) tienen el valor undefined en TypeScript. La versión 3.7 del lenguaje introdujo operadores que simplifican el trabajo con estos valores, lo que facilita la especificación de los valores predeterminados y el encadenamiento de “cortocircuitos” cuando se alcanza un valor indefinido. Para obtener más información sobre estas características, consulte las notas de la versión de TypeScript 3.7, específicamente las dos primeras características, el encadenamiento opcional y la fusión nula.

Crear y ejecutar aplicaciones de CDK

Por lo general, debe estar en el directorio raíz del proyecto cuando compila y ejecuta la aplicación.

Node.js no puede ejecutar TypeScript directamente; en su lugar, la aplicación se convierte a JavaScript mediante el compilador de TypeScript, tsc. A continuación, se ejecuta el código JavaScript resultante.

El AWS CDK hace esto automáticamente siempre que necesite ejecutar la aplicación. Sin embargo, la compilación manual puede resultar útil para comprobar si hay errores y ejecutar pruebas. Para compilar la aplicación TypeScript manualmente, emita npm run build. También puede optar por emitir npm run watch para entrar en el modo de visualización, en el que el compilador de TypeScript reconstruye automáticamente la aplicación cada vez que guarda los cambios en un archivo fuente.