Esta es la guía para AWS CDK desarrolladores de la versión 2. La CDK versión anterior entró en mantenimiento el 1 de junio de 2022 y finalizó el soporte 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 de AWS CDK en JavaScript

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

Puede usar cualquier editor o IDE. Muchos desarrolladores de AWS CDK utilizan Visual Studio Code (o su equivalente de código abierto VSCodium), que ofrece un buen soporte para JavaScript.

Introducción a JavaScript

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

Las aplicaciones de AWS CDK de JavaScript no requieren requisitos previos adicionales más allá de estos.

Creación de un proyecto

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

mkdir my-project
cd my-project
cdk init app --language javascript

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 JavaScript; por ejemplo, no debe comenzar por un número ni contener espacios.

Uso de cdk local

En su mayor parte, en esta guía se da por sentado que se instala el kit de herramientas de CDK de forma global (npm install -g aws-cdk), y los ejemplos de comandos proporcionados (por ejemplo, cdk synth) siguen esta suposición. Este enfoque facilita mantener el kit de herramientas de CDK actualizado y, dado que el CDK sigue una política estricta de compatibilidad con versiones anteriores, generalmente implica poco riesgo utilizar siempre la última versión.

Algunos equipos prefieren especificar todas las dependencias de cada proyecto, incluidas las herramientas como el kit de herramientas de CDK. Esta práctica le permite fijar estos componentes a versiones específicas y garantizar 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.

CDK incluye una dependencia para el kit de herramientas de CDK en el package.json de la plantilla del proyecto de JavaScript, por lo que, si quiere utilizar este enfoque, no necesita realizar ningún cambio 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 de CDK 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@1.120 --version imprime 1.120.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, son denominados aws-cdk-lib/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 del NPM de su proyecto a la última versión permitida según las reglas que especificó en package.json:

npm update

En JavaScript, importe módulos a su código con el mismo nombre que utilizó para instalarlos mediante el 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.

Administración de dependencias en JavaScript

En los proyectos de CDK de JavaScript, 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 por medio de npm install, el NPM graba el paquete en package.json por usted.

Si lo prefiere, puede usar Yarn en lugar del 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 por el comando cdk init --language typescript. El archivo generado para JavaScript es similar, solo que sin las entradas relacionadas con 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 la 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 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 las 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 dependencias

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

NPM

# 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

Yarn

# 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, lo cual podría ser necesario para establecer una nueva versión mínima. Si aloja su paquete en GitHub, puede configurar las actualizaciones de versiones de Dependabot para que actualice automáticamente package.json. Como alternativa, use npm-check-updates.

Expresiones idiomáticas de AWS CDK en JavaScript

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, una agrupación 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 “agrupación de atributos” como argumento.

El uso de un IDE o un editor que tenga un buen autocompletado de JavaScript ayudará a evitar errores ortográficos en los nombres de las propiedades. Si un constructo está esperando una propiedad encryptionKeys y la escribe como encryptionkeys, al instanciar el constructo, no ha transferido el valor que pretendía. Esto puede provocar un error en el momento de la síntesis si la propiedad es obligatoria, o hacer que la propiedad se ignore silenciosamente si es opcional. En este último caso, es posible que obtenga un comportamiento predeterminado que pretendía anular. Tenga mucho cuidado aquí.

Cuando subclasifique una clase de la Biblioteca de constructos de AWS (o sustituya un método que utilice un argumento similar a props), es posible que desee aceptar propiedades adicionales para su propio uso. La clase principal o el método anulado ignorarán estos valores, ya que en ese código nunca se accede a ellos, por lo que, en general, puede transferir todas las props que haya recibido.

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 las props recibidas 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 props) tienen el valor undefined en JavaScript. Para ello, se aplican las técnicas habituales. Por ejemplo, una expresión idiomática común para acceder a una propiedad de un valor que puede no estar definido es la siguiente:

// a may be undefined, but if it is not, it may have an attribute b
// c is undefined if a is undefined, OR if a doesn't have an attribute b
let c = a && a.b;

Sin embargo, si a pudiera tener algún otro valor “falso” además de undefined, es mejor hacer la prueba más explícita. Aquí, aprovecharemos el hecho de que null y undefined son iguales para probarlos al mismo tiempo:

let c = a == null ? a : a.b;

Uso de ejemplos de TypeScript con JavaScript

TypeScript es el lenguaje que utilizamos para desarrollar AWS CDK y fue el primer lenguaje compatible para el desarrollo de aplicaciones, por lo que muchos ejemplos de código de AWS CDK disponibles están escritos en TypeScript. Estos ejemplos de código pueden ser un buen recurso para los desarrolladores de JavaScript. Solo necesita eliminar las partes del código específicas de TypeScript.

Los fragmentos de TypeScript suelen utilizar las palabras clave import y export más recientes de ECMAScript para importar objetos de otros módulos y declarar que los objetos estarán disponibles fuera del módulo actual. Node.js acaba de empezar a admitir estas palabras clave en sus últimas versiones. En función de la versión de Node.js que utilice (o que desee admitir), puede reescribir las importaciones y exportaciones para utilizar la sintaxis anterior.

Las importaciones se pueden sustituir por llamadas a la función require().

TypeScript

import * as cdk from 'aws-cdk-lib';
import { Bucket, BucketPolicy } from 'aws-cdk-lib/aws-s3';

