.arc Project Layout

Here we'll dig a bit deeper into how a arc 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 20 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
@css Defines HTTP routes that return text/css content (API Gateway, Lambda)
Syntax: desired path; must include leading slash; dashes and underscores not allowed; must begin with a letter; parameters denoted with colons (:)
Example: /path/to/your/new.css
@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
@html Defines HTTP routes that return text/html content (API Gateway, Lambda)
Syntax: get or post 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
@js Defines HTTP routes that return text/javascript content (API Gateway, Lambda)
Syntax: /path/to/your/new.js
@json Defines HTTP routes that return application/json content (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: post /haste
@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
@text Defines HTTP routes that return text/plain content (API Gateway, Lambda)
Syntax: desired path; must include leading slash; dashes and underscores not allowed; must begin with a letter; parameters denoted with colons (:)
Example: /path/to/your/plain.txt
@xml Defines HTTP routes that return application/xml content (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: put /thecookiedown

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

@html
get /

@json
get /posts # the posts go here

Running npx create creates the following code:

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

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 ARC_DEPLOY=production npx deploy.

Time to celebrate! ✨

Next: Learn how to work locally