.arc Project Layout

Here we'll dig a bit deeper into how an Architect project is laid out and defined in the .arc manifest.

Quick .arc cheatsheet

Section Description
@app [Required] Defines your application namespace
Syntax: Lowercase alphanumeric string; maximum of 10 characters; dashes allowed; underscores not allowed; must begin with a letter
Example: hello-world-app
@aws Defines defines AWS variables
Syntax: Accepts either or both of two keys: region and profile
Example: region us-east-1
@domain Defines and assigns a domain name to your app (ACM, API Gateway, and Route 53)
Syntax: Standard domain characters and syntax; only use the FQDN, do not include protocol or path
Example: arc.codes
@events Defines SNS topics and Lambda handlers for them (SNS, Lambda)
Syntax: Lowercase alphanumeric string; maximum of 50 characters; dashes allowed; underscores not allowed; must begin with a letter
Example: hi
@http Defines generic HTTP routes (API Gateway, Lambda)
Syntax: get, post, put, patch, or delete followed by the desired path; must include leading slash; dashes and underscores not allowed; must begin with a letter; advised maximum of 100 characters; parameters denoted with colons (:)
Example: get /schwifty/:where
@indexes Defines table global secondary indexes (DynamoDB)
Syntax: Subset of @tables; please visit the @indexes reference for additional information on defining required keys and more
@queues Defines SQS queues and handlers for them (SQS, Lambda)
Syntax: Lowercase alphanumeric string; maximum of 50 characters; dashes allowed; underscores not allowed; must begin with a letter
Example: post /haste
@scheduled Defines functions that are invoked at specified times (CloudWatch Events)
Syntax: Lowercase alphanumeric string (maximum of 20 characters; dashes allowed; underscores not allowed; must begin with a letter) followed by a valid rate or cron expression (more info here)
Example: friyay-only cron(0 15 ? * FRI *)
@slack Defines HTTP handlers to build apps for the Slack API (API Gateway, Lambda)
Syntax: Lowercase alphanumeric string; maximum of 50 characters; dashes allowed; underscores not allowed; must begin with a letter
Example: hello-bot
@static Defines S3 buckets for hosting static assets (S3)
Syntax: Requires two arguments: staging and production, each followed by a valid globally unique S3 bucket name
Example:
staging test-bukkit
production main-bukkit
@tables Defines database tables and trigger functions for them (DynamoDB)
Valid (table names only): Lowercase alphanumeric string; between 3 and 255 characters; dashes allowed; underscores not allowed; must begin with a letter; please visit the @tables reference for additional information on defining required keys and more

One more thing: comments! Add comments in their own lines, or inline, with a #.

Example

Ok, let's provision a basic project with a simple .arc manifest!

Given the following .arc file:

# this is going to be great!
@app
testapp

@events
hello

@http
get /
get /posts # the posts go here

Running npx create creates the following code:

/
├── src
│   ├── events
│   │   └── hello/
│   ├── http
│   │   ├── get-index/
│   │   └── get-posts/
│   └── shared/
├── .arc
├── package.json
└── public/

The generated code was also immediately deployed to the built-in staging environment. Subsequent edits to the local code are deployed by running npx deploy.

Happy with staging? Ship a release to production by running npx deploy production.

Time to celebrate! ✨

Next: Learn how to work with HTTP functions