Esta es la guía para desarrolladores de AWS CDK v2. 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. Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés. # 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](https://nodejs.org/) y el administrador de paquetes de nodos (`npm`). También puede usar [Yarn](https://yarnpkg.com/) 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.](https://www.npmjs.com/) Puede usar cualquier editor o IDE. Muchos desarrolladores de AWS CDK usan [Visual Studio Code](https://code.visualstudio.com/) (o su equivalente de código abierto [VSCodium](https://vscodium.com/)), 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](getting-started.md). También necesita el propio TypeScript (versión 3.8 o posterior). Si no lo tiene, puede instalarlo mediante `npm`. ``` $ npm install -g typescript ``` **nota** Si aparece un error de permiso y tiene acceso de administrador al sistema, intente con `sudo npm install -g typescript`. Mantenga TypeScript actualizado con un `npm update -g typescript` periódico. **nota** Obsolescencia del lenguaje de terceros: la versión en otros idiomas solo se admite hasta que el proveedor o la comunidad compartan su fecha de caducidad (EOL) y está sujeta a cambios con previo aviso. ## 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 [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib-readme.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib-readme.html) 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`. | Operación | Uso de herramientas globales | Uso de herramientas locales | | --- | --- | --- | | **Iniciar el proyecto** | `cdk init --language typescript` | `npx aws-cdk init --language typescript` | | **Compilación** | `tsc` | `npm run build` | | **Ejecutar el comando del kit de herramientas de CDK** | `cdk …​` | `npm run cdk …​` or `npx aws-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`. **sugerencia** Configure un alias para poder usar el comando `cdk` con la instalación local del kit de herramientas de CDK. ``` $ alias cdk="npx aws-cdk" ``` ``` doskey cdk=npx aws-cdk $* ``` ## 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/-alpha`. El nombre del servicio tiene el prefijo *aws-*. Si no está seguro del nombre de un módulo, [búsquelo en el NPM](https://www.npmjs.com/search?q=%40aws-cdk). **nota** La [referencia de la API de CDK](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-construct-library.html) también muestra los nombres de los paquetes. 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. + Utilice directivas `import` al estilo de ES6, no `require()`. + Por lo general, se importan clases individuales desde `aws-cdk-lib`. ``` import { App, Stack } from 'aws-cdk-lib'; ``` + Si necesita muchas clases de `aws-cdk-lib`, puede utilizar un alias de espacio de nombres de `cdk` en lugar de importar clases individuales. Evite hacer ambas cosas. ``` import * as cdk from 'aws-cdk-lib'; ``` + Por lo general, se importan las Bibliotecas de constructos de AWS utilizando alias de espacio de nombres cortos. ``` import { aws_s3 as s3 } from 'aws-cdk-lib'; ``` ## 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 \$1, 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 \$1) 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. **aviso** Las `peerDependencies` se instalan automáticamente solo en NPM 7 y versiones posteriores. Si usa NPM 6 o una versión anterior, o si usa Yarn, debe incluir las dependencias de sus dependencias en `devDependencies`. De lo contrario, no se instalarán y recibirá una advertencia sobre las dependencias entre pares no resueltas. ### Instalación y actualización de las dependencias Ejecute el siguiente comando para instalar las dependencias de su proyecto. **Example** ``` # Install the latest version of everything that matches the ranges in 'package.json' npm install # Install the same exact dependency versions as recorded in 'package-lock.json' npm ci ``` ``` # Install the latest version of everything that matches the ranges in 'package.json' $ yarn upgrade # Install the same exact dependency versions as recorded in 'yarn.lock' $ yarn install --frozen-lockfile ``` 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](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuring-dependabot-version-updates) para que actualice automáticamente `package.json`. Como alternativa, use [npm-check-updates](https://www.npmjs.com/package/npm-check-updates). **importante** Por diseño, al instalar o actualizar las dependencias, NPM y Yarn eligen la última versión de cada paquete que cumpla con los requisitos especificados en `package.json`. Siempre existe el riesgo de que estas versiones se rompan (ya sea accidental o deliberadamente). Realice pruebas exhaustivas después de actualizar las dependencias de su proyecto. ## 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 [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.Bucket.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.Bucket.html) (en el módulo `aws-cdk-lib/aws-s3`) especifica un argumento de `props` que se ajusta a la interfaz [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.BucketProps.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.BucketProps.html). Si una propiedad es en sí misma un objeto, por ejemplo, la propiedad [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.BucketProps.html#websiteredirect](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.BucketProps.html#websiteredirect) de `BucketProps`, dicho objeto tendrá su propia interfaz a la que deberá ajustarse su forma, en este caso [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.RedirectTarget.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.RedirectTarget.html). 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](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html), 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.