Commencez avec TypeScript Création d’un projet Utilisation de locaux tsc et cdk Gestion des modules AWS de la bibliothèque Construct Gestion des dépendances dans TypeScript AWS CDK expressions idiomatiques dans TypeScript Créez et exécutez CDK des applications

Travailler avec le AWS CDK in TypeScript

TypeScript est une langue client entièrement prise en charge pour le AWS Cloud Development Kit (AWS CDK) et est considérée comme stable. L'utilisation de l' AWS CDK in TypeScript utilise des outils familiers, notamment le TypeScript compilateur (tsc) de Microsoft, Node.js et le Node Package Manager (npm). Vous pouvez également utiliser Yarn si vous préférez, comme le montrent les exemples de ce guideNPM. Les modules composant la bibliothèque AWS Construct sont distribués via le NPM référentiel npmjs.org.

Vous pouvez utiliser n'importe quel éditeur ouIDE. De nombreux AWS CDK développeurs utilisent Visual Studio Code (ou son équivalent open source VSCodium), qui bénéficie d'un excellent support pour TypeScript.

Rubriques

Commencez avec TypeScript
Création d’un projet
Utilisation de locaux tsc et cdk
Gestion des modules AWS de la bibliothèque Construct
Gestion des dépendances dans TypeScript
AWS CDK expressions idiomatiques dans TypeScript
Créez et exécutez CDK des applications

Commencez avec TypeScript

Pour utiliser le AWS CDK, vous devez disposer d'un AWS compte et d'informations d'identification et avoir installé Node.js et le AWS CDK Toolkit. Consultez Commencer à utiliser le AWS CDK.

Vous avez également besoin de TypeScript lui-même (version 3.8 ou ultérieure). Si vous ne l'avez pas déjà, vous pouvez l'installer en utilisantnpm.


npm install -g typescript

Note

Si une erreur d'autorisation s'affiche et que vous disposez d'un accès administrateur sur votre système, essayezsudo npm install -g typescript.

TypeScript Tenez-vous au courant avec un habituénpm update -g typescript.

Note

Obsolète linguistique tierce : la version linguistique n'est prise en charge que jusqu'à sa EOL (fin de vie) partagée par le fournisseur ou la communauté et est sujette à modification avec préavis.

Création d’un projet

Vous créez un nouveau AWS CDK projet en l'appelant cdk init dans un répertoire vide. Utilisez l'--languageoption et spécifiez typescript :


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

La création d'un projet installe également le aws-cdk-libmodule et ses dépendances.

cdk initutilise le nom du dossier du projet pour nommer les différents éléments du projet, notamment les classes, les sous-dossiers et les fichiers. Les traits d'union figurant dans le nom du dossier sont convertis en traits de soulignement. Toutefois, le nom doit sinon prendre la forme d'un TypeScript identifiant ; par exemple, il ne doit pas commencer par un chiffre ni contenir d'espaces.

Utilisation de locaux `tsc` et `cdk`

Dans l'ensemble, ce guide suppose que vous installez TypeScript le CDK Toolkit globalement (npm install -g typescript aws-cdk), et les exemples de commandes fournis (tels quecdk synth) suivent cette hypothèse. Cette approche facilite la mise à jour des deux composants, et comme les deux adoptent une approche stricte en matière de rétrocompatibilité, il y a généralement peu de risques à toujours utiliser les dernières versions.

Certaines équipes préfèrent spécifier toutes les dépendances au sein de chaque projet, y compris des outils tels que le TypeScript compilateur et le CDK Toolkit. Cette pratique vous permet d'associer ces composants à des versions spécifiques et de vous assurer que tous les développeurs de votre équipe (et de votre environnement CI/CD) utilisent exactement ces versions. Cela élimine toute source potentielle de changement, ce qui contribue à rendre les builds et les déploiements plus cohérents et reproductibles.

CDKCela inclut des dépendances pour les deux TypeScript et pour le CDK kit d'outils dans le modèle de TypeScript projet. Ainsipackage.json, si vous souhaitez utiliser cette approche, vous n'avez pas besoin d'apporter de modifications à votre projet. Il vous suffit d'utiliser des commandes légèrement différentes pour créer votre application et pour émettre des cdk commandes.