JavaScript

const cdk = require('aws-cdk-lib');
const { Bucket, BucketPolicy } = require('aws-cdk-lib/aws-s3');

Las exportaciones se pueden asignar al objeto module.exports.

TypeScript

export class Stack1 extends cdk.Stack {
  // ...
}

export class Stack2 extends cdk.Stack {
  // ...
}

JavaScript

class Stack1 extends cdk.Stack {
  // ...
}

class Stack2 extends cdk.Stack {
  // ...
}

module.exports = { Stack1, Stack2 }

Una vez que haya ordenado las importaciones y exportaciones, puede profundizar en el código real. Es posible que se encuentre con estas características de TypeScript de uso común:

Se pueden proporcionar anotaciones de tipo para las variables, los miembros de la clase, los parámetros de las funciones y los tipos de retorno de funciones. En el caso de las variables, los parámetros y los miembros, los tipos se especifican siguiendo el identificador con dos puntos y el tipo. Los valores de retorno de las funciones siguen la firma de la función y constan de dos puntos y el tipo.

Para convertir código con anotaciones de tipo a JavaScript, elimine los dos puntos y el tipo. Los miembros de la clase deben tener algún valor en JavaScript; configúrelos como undefined si solo tienen una anotación de tipo en TypeScript.

TypeScript

var encrypted: boolean = true;

class myStack extends cdk.Stack {
    bucket: s3.Bucket;
    // ...
}

function makeEnv(account: string, region: string) : object {
    // ...
}

JavaScript

var encrypted = true;

class myStack extends cdk.Stack {
    bucket = undefined;
    // ...
}

function makeEnv(account, region) {
    // ...
}

En TypeScript, las interfaces se utilizan para asignar un nombre a las agrupaciones de propiedades obligatorias y opcionales y a sus tipos. A continuación, puede utilizar el nombre de la interfaz como anotación de tipo. TypeScript se asegurará de que el objeto que utilice como argumento para una función tenga las propiedades requeridas de los tipos correctos.

interface myFuncProps {
    code: lambda.Code,
    handler?: string
}

JavaScript no tiene una característica de interfaz, por lo que una vez que haya eliminado las anotaciones de tipo, elimine por completo las declaraciones de la interfaz.

Cuando una función o un método devuelve un tipo de uso general (como object), pero quiere tratar ese valor como un tipo secundario más específico para acceder a las propiedades o los métodos que no forman parte de la interfaz del tipo más general, TypeScript le permite convertir el valor con el uso de as seguido de un nombre de tipo o interfaz. JavaScript no admite (o necesita) esto, así que simplemente elimine as y el siguiente identificador. Una sintaxis de conversión menos común es usar el nombre de un tipo entre paréntesis, <LikeThis>. Estas conversiones también deben eliminarse.

Por último, TypeScript admite los modificadores de acceso public, protected y private para los miembros de las clases. Todos los miembros de la clase en JavaScript son públicos. Tan solo elimine estos modificadores dondequiera que los vea.

Saber cómo identificar y eliminar estas características de TypeScript contribuye en gran medida a adaptar fragmentos cortos de TypeScript a JavaScript. Pero puede que no sea práctico convertir ejemplos de TypeScript más largos de esta manera, ya que es más probable que usen otras características de TypeScript. Para estas situaciones, recomendamos Sucrase. Sucrase no mostrará un reclamo si el código utiliza una variable indefinida, por ejemplo, como lo haría tsc. Si es sintácticamente válido, con pocas excepciones, Sucrase puede traducirlo a JavaScript. Esto lo hace particularmente valioso para convertir fragmentos que tal vez no se puedan ejecutar por sí solos.

Migración a TypeScript

Muchos desarrolladores de JavaScript optan por TypeScript a medida que sus proyectos se hacen más grandes y complejos. TypeScript es un superconjunto de JavaScript (todo el código de JavaScript es código de TypeScript válido, por lo que no es necesario realizar cambios en el código), y también es un lenguaje compatible con AWS CDK. Las anotaciones de texto y otras características de TypeScript son opcionales y se pueden agregar a su aplicación AWS CDK a medida que las considere útiles. TypeScript también les da acceso anticipado a las nuevas características de JavaScript, como el encadenamiento opcional y la fusión de NULL, antes de que estén finalizadas, y sin necesidad de actualizar Node.js.

Las interfaces “basadas en formas” de TypeScript, que definen las agrupaciones de las propiedades obligatorias y opcionales (y sus tipos) dentro de un objeto, permiten detectar errores comunes al escribir el código y facilitan que el IDE proporcione consejos sólidos de autocompletado y de codificación en tiempo real.

La codificación en TypeScript implica un paso adicional: compilar su aplicación con el compilador de TypeScript, tsc. Para las aplicaciones de AWS CDK típicas, la compilación requiere unos segundos como máximo.

La forma más fácil de migrar una aplicación de AWS CDK existente de JavaScript a TypeScript es crear un nuevo proyecto de TypeScript con cdk init app --language typescript y, a continuación, copiar los archivos de origen (y cualquier otro archivo necesario, como activos con el código fuente de la función de AWS Lambda) en el nuevo proyecto. Cambie el nombre de sus archivos de JavaScript para que terminen en .ts y comience a desarrollar en TypeScript.