Permalink
Branch: master
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
158 lines (107 sloc) 5.35 KB

Overview

Begin applications are comprised of many small, fast, individually executing cloud functions. Let's take a look at the source tree of a basic Begin app:

.
β”œβ”€β”€ public/             # … Static assets
β”œβ”€β”€ src/
β”‚Β Β  β”œβ”€β”€ http/           # … HTTP Functions
β”‚Β Β  β”‚   └── get-index/  # … HTTP route: `GET /`
β”‚   β”œβ”€β”€ shared/         # … Shared code
|   └── views/          # … Shared frontend code
└── test/               # … Tests

Your app's many individually isolated cloud functions (or Functions, for short) are organized in your project under src/.

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

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 all the dependencies required for it to operate.

Here's the example project path of 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: 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.

Shared code

src/shared

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

When working locally, run npx hydrate to update your shared code across all Functions.

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

.
└── 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 across all your HTTP GET Functions.

This allows for more efficient front-end code sharing, preventing the unnecessary hydration of front-end code to non-GET and non-HTTP Functions.

When working locally, run npx hydrate to update your shared code across any pertinent 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 an S3 bucket for hosting or CDN distribution (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 deployments.

Tests

tests/

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

Begin apps come provisioned with tape and some boilerplate tests in this directory.

Caveats

  • 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
  • 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
  • Non-leaf node directories not mentioned in this doc will otherwise be ignored by Begin