Opération	Utiliser des outils mondiaux	Utiliser des outils locaux
Initialiser le projet	`cdk init --language typescript`	`npx aws-cdk init --language typescript`
Génération	`tsc`	`npm run build`
Exécuter la commande CDK Toolkit	`cdk ...`	`npm run cdk ...` ou `npx aws-cdk ...`

npx aws-cdkexécute la version du CDK Toolkit installée localement dans le projet en cours, s'il en existe une, en revenant à l'installation globale, le cas échéant. S'il n'existe aucune installation globale, npx télécharge une copie temporaire du CDK Toolkit et l'exécute. Vous pouvez spécifier une version arbitraire du CDK Toolkit en utilisant la @ syntaxe : npx aws-cdk@2.0 --version prints2.0.0.

Astuce

Configurez un alias afin de pouvoir utiliser la cdk commande dans le cadre d'une installation locale du CDK Toolkit.

Gestion des modules AWS de la bibliothèque Construct

Utilisez le Node Package Manager (npm) pour installer et mettre à jour les modules AWS Construct Library destinés à être utilisés par vos applications, ainsi que par les autres packages dont vous avez besoin. (Vous pouvez utiliser à la yarn place de npm si vous préférez.) npminstalle également automatiquement les dépendances de ces modules.

La plupart AWS CDK des constructions se trouvent dans le CDK package principal, nomméaws-cdk-lib, qui est une dépendance par défaut dans les nouveaux projets créés parcdk init. Les modules de la bibliothèque de AWS construction « expérimentaux », où des constructions de niveau supérieur sont encore en cours de développement, sont nommés ainsi. @aws-cdk/SERVICE-NAME-alpha Le nom du service comporte un préfixe aws-. Si vous n'êtes pas sûr du nom d'un module, recherchez-le sur NPM.

Note

La CDKAPIréférence indique également les noms des packages.

Par exemple, la commande ci-dessous installe le module expérimental pour AWS CodeStar.


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

La prise en charge de la bibliothèque Construct par certains services se trouve dans plusieurs espaces de noms. Par exempleaws-route53, il existe en outre trois espaces de noms Amazon Route 53 supplémentaires, aws-route53-targetsaws-route53-patterns, etaws-route53resolver.

Les dépendances de votre projet sont conservées danspackage.json. Vous pouvez modifier ce fichier pour verrouiller certaines ou toutes vos dépendances dans une version spécifique ou pour permettre leur mise à jour vers des versions plus récentes selon certains critères. Pour mettre à jour NPM les dépendances de votre projet vers la dernière version autorisée conformément aux règles que vous avez spécifiées dans package.json :


npm update

Dans TypeScript, vous importez des modules dans votre code sous le même nom que celui que vous utilisez pour les installerNPM. Nous recommandons les pratiques suivantes lors de l'importation de AWS CDK classes et de modules AWS Construct Library dans vos applications. Le respect de ces directives vous aidera à rendre votre code cohérent avec AWS CDK les autres applications et à le rendre plus facile à comprendre.

N'utilisez pas require() les import directives de ES6 style -style.
En général, importez des classes individuelles depuisaws-cdk-lib.
```
import { App, Stack } from 'aws-cdk-lib';
```
Si vous avez besoin de nombreuses classesaws-cdk-lib, vous pouvez utiliser un alias d'espace de noms de cdk au lieu d'importer les classes individuelles. Évitez de faire les deux.
```
import * as cdk from 'aws-cdk-lib';
```
En général, importez des structures AWS de service utilisant des alias d'espace de noms courts.
```
import { aws_s3 as s3 } from 'aws-cdk-lib';
```

Gestion des dépendances dans TypeScript

Dans les TypeScript CDK projets, les dépendances sont spécifiées dans le package.json fichier du répertoire principal du projet. Les AWS CDK modules principaux se trouvent dans un seul NPM package appeléaws-cdk-lib.

