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/             # … (optional) Static assets (can be renamed)
├── src/
│   ├── http/           # … (optional) All HTTP functions
│   │   └── get-foo/    # … (optional) HTTP route: `GET /foo`
│   ├── shared/         # … (optional) Shared code
|   └── views/          # … (optional) Shared frontend code
└── .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 (optional)

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 (optional)

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 (optional)

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/ (optional)

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, or to aim your static site generator at. The folder name is also configurable from the Static assets screen, too.

Learn more about working with public/ and static assets.

Note: assume the S3 bucket may fully sync with your public/ (or configured folder name) in your source control; anything not found there may be deleted from the S3 bucket during subsequent deployments.

Tests

tests/ (optional)

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

Most 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