Reference docs


Getting Started

Project structure

Overview

Begin applications are comprised of many small, fast, individually executing cloud functions (or Functions for short).

Let's take a look at the source tree of a basic Begin app:

.
├── public/             # … Static assets
├── src/
│   ├── http/           # … All Functions delivering HTTP responses
│   │   └── get-index/  # … HTTP route: `GET /`
│   ├── shared/         # … Shared code
|   └── views/          # … Shared frontend code
├── test/               # … Tests
└── .arc                # … Project manifest (read-only)

Each Function directory services a handler for a publicly available HTTP route (e.g. src/http/get-hello-world services GET /hello/world).

Your app's many individually isolated Functions are organized in your project under src/.

Business logic

src/http

Contains Function directories representing HTTP routes.

Each directory maps to its own individual, fully isolated, and independently deployable cloud function.

Function directories must contain an index.js file that services the cloud function handler, and any dependencies required for it to operate.

Here's an example project tree for a Function that handles the HTTP path POST /api/:itemID:

.
└── src/
    └── http/
        └── post-api-000itemID/
            ├── node_modules/
            ├── index.js
            ├── package-lock.json
            └── package.json

Note: New Function directories are generated by Begin. Learn more about creating new Functions.

Shared code

src/shared

This is a handy folder that makes its contents available across all your Functions under the @architect/shared namespace. Think: per-project globally installed modules.

Here's an example of how a file in src/shared would be available to a Function:

.
└── src/
    ├── http/
    │   └── post-api-000itemID/
    |       ├── node_modules/
    |       |   └── @architect/
    |       |       └── shared/
    |       |           └── constants.js
    |       └── index.js
    └── shared/
        └── constant.js

Here's what the require would look like for that file:

// src/http/post-api-000itemID/index.js
const Constants = require('@architect/shared/constants')
exports.handler = async function http(request) {
  return {
    type: 'text/html; charset=utf8',
    body: Constants.helloWorld
  }
}

You can install global dependencies to src/shared – but mind dependency bloat! Routes must weigh in under 5MB uncompressed.

src/views

Similar to src/shared, the src/views directory is another shared code utility folder. However this folder's contents are available only to your app's HTTP GET Functions.

This allows for more efficient front-end code sharing, preventing the unnecessary bloat of your front-end getting copied to your non-GET and/or non-HTTP Functions.

Here's an example of how a file in src/views would be available to an HTTP GET Function after hydration:

.
└── src/
    ├── http/
    │   └── get-index/
    |       ├── node_modules/
    |       |   └── @architect/
    |       |       └── views/
    |       |           └── layout.js
    |       └── index.js
    └── views/
        └── layout.js

Here's what the require would look like for that file:

// src/http/get-index/index.js
const Layout = require('@architect/views/layout')
exports.handler = async function http(request) {
  return {
    type: 'text/html; charset=utf8',
    body: Layout('Hello world!')
  }
}

Static assets

public/

Contents of the public directory are deployed to a secure blob store (S3) for hosting and distribution to your CDN (URLs for both of which can be found in your app's Settings screen).

This is a great place to place images and build artifacts!

Learn more about working with public/ and static assets.

Note: assume the S3 bucket will sync with your public/ in your source control; anything not found there may be deleted from the S3 bucket during subsequent deployments.

Tests

tests/

Test root for your app's tests (run locally via npm test)

Begin apps come provisioned with some basic tests in this directory.

Head here to learn more about writing tests in Begin.

Considerations

  • Function directories are generated by Begin; you can check in new Function dirs in src, but they will not provision new infrastructure. Learn more about creating new Functions.
  • Similarly, while you are totally encouraged to add files, subfolders, modules, etc. to your Functions, moving or renaming Function folders themselves will break your application. So don't do that – instead, create new resources and git mv your files on over.
  • Dependencies in your project's root package.json are not available to your Functions
    • To ensure a dependency is available to a given Function, cd into that Function's folder and install it there
  • Directories not mentioned in this doc will otherwise be ignored by Begin