Lorsque vous installez un package à l'aide denpm install, NPM enregistre le package package.json pour vous.

Si vous préférez, vous pouvez utiliser Yarn à la place deNPM. Cependant, il CDK ne prend pas en charge le plug-and-play mode Yarn, qui est le mode par défaut dans Yarn 2. Ajoutez ce qui suit au .yarnrc.yml fichier de votre projet pour désactiver cette fonctionnalité.


nodeLinker: node-modules

CDKapplications

Voici un exemple de package.json fichier généré par la cdk init --language typescript commande :


{
  "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"
  }
}

Pour les CDK applications déployables, aws-cdk-lib cela doit être spécifié dans la dependencies section depackage.json. Vous pouvez utiliser un spécificateur de numéro de version caret (^) pour indiquer que vous accepterez des versions ultérieures à celle spécifiée, à condition qu'elles soient dans la même version majeure.

Pour les constructions expérimentales, spécifiez les versions exactes des modules de la bibliothèque de constructions alpha, APIs qui peuvent changer. N'utilisez pas ^ ou ~ car les versions ultérieures de ces modules peuvent apporter API des modifications susceptibles de casser votre application.

Spécifiez les versions des bibliothèques et des outils nécessaires pour tester votre application (par exemple, le framework de jest test) dans la devDependencies section depackage.json. Utilisez éventuellement ^ pour indiquer que les versions compatibles ultérieures sont acceptables.

Bibliothèques de construction tierces

Si vous développez une bibliothèque de constructions, spécifiez ses dépendances à l'aide d'une combinaison des devDependencies sections peerDependencies et, comme indiqué dans l'exemple de package.json fichier suivant.


{
  "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"
  }
}

DanspeerDependencies, utilisez un curseur (^) pour spécifier la version la plus basse de aws-cdk-lib celle avec laquelle votre bibliothèque fonctionne. Cela permet d'optimiser la compatibilité de votre bibliothèque avec une gamme de CDK versions. Spécifiez les versions exactes des modules de la bibliothèque de construction alpha, APIs qui peuvent changer. L'utilisation peerDependencies garantit qu'il n'y a qu'une seule copie de toutes les CDK bibliothèques dans l'node_modulesarborescence.

DansdevDependencies, spécifiez les outils et les bibliothèques dont vous avez besoin pour les tests, éventuellement avec ^ pour indiquer que les versions compatibles ultérieures sont acceptables. Spécifiez exactement (sans ^ ou ~) les versions les plus basses aws-cdk-lib et les autres CDK packages avec lesquels vous annoncez que votre bibliothèque doit être compatible. Cette pratique garantit que vos tests s'exécutent par rapport à ces versions. Ainsi, si vous utilisez par inadvertance une fonctionnalité présente uniquement dans les versions les plus récentes, vos tests peuvent la détecter.

Avertissement

peerDependenciesne sont installés automatiquement qu'à partir de la version NPM 7. Si vous utilisez NPM 6 ou une version antérieure, ou si vous utilisez Yarn, vous devez inclure les dépendances de vos dépendances dansdevDependencies. Dans le cas contraire, ils ne seront pas installés et vous recevrez un avertissement concernant les dépendances non résolues entre pairs.

Installation et mise à jour des dépendances

Exécutez la commande suivante pour installer les dépendances de votre projet.

Pour mettre à jour les modules installés, les yarn upgrade commandes npm install et précédentes peuvent être utilisées. L'une ou l'autre des commandes met node_modules à jour les packages vers les dernières versions conformes aux règles depackage.json. Cependant, ils ne package.json se mettent pas à jour d'eux-mêmes, ce que vous pouvez faire pour définir une nouvelle version minimale. Si vous hébergez votre package sur GitHub, vous pouvez configurer les mises à jour de version de Dependabot pour qu'elles soient mises à jour package.json automatiquement. Sinon, utilisez npm-check-updates.

Important

