Detailed AWS setup
To work locally all you need is Node, any additional supported runtimes you plan to use, and the Architect CLI.
AWS deployment requirements
- Node.js for Architect
- Python for the AWS CLI
- Any additional supported runtimes you plan to use in your application
- AWS CLI
- AWS credentials
- AWS SDK
- Architect CLI
Architect supports the following runtime versions:
- Unless otherwise specified in your project manifest, Node.js 16.x is the default runtime for new functions
⚠️ Working locally with the Sandbox requires target runtimes to be available in your
Additionally, all other standard AWS-managed runtimes are supported in Architect applications (but may not be supported in Sandbox), including:
Architect also supports any custom runtime in using either Lambda Layers or Lambda container images.
Change a project’s default runtime by specifying an explicit environment or an alias in
app.arc with the
# version pins the default runtime to Python 3.8 @aws runtime python3.8
# always run the latest supported version of Python @aws runtime python
ℹ️ This setting can be overridden on a per-function basis with
The AWS Command Line Interface is the main interface for interacting with all parts of AWS using your computer’s terminal. Architect uses the AWS CLI to package and deploy your app via CloudFormation. Follow this guide to installing the AWS CLI for your preferred environment.
You’ll need an Amazon Web Services account and credentials set up on your development machine and / or CI systems. If you haven’t yet set it up, here’s a useful guide for Configuring the AWS CLI.
In the context of a deployment tool, Architect requires account credentials with IAM
AdministratorAccess privileges. In turn, Architect will create and attach least-privilege IAM roles to runtime resources within your application, ensuring strict security boundaries by default.
ℹ️ While it is possible to limit Architect’s deployment credentials to specific IAM and CloudFormation privileges, such an exercise would only be performative. Credentials capable of creating IAM roles can grant and attach new roles with
On *nix systems AWS Credentials are listed in:
Or on Windows systems:
If that file doesn’t exist, create it, and add something like the following (assuming you have multiple AWS accounts):
[default] aws_access_key_id=xxx aws_secret_access_key=xxx [work] aws_access_key_id=xxx aws_secret_access_key=xxx [personal] aws_access_key_id=xxx aws_secret_access_key=xxx
While it is recommended to explicitly declare your application’s AWS profile and region in the
@aws pragma of your project’s manifest, you may also set a (default) profile and region with the
AWS_REGION environment variables.
Each Lambda runtime version includes its own built-in version of the AWS SDK. These versions are maintained and transparently upgraded by AWS.
Since the AWS SDK is an extremely large library, we strongly recommend you do not ship your own version as a dependency, either in full or as a bundle. Doing so may have some of the following unintended side effects:
- Slower Lambda coldstart and / or invocation
- Reduced available code payload size
- Possibly increased difficulty debugging (in the case of bundles)
Node.js AWS SDK versions
AWS maintains two versions of the AWS SDK for Node.js developers:
- v2 -
- v3 -
Lambda Node.js runtimes up to
nodejs16.x include AWS SDK v2 (
nodejs18.x, Lambda now includes AWS SDK v3 (
While v2 will likely continue to be maintained for some time to come, by making v3 the only available built-in version in
nodejs18.x AWS has signaled that they expect users to migrate to the new version, whether or not it is an actual improvement to developer experience.
Moreover, as the versions imply, v2 is largely incompatible with v3, and per the above recommendation, the version you should use in your handler code should correspond to the runtime you use. For example:
- If you have a Lambda running
nodejs16.x, we recommend against adding
@aws-sdk/*modules (until you are ready to migrate to
- Likewise, if you intend to run your Lambda on
nodejs18.x, we recommend against using
ℹ️ Upgrading to
nodejs18.x(and thus using AWS SDK v3) represents a meaningful change, and should be investigated thoroughly and with care. Key interfaces have been retired (such as
.promise()), and some core SDK methods have changed significantly. (Example:
S3.GetObjectno longer returns a Buffer.) However, you can likely safely and reliably upgrade if your handlers make use of
Architect’s AWS SDK strategy
A core goal of Architect is to make building Functional Web Apps simpler, and an important aspect of that objective is to help (automatically) manage the many dependencies in use across your Lambdas, whether your project has one or one hundred of them.
However, in the singular case of AWS SDK, AWS manages that dependency in particular. For the aforementioned reasons Architect does not attempt to automatically manage or include any version of AWS SDK.
Practically speaking, that means if, for example, you rely on Architect’s Lambda treeshaking feature – which scans your Lambda code and automatically installs
imported dependencies at deploy-time – any mismatched versions of the AWS SDK will not be automatically installed by Architect.
Architect will, however, attempt to provide helpful warnings where possible. For example: if your
aws-sdk, which is not built into the Lambda container, Architect will warn you of this during deployment.
Forward compatibility via
@architect/functions >= 5.3 papers over all possible breaking changes and incompatibilities between AWS SDK versions 2 and 3. This means if your Lambdas make use of
@architect/functions (and you otherwise do not directly rely on AWS SDK calls), you would very likely be fully forward-compatible with
nodejs18.x as of v5.3.
However, if your Lambdas do NOT make use of
@architect/functions, or make use of AWS SDK calls outside of the methods provided by
@architect/functions, before opting into Lambda
nodejs18.x + SDK v3 we strongly advise you investigate thoroughly and with care.
ℹ️ The one currently known caveat where
@architect/functionscannot paper over v2 → v3 is in
arc.tables()._docclient methods; see more here.
The following command uses
npm, the package manager for Node.js.
To create an entirely new Architect project:
npm init @architect ./testapp
npm init "@architect" ./testapp
To install Architect locally into an existing project:
npm init @architect ./testapp
npm init "@architect" ./testapp
Or you can install Architect globally, enabling you to use Architect from any directory on your computer. When doing so, you should also be sure to install the AWS SDK globally as well.
npm i -g @architect/architect aws-sdk