Dès la conception, lorsque vous installez ou mettez à jour NPM des dépendances, Yarn choisit la dernière version de chaque package qui répond aux exigences spécifiées danspackage.json. Il existe toujours un risque que ces versions soient cassées (accidentellement ou intentionnellement). Effectuez des tests approfondis après avoir mis à jour les dépendances de votre projet.

AWS CDK expressions idiomatiques dans TypeScript

accessoires

Toutes les classes de la bibliothèque de AWS construction sont instanciées à l'aide de trois arguments : la portée dans laquelle la construction est définie (son parent dans l'arbre de construction), un identifiant et des accessoires. L'argument props est un ensemble de paires clé/valeur que la construction utilise pour configurer les AWS ressources qu'elle crée. D'autres classes et méthodes utilisent également le modèle « bundle of attributes » pour les arguments.

Dans TypeScript, la forme de props est définie à l'aide d'une interface qui vous indique les arguments obligatoires et facultatifs ainsi que leurs types. Une telle interface est définie pour chaque type d'propsargument, généralement spécifique à une construction ou à une méthode unique. Par exemple, la construction Bucket (dans leaws-cdk-lib/aws-s3 module) spécifie un props argument conforme à l'BucketPropsinterface.

Si une propriété est elle-même un objet, par exemple la websiteRedirectpropriété deBucketProps, cet objet aura sa propre interface à laquelle sa forme doit être conforme, dans ce cas RedirectTarget.

Si vous sous-classez une classe AWS Construct Library (ou si vous remplacez une méthode qui prend un argument semblable à des accessoires), vous pouvez hériter de l'interface existante pour en créer une nouvelle qui spécifie les nouveaux accessoires requis par votre code. Lorsque vous appelez la classe parent ou la méthode de base, vous pouvez généralement transmettre l'intégralité de l'argument props que vous avez reçu, car tous les attributs fournis dans l'objet mais non spécifiés dans l'interface seront ignorés.

Une future version du AWS CDK pourrait par hasard ajouter une nouvelle propriété avec un nom que vous avez utilisé pour votre propre propriété. Le transfert de la valeur que vous recevez vers le haut de la chaîne d'héritage peut alors provoquer un comportement inattendu. Il est plus sûr de transmettre une copie sommaire des accessoires que vous avez reçus lorsque vos biens ont été retirés ou transférésundefined. Par exemple :


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

Vous pouvez également nommer vos propriétés de manière à ce qu'il soit clair qu'elles appartiennent à votre construction. De cette façon, il est peu probable qu'ils entrent en collision avec des propriétés dans les futures AWS CDK versions. S'ils sont nombreux, utilisez un seul objet portant le nom approprié pour les conserver.

Valeurs manquantes

Les valeurs manquantes dans un objet (comme les accessoires) ont pour valeur undefined in TypeScript. La version 3.7 du langage a introduit des opérateurs qui simplifient le travail avec ces valeurs, en facilitant la spécification des valeurs par défaut et en « court-circuitant » le chaînage lorsqu'une valeur indéfinie est atteinte. Pour plus d'informations sur ces fonctionnalités, consultez les notes de mise à jour de la version TypeScript 3.7, en particulier les deux premières fonctionnalités, le chaînage facultatif et la coalescence nulle.

Créez et exécutez CDK des applications

En règle générale, vous devez vous trouver dans le répertoire racine du projet lors de la création et de l'exécution de votre application.

Node.js ne peut pas s'exécuter TypeScript directement ; au lieu de cela, votre application est convertie à l' JavaScript aide du TypeScript compilateurtsc. Le JavaScript code obtenu est ensuite exécuté.

Il le fait AWS CDK automatiquement chaque fois qu'il doit exécuter votre application. Cependant, il peut être utile de compiler manuellement pour vérifier les erreurs et pour exécuter des tests. Pour compiler votre TypeScript application manuellement, lanceznpm run build. Vous pouvez également npm run watch entrer en mode veille, dans lequel le TypeScript compilateur reconstruit automatiquement votre application chaque fois que vous enregistrez des modifications dans un fichier source.

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

Collaborez avec la CDK bibliothèque

Dans JavaScript