Forem: SHAWNHOSEA

Apollo GraphQL & Begin starter example

SHAWNHOSEA — Thu, 08 Apr 2021 21:58:06 +0000

⏱ This tutorial is an introductory walkthrough of creating an Apollo GraphQL app on Begin. It should take less than 15 minutes.

Introduction

Hello there, Beginner!

This tutorial uses the Apollo GraphQL Begin starter example, extended by an example API endpoint.

What is GraphQL?

Created by Facebook in parallel with React, GraphQL is a query language that defines a set of constraints for APIs. It has a built-in server-side runtime for fulfilling those queries with your existing data. Basically, it is used to load data from a server to a client -- it’s a way to get data from an API into your application. The principles of GraphQL are extremely useful building blocks for web applications.

To learn more about GraphQL click here to check out their docs!

What is Apollo?

Apollo is the industry-standard GraphQL implementation, providing the data graph layer that connects modern apps to the cloud.

The Apollo platform is an implementation of GraphQL that can transfer data between the cloud (server) to the UI of your app. In fact, Apollo builds its environment in such a way that we can use it to handle GraphQL on the client as well as the server-side of the application.

To learn more about Apollo click here to checkout their docs!

Prerequisites

You will need to have git and Node.js installed to your local computer to follow along with this tutorial. (Learn more about installing git and installing Node.js.)

You'll also need a GitHub account. (Learn more about signing up with GitHub.)

This tutorial also assumes some familiarity with such things as:

Text editors
Terminal / CLI
Git and version control
General software development using JavaScript

You do not need to be an expert in any of these things in order to follow along and make your first Apollo app in Begin!

Getting started

Create your Apollo app

First, click the Deploy to Begin button below. This starts the process of authorizing Begin with your GitHub account. (You may be prompted to log into GitHub, and/or be asked to create a Begin username.)

Name your app & repo

You'll then be prompted to name your new app and repository – this is optional, feel free to use the default app and repo name if you like!

Note: your Begin app name and repository name cannot be changed later.

Once you've clicked the Create... button, Begin will spin up your new project on GitHub (under github.com/{your GH username}/{your repo name}).

By default your Begin app repo is created as a public GitHub repo; it can be set to private by granting Begin additional permissions from this screen (or later from the Settings screen found in the left nav of your Begin app).

Your first deploy

After creating your app, you'll be taken to its Activity stream. Welcome to the main backend interface of your Begin app!

From the Activity view, you'll be able to watch your app build & deploy in real-time. Any time you push to master, you'll see a new build get kicked off in Begin.

Each build undergoes a number of predefined build steps (learn more about build steps here); these build steps may install your app's dependencies (install), check your code's syntax for issues (lint), generate any files or assets needed to run your app (build), and/or run an automated test suite (test).

If no build steps fail, then the build containing your latest commit to master is automatically deployed to your staging environment.

Go ahead and click the Staging link in the upper left corner of your left nav to open your new app's staging URL. You should now see your basic Apollo GraphQL app:

💡 Learn more! Head here to dig deeper into covers build pipelines, git tagging, and more.

Make your first commit

If you'd like to jump right into making your first commit and running your first build, click the Edit on GitHub button. This will open your app's code in GitHub and allow you to make a quick change.

Look for this code, and try changing the text of the h1 to say My Begin + Apollo GraphQL API:

// Customize your site by changing the text of the h1
 <body>
    <h1 class="center-text">Begin + Apollo GraphQL API</h1> // Edit this line of code
    <section
      class="padding-0 background-color-dark border-radius-4"
    >
      <pre><code id="code" class="color-light">
        Loading...
      </code></pre>
    </section>

Click the commit changes button on GitHub, and head back to your Activity view to watch it build.

When it's done, don't forget to see your changes live in your staging environment!

Get set up locally

Next, let's get your new site running in your local environment (i.e. the computer you work on).

First, head to your GitHub repo (from the first card in your Activity, or from the left nav). Find the clone or download the button and copy the git URL.

Then head to your terminal and clone your repo to your local filesystem.

git clone https://github.com/your-github-username/your-new-begin-app.git

Once you've got your project cloned on your local machine, cd into the project directory, install your dependencies, and start the local dev server:

cd your-new-begin-app
npm install
npm start

You should see a localhost link in your terminal – go ahead and visit that in your browser.

That's all you need to do preview your changes locally before pushing them to staging!

Project structure

Now that your app is live on staging and running locally, let's take a quick look into how the project itself is structured so you'll know your way around. Here are the key folders in the source tree of your Apollo app:

.
├── public/
├── src/
│   └── http/
│       └── post-graphql/
└── test/

Let's go over each of these directories and how you may use them:

`public/`

The public directory is where we host our home page: index.html. Inside we have an example GraphQL query that pulls in data from our HTTP function using an async function that fetches our GraphQL data graph from src/http/post-graphql/index.js. We then append our query results to a DOM element using getElementById.

// public/index.html

 <!-- Example GraphQL query -->
 // Fetch data graph layer
  <script type=module>
    (async function() {
      let query = `{hello}`
      let result = await fetch('/graphql', {
        method: 'post',
        body: JSON.stringify({query}),
        headers: {
          'X-Requested-With': 'XMLHttpRequest',
          'Content-Type': 'application/json',
        }
      })
      let json = await result.json()
      console.log(json)

      // Append results to div element
      let code = document.getElementById('code')
      code.innerHTML = JSON.stringify(json, null, 2)
    })()
  </script>

`src/http/post-graphql/`

The POST /graphql function constructs a schema, using GraphQL schema language and then sets up a GraphQL server that will enforce our schema's structure. Afterwards, we provide resolver functions for your schema fields that will output our Hello World string! To learn more about GraphQL schemas, check out this section of the Apollo docs: Build a schema.

// src/http/post-graphql/index.js

let arc = require('@architect/functions')
let {ApolloServer, gql} = require('apollo-server-lambda')

// Construct a schema, using GraphQL schema language
let typeDefs = gql`
  type Query {
    hello: String
  }
`
// Provide resolver functions for your schema fields
let resolvers = {
  Query: {
    hello: () => 'Hello world!',
  },
}

let server = new ApolloServer({typeDefs, resolvers})
let handler = server.createHandler()

exports.handler = function(event, context, callback) {
  let body = arc.http.helpers.bodyParser(event)
  // Body is now parsed, re-encode to JSON for Apollo
  event.body = JSON.stringify(body)
  handler(event, context, callback)
}

In the next section, we will go more in-depth about how to provision HTTP functions in your Apollo GraphQL app by setting up a function that displays the GraphQL playground.

💡 Learn more! Head here to dig deeper into HTTP functions in Begin apps.

`src/test/`

Your Apollo GraphQL project comes built-in with a few boilerplate tests to ensure that things are running smoothly in your app. We've even loaded some example tests for web integration & Begin data in the src/test/example/ directory.

A solid platform is the foundation of a durable application, but tests are essential!

You can find the test script specified in package.json:

// package.json
{
  "scripts": {
    "test": "NODE_ENV=testing tape test/*-test.js | tap-spec"
  }
}

Tests run via npm test or npm t.

While you can use any test runner and reporter combo you want, we recommend the TAP family for testing. Test suites that require their runners to inject globals can create some very difficult to debug situations.

With that said, Jest, Enzyme, Mocha, etc. are all options available to you!

💡 Learn more! Head here to dig deeper into the project structure of Begin apps.

GraphQL Playground

The GraphQL Playground is an IDE (Integrated development environment) for better development workflows (GraphQL Subscriptions, interactive docs & collaboration). This playground is where you can test out your GraphQL queries for your app. You can learn more about the GraphQL Playground here.

Provision new route for GraphQL Playground

Let's make a new route that displays our GraphQL playground on its own page.

Ready to give it a go?

Head to your app’s repo folder
Open the app.arc file in your root
Find the @http pragma, and on a new line, add the route get /playground.
Start the local dev environment (npm start) to generate any new HTTP Function handlers
Push your changes!

Your new route(s) will instantly activate in staging. Then deploy to production to see them there, too.

If your app’s existing app.arc file has a commented warning about not editing it, go ahead and remove that – it's time to start editing that file!

Inside of your project folder, navigate to the src/http/get-playground/index.js file. This repo here provides the code that will display our playground. The code is also written below. Copy and paste this code inside of the index.js file.

<!DOCTYPE html>
<html>

<head>
  <meta charset=utf-8/>
  <meta name="viewport" content="user-scalable=no, initial-scale=1.0, minimum-scale=1.0, maximum-scale=1.0, minimal-ui">
  <title>GraphQL Playground</title>
  <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/graphql-playground-react/build/static/css/index.css" />
  <link rel="shortcut icon" href="//cdn.jsdelivr.net/npm/graphql-playground-react/build/favicon.png" />
  <script src="//cdn.jsdelivr.net/npm/graphql-playground-react/build/static/js/middleware.js"></script>
</head>

<body>
  <div id="root">
    <style>
      body {
        background-color: rgb(23, 42, 58);
        font-family: Open Sans, sans-serif;
        height: 90vh;
      }

      #root {
        height: 100%;
        width: 100%;
        display: flex;
        align-items: center;
        justify-content: center;
      }

      .loading {
        font-size: 32px;
        font-weight: 200;
        color: rgba(255, 255, 255, .6);
        margin-left: 20px;
      }

      img {
        width: 78px;
        height: 78px;
      }

      .title {
        font-weight: 400;
      }
    </style>
    <img src='//cdn.jsdelivr.net/npm/graphql-playground-react/build/logo.png' alt=''>
    <div class="loading"> Loading
      <span class="title">GraphQL Playground</span>
    </div>
  </div>
  <script>window.addEventListener('load', function (event) {
      GraphQLPlayground.init(document.getElementById('root'), {
        endpoint: '/graphql'
      })
    })</script>
</body>

</html>

Now let's add a button that will take us to our new playground route. Head to the public directory and open the index.html file. Add this block of code in between the <style> tag.

Add this block of code after the <section> tag inside of the <body>.

// public/index.html

  <a href="/playground">GraphQL Playground</a>

This link navigates to our new GraphQL playground.

Your new GraphQL playground is set up and connected to your data graph. Test out some new queries grow your database!

Deploy your site

While not required, it's always a good idea to lint and run tests before pushing just to make sure you catch any errors:

npm run lint
npm t

Everything set? Now let's push this commit (and deploy the build to staging):

git add -A
git commit -am 'Just customizing my Begin site!'
git push origin master

Head on back to Begin and open your staging URL once your build is complete. Looking good? Excellent!

Now let's deploy to production: click the Deploy to production button in the upper left, pick a version, leave an optional message summarizing your changes, and Ship it!

When your next build is done, click the production link in the upper left corner to see the latest release of your app!

✨Tip: You can also deploy to production from your terminal by bumping your npm version (npm version [patch|minor|major] && git push origin) or by cutting a git tag (git tag -a 1.0.0 -m "1.0, here we come" && git push origin --tags)

Congratulations!

You've now got a shiny new Apollo GraphQL app hosted on Begin – nice work.

Now go show it off – people need to see this thing!

Additional resources

Expand the capabilities of your app:
- Creating new routes
- Add Begin Data
Begin reference docs
Get help:
- Begin community
- Issue tracker
More about Apollo
More about GraphQL

Getting started using Vue on Begin

SHAWNHOSEA — Thu, 08 Apr 2021 21:02:59 +0000

⏱ This tutorial is an introductory walkthrough of creating a Vue app on Begin. It should take less than 15 minutes.

Introduction

Hello there, Beginner!

This tutorial uses the Vue starter app, extended by an example API endpoint. You'll have all the capabilities of Vue for building beautiful user interfaces, combined with the power, speed, and security of cloud functions and serverless data storage.

What is Vue.js?

Vue (pronounced like view) is a progressive framework for building user interfaces. The core library is focused on the view layer only and is easy to pick up and integrate with other libraries or existing projects. On the other hand, Vue is also perfectly capable of powering sophisticated Single-Page Applications when used in combination with modern tooling and supporting libraries.

If you’d like to learn more about Vue before diving in, here is a video walking through the core principles of Vue and a sample project.

Prerequisites

You will need to have git and Node.js installed to your local computer to follow along with this tutorial. (Learn more about installing git and installing Node.js.)

You'll also need a GitHub account. (Learn more about signing up with GitHub.)

Although it would be helpful to have some experience with Vue, it's not required to follow along with this tutorial. (Related, the Vue docs are a great reference.)

This tutorial also assumes some familiarity with such things as:

Text editors
Terminal / CLI
Git and version control
General software development using JavaScript

You do not need to be an expert in any of these things in order to follow along and make your first Vue app in Begin!

Getting started

Create your new Vue app

Name your app & repo

You'll then be prompted to name your new app and repository – this is optional, feel free to use the default app and repo name if you like!

Note: your Begin app name and repository name cannot be changed later.

Once you've clicked the Create... button, Begin will spin up your new project on GitHub (under github.com/{your GH username}/{your repo name}).

By default your Begin app repo is created as a public GitHub repo; it can be set to private by granting Begin additional permissions from this screen (or later from the Settings screen found in the left nav of your Begin app).

Your first deploy

After creating your app, you'll be taken to its Activity stream. Welcome to the main backend interface of your Begin app!

From the Activity view, you'll be able to watch your app build & deploy in real-time. Any time you push to master, you'll see a new build get kicked off in Begin.

Each build undergoes a number of predefined build steps (learn more about build steps here); these build steps may install your app's dependencies (install), test your code's syntax (lint), generate any files or assets needed to run your app (build), and/or run an automated test suite (test).

If no build steps fail, then the build containing your latest commit to master is automatically deployed to your staging environment.

Go ahead and click the Staging link in the upper left corner of your left nav to open your new app's staging URL. You should now see your Vue app:

💡 Learn more! Head here to dig deeper into covers build pipelines, git tagging, and more.

Make your first commit

Look for this code, and try editing your basic app. Let's edit the <h2> tag that says "Change me!" to "My app!":

// Customize your site by changing the data below
return (
  <template>
  <div class="hello">
    <h1>{{ message }}</h1>
    <h2>Change me</h2> // Start by editing here!
    <p>
      For a guide and recipes on how to configure / customize this project,<br>
      check out the
      <a href="https://cli.vuejs.org" target="_blank" rel="noopener">vue-cli documentation</a>.
    </p>

Click the commit changes button on GitHub, and head back to your Activity view to watch it build.

When it's done, don't forget to see your changes live in your staging environment!

Get set up locally

Next, let's get your new site running in your local environment (i.e. the computer you work on).

First, head to your GitHub repo (from the first card in your Activity, or from the left nav). Find the clone or download button and copy the git URL.

Then head to your terminal and clone your repo to your local filesystem.

git clone https://github.com/your-github-username/your-new-begin-app.git

Once you've got your project cloned on your local machine, cd into the project directory, install your dependencies, and start the local dev server:

cd your-new-begin-app
npm install
npm start

You should see a localhost link in your terminal – go ahead and visit that in your browser.

That's all you need to do preview your changes locally before pushing them to staging!

Vue CLI

Vue CLI is a command-line interface that acts as standard tooling for Vue.js development. It's feature-rich with out-of-the-box support for Babel, Typescript, ESLint, Unit Testing & End-to-end Testing. You create, develop and manage your projects through an accompanying graphical user interface. It's really cool and you might want to set it up in your project for future use. We'll show you how to do that.

Getting Started

Since we've already created our project and have it set up locally on our machine, all we have to do is install the CLI globally and run the command to start the GUI(graphical user interface)

Install globally:

npm install -g @vue/cli
# OR
yarn global add @vue/cli

Start GUI:

vue ui

Once you start the GUI, you will see this screen load up in your browser on http://localhost:8000
Our project is already on our local machine so let's click the import button to sync our project and the GUI.

Look for your begin-vue-app project folder and click import this folder as shown in the screen below.

Now we're synced. Welcome to your new project! Vue CLI and the accompanying GUI tool give you tremendous insight and analytics into your Vue app.

💡 Learn more! Be sure to head over to the Vue CLI docs to learn everything that you can do with these Vue development tools.

Project structure

Now that your app is live on staging and running locally, let's take a quick look into how the project itself is structured so you'll know your way around. Here are the key folders and files in the source tree of your Vue app:

.
├── public/
├── src/
│    ├── assets/
│    ├── components/
│    ├── http/
│    │   └── get-api/
│    ├── App.vue
│    └── main.js
└── test/

Let's go over each of these directories & files and learn how you may use them:

`public/index.html`

public/index.html is the page served in the browser. Vue is a single-page application framework. It's used to create single-page applications(SPA). It loads just one file which is the index.html file. The div with an id of app (as seen in the code below) is a placeholder for our Vue application.

// public/index.html

  <div id="app"></div>

The file public/index.html is a template that will be processed with html-webpack-plugin. During build, asset links will be injected automatically.

`src/assets/`

All of our apps static assets(images) can be exported from this folder and imported into our components via relative paths.
When you reference a static asset using relative paths (must start with .) inside JavaScript, CSS or *.vue files, the asset will be included into your Webpack dependency graph.

`src/components/`

You guessed it. This directory is where we keep our apps components.

Components are one of the most powerful features of Vue.js and can be reused as many times as you want. They help you extend basic HTML elements to encapsulate reusable code. At a high level, components are custom elements that Vue.js’ compiler would attach specified behavior to. Think of them as reusable Vue instances with a name!

💡 Learn more! Go here to learn more about using components in Vue.

`src/http/get-api/`

The cloud function that handles example API requests is found at src/http/get-api/.

Some Begin apps are inert static web sites – but not this one. Your Vue app utilizes this built-in small, fast, individually executing cloud function that handles HTTP API requests and responses. (We call those HTTP functions, for short.)

The HTTP function that handles requests to GET /api is found in src/http/get-api/.

In the next section, we will go more in-depth about how to provision HTTP functions in your Vue app.

💡 Learn more! Head here to dig deeper into HTTP functions in Begin apps.

`./App.vue`

This ./App.vue file is a component that is structured like any other component you would build inside of a Vue application. It has a template tag for our markup that is loading an image from our src/assets folder and another component called HelloWorld.vue from our src/components folder.

The script tag is for our JS and where we import in our HelloWorld component.

The style tag is for our CSS styling. In this particular component the styles affect our app globally. Whenever you see a <style scoped> tag inside of a component, just know that those particular styles are scoped only to that particular component.

`main.js`

In our src folder you will find a main.js file which is the entry point into Vue. Here we import Vue and our main app component which is a file called ./App.vue.

We create a new Vue instance and we render the app component inside of an element with the id of app. This would be the div in public/index.html that has an id of 'app'.

`src/test/`

Your Vue project comes built-in with a few boilerplate tests to ensure that things are running smoothly in your app. We've even loaded some example tests for web integration & Begin data in the /test/example/ directory.

A solid platform is the foundation of a durable application, but tests are essential!

Tests run via npm test or npm t.

With that said, Vue CLI has built-in options for unit testing with Jest or Mocha that works out of the box. There is also the official Vue Test Utils which provides more detailed guidance for custom setups.

💡 Learn more! Head here to dig deeper into the project structure of Begin apps.

Using API endpoints

Now for the fun part! Let's go over how HTTP functions work.

The text in the red box below is actually being fetched from an example API endpoint, handled by src/http/get-api/index.js.

The output of this HTTP function can be called by fetching GET /api, and subsequently used by any component within your Vue app:

// src/http/get-api/index.js

exports.handler = async function http (req) {
  console.log('Begin API called')
  return {
    statusCode: 200,
    headers: {
      'content-type': 'application/json; charset=utf8',
      'cache-control': 'no-cache, no-store, must-revalidate, max-age=0, s-maxage=0'
    },
    body: JSON.stringify({
      message: 'Hello from your Begin API!'
    })
  }
}

Now let's navigate to src/App.vue to see how this HTTP function is being implemented into your app. ./App.vue is our apps root component. Inside of the script tag you will find an import of our HelloWorld component. This component actually holds and displays the data from our Begin endpoint. As you can see below, GET /api/ is fetched via async function.

// src/App.vue

<script>
import HelloWorld from './components/HelloWorld.vue'

export default {
  name: 'app',
  data: function () {
    return {
      message: 'Loading...'
    }
  },
  components: {
    HelloWorld
  },
  methods:  {
    getData: async function () {
      try {
        let data = await (await fetch('api')).json()
        this.message = data.message
      } catch (err) {
        this.message = err.message
      }
    }
  },
  mounted: function () {
    this.getData()
  }
}
</script>

Then if we head over to our /components/HelloWorld.vue we'll find the h1 receiving the message prop being passed down from our apps root component ./App.vue

<template>
  <div class="hello">
    <h1>{{ message }}</h1> // data passed in.
    <h2>Change me</h2>

As you can probably see by now, being able to fetch and display data within your app serverlessly is an awesome way to extend the capabilities of your Vue app.

Deploy your site

While not required, it's always a good idea to lint and run tests before pushing just to make sure you catch any errors:

npm run lint
npm t

Everything set? Now let's push this commit (and deploy the build to staging):

git add -A
git commit -am 'Just customizing my Begin site!'
git push origin master

Head on back to Begin and open your staging URL once your build is complete. Looking good? Excellent.

Now let's deploy to production: click the Deploy to production button in the upper left, pick a version, leave an optional message summarizing your changes, and Ship it!

When your next build is done, click the production link in the upper left corner to see the latest release of your app.

✨Tip: You can also deploy to production from your terminal by bumping your npm version (npm version [patch|minor|major] && git push origin) or by cutting a git tag (git tag -a 1.0.0 -m "1.0, here we come" && git push origin --tags)

Congratulations!

You've now got a shiny new Vue app hosted on Begin – nice work.

Now go show it off – people need to see this thing!

Additional resources

Expand the capabilities of your app:
- Creating new routes
- Add Begin Data
Begin reference docs
Get help:
- Begin community
- Issue tracker
More about Vue

Create React App starter running on Begin.

SHAWNHOSEA — Thu, 08 Apr 2021 14:07:34 +0000

⏱ This tutorial is an introductory walkthrough of creating a React app on Begin. It should take less than 15 minutes.

Introduction

Hello there, Beginner!

This tutorial uses the Create React App starter app, extended by an example API endpoint. You'll have all the capabilities of React for building beautiful user interfaces, combined with the power, speed, and security of cloud functions and serverless data storage.

Prerequisites

You will need to have git and Node.js installed to your local computer to follow along with this tutorial. (Learn more about installing git and installing Node.js.)

You'll also need a GitHub account. (Learn more about signing up with GitHub.)

Although it would be helpful to have some experience with React, it's not required to follow along with this tutorial. (Related, the React docs are a great reference.)

This tutorial also assumes some familiarity with such things as:

Text editors
Terminal / CLI
Git and version control
General software development using JavaScript

You do not need to be an expert in any of these things in order to follow along and make a React app in Begin!

Getting started

Create your new React app

Name your app & repo

You'll then be prompted to name your new app and repository – this is optional, feel free to use the default app and repo name if you like!

Note: your Begin app name and repository name cannot be changed later.

Once you've clicked the Create... button, Begin will spin up your new project on GitHub (under github.com/{your GH username}/{your repo name}).

By default your Begin app repo is created as a public GitHub repo; it can be set to private by granting Begin additional permissions from this screen (or later from the Settings screen found in the left nav of your Begin app).

Your first deploy

After creating your app, you'll be taken to its Activity stream. Welcome to the main backend interface of your Begin app!

From the Activity view, you'll be able to watch your app build & deploy in real-time. Any time you push to master, you'll see a new build get kicked off in Begin.

If no build steps fail, then the build containing your latest commit to master is automatically deployed to your staging environment.

Go ahead and click the Staging link in the upper left corner of your left nav to open your new app's staging URL. You should now see your react app:

💡 Learn more! Head here to dig deeper into covers build pipelines, git tagging, and more.

Make your first commit

Look for this code, and try editing your basic app. Let's edit the <p> tag that says "Change me!" to "My app!":

// Customize your site by changing the data below
return (
  <div className="App">
    <header className="App-header">
      <img src={logo} className="App-logo" alt="logo" />
      <p>{message}</p>
      <p>Change Me!</p> // ← Start by editing this!

Click the commit changes button on GitHub, and head back to your Activity view to watch it build.

When it's done, don't forget to see your changes live in your staging environment!

Get set up locally

Next let's get your new site running in your local environment (i.e. the computer you work on).

First, head to your GitHub repo (from the first card in your Activity, or from the left nav). Find the clone or download button and copy the git URL.

Then head to your terminal and clone your repo to your local filesystem.

git clone https://github.com/your-github-username/your-new-begin-app.git

Once you've got your project cloned on your local machine, cd into the project directory, install your dependencies, and start the local dev server:

cd your-new-begin-app
npm install
npm start

You should see a localhost link in your terminal – go ahead and visit that in your browser.

That's all you need to do preview your changes locally before pushing them to staging!

Project structure

.
├── api/
│    └── index.js
├── build/
├── public/
├── src/
│    └── App.js
└── test/

Let's go over each of these directories and files and how you may use them:

`api/`

The api folder is where the cloud function that handles GET requests to /api lives. When we call our api from our app it will execute the handler function in the index.js file.

Some Begin apps are inert static websites – but not this one. Your React app utilizes this built-in small, fast, individually executing cloud function that handles HTTP API requests and responses. (We call those HTTP functions, for short.)

In the next section, we will go more in-depth about how to provision HTTP functions in your React app.

💡 Learn more! Head here to dig deeper into HTTP functions in Begin apps.

`build/`

The build folder is where your React app will build into (and be served from locally). Since this folder contains build artifacts, it isn't checked into git and shouldn't be directly modified. Instead, let your app re-build its contents.

Each time your app is deployed by Begin, the build artifacts in build will automatically be published to your app's static asset bucket (on S3) as well as Begin's CDN.

`public/`

Per Create React App convention, files placed into public are not processed, and will instead be copied into build when your app is built.

Add images (like your logo) and any other static assets or files to public to make them publicly accessible in your app. Learn more about the public folder.

`src/App.js`

Along with the other boilerplate React app files (src/App.css, src/App-test.js, etc.), src/App.js serves as the primary entry point for your React app. This is a great place to start tinkering with your app.

`src/test/`

Your React project comes built-in with a few boilerplate tests to ensure that things are running smoothly in your app. We've even loaded some example tests for web integration & Begin data in the src/test/example/ directory.

A solid platform is the foundation of a durable application, but tests are essential!

You can find the test script specified in package.json:

// package.json
{
  "scripts": {
    "test": "NODE_ENV=testing tape test/*-test.js | tap-spec"
  }
}

Tests run via npm test or npm t.

With that said, Jest, Enzyme, React Testing Library, etc. are all options available to you!

💡 Learn more! Head here to dig deeper into the project structure of Begin apps.

Using API endpoints

Now for the fun part! Let's go over how HTTP functions work.

The text in the red box below is actually being fetched an example API endpoint, handled by api/index.js.

The output of this HTTP function can be called by fetching GET /api, and subsequently used by any component within your React app:

// api/index.js

exports.handler = async function http (req) {
  console.log('Begin API called')
  return {
    statusCode: 200,
    headers: {
      'content-type': 'application/json; charset=utf8',
      'cache-control': 'no-cache, no-store, must-revalidate, max-age=0, s-maxage=0'
    },
    body: JSON.stringify({
      message: 'Hello from your Begin API!'
    })
  }
}

Now let's navigate to src/App.js to see how this HTTP function was being implemented into your app. As you can see below, GET /api/ is fetched via async function wrapped in a React hook (useEffect).

// src/App.js

const App = () => {
  const [message, setMessage] = useState('...loading')

  useEffect(() => {
    async function fetchData () {
      try {
        let data = await (await fetch('/api')).json()
        setMessage(data.message)
      } catch (err) {
        setMessage(err.message)
      }
    }
    fetchData()
  })

  return (
    <div className="App">
      <header className="App-header">
        <img src={logo} className="App-logo" alt="logo" />
        <p>{message}</p>
        <p>Change me!</p>
        <p>
          Edit <code>src/App.js</code> and save to reload.
        </p>
        <a
          className="App-link"
          href="https://reactjs.org"
          target="_blank"
          rel="noopener noreferrer"
        >
          Learn React
        </a>
      </header>
    </div>
  );
}

This is just one small example of how using a live API endpoint powered by an HTTP function can make your React app dynamic. Just think of all the things you can build this way!

Deploy your site

While not required, it's always a good idea to lint and run tests before pushing just to make sure you catch any errors:

npm run lint
npm t

Everything set? Now let's push this commit (and deploy the build to staging):

git add -A
git commit -am 'Just customizing my Begin site!'
git push origin master

Head on back to Begin and open your staging URL once your build is complete. Looking good? Excellent.

Now let's deploy to production: click the Deploy to production button in the upper left, pick a version, leave an optional message summarizing your changes, and Ship it!

When your next build is done, click the production link in the upper left corner to see the latest release of your app.

✨Tip: You can also deploy to production from your terminal by bumping your npm version (npm version [patch|minor|major] && git push origin) or by cutting a git tag (git tag -a 1.0.0 -m "1.0, here we come" && git push origin --tags)

Congratulations!

You've now got a shiny new React app hosted on Begin – nice work.

Now go show it off – people need to see this thing!

Additional resources

Expand the capabilities of your app:
- Creating new routes
- Add Begin Data
Begin reference docs
Get help:
- Begin community
- Issue tracker
More about React:

Setting up a Svelte app running on Begin

SHAWNHOSEA — Thu, 08 Apr 2021 13:51:22 +0000

⏱ This tutorial is an introductory walkthrough of creating a Svelte app on Begin. It should take less than 5 minutes.

Introduction

Hello there, Beginner!

This tutorial walks through setting up a Svelte app running on Begin. Svelte is a new approach to building user interfaces; unlike many frontend frameworks that do the bulk of their work in the browser (like React and Vue), Svelte shifts that work into a compile step that happens when you build your app. Today you'll learn how to create a Svelte app powered by Begin HTTP functions.

Prerequisites

You will need to have git and Node.js installed to your local computer to follow along with this tutorial. (Learn more about installing git and installing Node.js.)

You'll also need a GitHub account. (Learn more about signing up with GitHub.)

This tutorial also assumes some familiarity with such things as:

Text editors
Terminal / CLI
Git and version control
General software development using JavaScript

You do not need to be an expert in any of these things in order to follow along and make a Svelte app in Begin!.

Getting started

Create your Svelte app

Name your app & repo

You'll then be prompted to name your new app and repository – this is optional, feel free to use the default app and repo name if you like!

Note: your Begin app name and repository name cannot be changed later.

Once you've clicked the Create... button, Begin will spin up your new project on GitHub (under github.com/{your GH username}/{your repo name}).

By default your Begin app repo is created as a public GitHub repo; it can be set to private by granting Begin additional permissions from this screen (or later from the Settings screen found in the left nav of your Begin app).

Your first deploy

After creating your app, you'll be taken to its Activity stream. Welcome to the main backend interface of your Begin app!

From the Activity view, you'll be able to watch your app build & deploy in real-time. Any time you push to master, you'll see a new build get kicked off in Begin.

If no build steps fail, then the build containing your latest commit to master is automatically deployed to your staging environment.

Go ahead and click the Staging link in the upper left corner of your left nav to open your new app's staging URL. You should now see your basic Svelte app:

💡 Learn more! Head here to dig deeper into covers build pipelines, git tagging, and more.

Make your first commit

Look for this code, and try changing the text of the h3 tag and the color of the h1 tag:

// Customize your site by changing the color of the h1
<script>
  import { onMount } from 'svelte'
  export let name;
  export let message;
  onMount(async () => {
    let data = await (await fetch('/api')).json()
    message = data.msg
    console.log('MESSAGE: ', message)
  })
</script>

<main>
  <h1>Hello {name}!</h1>
  <h2>{message}</h2>
  <h3>Change me!</h3> // <-- Change text!
  <p>Visit the <a href="https://svelte.dev/tutorial">Svelte tutorial</a> to learn how to build Svelte apps.</p>
</main>

<style>
  main {
    text-align: center;
    padding: 1em;
    max-width: 240px;
    margin: 0 auto;
  }

  h1 {
    color: #ff3e00; // <-- change color!
    text-transform: uppercase;
    font-size: 4em;
    font-weight: 100;
  }

  @media (min-width: 640px) {
    main {
      max-width: none;
    }
  }
</style>

Click the commit changes button on GitHub, and head back to your Activity view to watch it build.

When it's done, don't forget to see your changes live in your staging environment!

Get set up locally

Next, let's get your new site running in your local environment (i.e. the computer you work on).

First, head to your GitHub repo (from the first card in your Activity, or from the left nav). Find the clone or download button and copy the git URL.

Then head to your terminal and clone your repo to your local filesystem.

git clone https://github.com/your-github-username/your-new-begin-app.git

Once you've got your project cloned on your local machine, cd into the project directory, install your dependencies, and start the local dev server:

cd your-new-begin-app
npm install
npm run dev

You should see a localhost link in your terminal – go ahead and visit that in your browser.

That's all you need to do preview your changes locally before pushing them to staging!

Project structure

.
├── public/
├── src/
│   ├── http/
│   │   └── get-api/
│   ├── App.svelte
│   └── main.mjs
└── rollup.config.js

Let's go over each of these directories and how you may use them:

`public/`

The public directory is where you'll add images and any other static assets or files you want to make publicly accessible in your app.

Each time your app deploys, the contents of this folder will automatically be published to your app's static asset bucket on S3 and Begin's CDN.

This is also where your component-level CSS & JS are bundled, as well as your app's global CSS, which affects the entirety of your app's styling.

Exercise caution! The full contents of this folder will be copied with each deploy, overwriting any existing files with the same name.

`src/http/get-api/`

The cloud function that handles requests to your site is found at src/http/get-api/.

Some Begin apps are inert static web sites – but not this one. Your Svelte app is built on a small, fast, individually executing cloud function that handles your HTTP requests and responses. (We call those HTTP functions, for short.)

The HTTP function that handles requests to GET /api is found in src/http/get-api/.

In the next section we will go more in-depth about how to provision HTTP functions in your Svelte app.

💡 Learn more! Head here to dig deeper into HTTP functions in Begin apps.

`src/main.js`

The main entry point for your Svelte app, src/main.js imports your App.svelte file (your root app component). In this example, we initialize your app to document.body and pass it a prop to demonstrate how props can be passed along to different components inside of your app.

`src/App.svelte`

src/App.svelte is what's referred to as a single file component – it contains all of the code needed to display your frontend. The opening <script> tag contains JavaScript, and in this example it receives in props from src/main.js:

<script>
  import { onMount } from 'svelte'
  export let name;
  export let message;
  onMount(async () => {
    let data = await (await fetch('/api')).json()
    message = data.msg
    console.log('MESSAGE: ', message)
  })
</script>

Right below the <script> tag we have a section for our HTML – <main> – which can render variables from your script tag inside {curly brackets}:

<main>
  <h1>Hello {name}!</h1>
  <h2>{message}</h2>
  <h3>Change me!</h3>
  <p>Visit the <a href="https://svelte.dev/tutorial">Svelte tutorial</a> to learn how to build Svelte apps.</p>
</main>

Lastly, at the bottom of src/App.svelte we have a <style> tag, which contains all the CSS for this specific component.

`rollup.config.js`

Rollup is a module bundler for JavaScript which compiles small pieces of code into something larger and more complex, such as a library or application. It allows us to use ES modules import syntax so that we may create component-based applications. This config file bundles all of your component-level CSS and JS into the public directory.

Using API endpoints

Extending your Svelte app with HTTP functions may be why you're here, right? Let's take a look at how all this works.

Let's start with the src/App.svelte code inside <script> tag found below. When the component renders initially into a page or "mounts", we're able to use what's called a lifecycle method called onMount, which is provided by the Svelte framework. Inside this onMount handler we fetch data from src/http/get-api/ and then set the variable named message with the returned data. We're now able to pass this variable into our HTML as props so that it displays a message from our HTTP function. Not bad, right?

// src/App.svelte

// JavaScript
<script>
  import { onMount } from 'svelte'
  export let name;
  export let message;
  onMount(async () => {
    let data = await (await fetch('/api')).json()
    message = data.msg
    console.log('MESSAGE: ', message)
  })
</script>

// HTML
<main>
  <h1>Hello {name}!</h1>
  <h2>{message}</h2>
  <h3>Change me!</h3>
  <p>Visit the <a href="https://svelte.dev/tutorial">Svelte tutorial</a> to learn how to build Svelte apps.</p>
</main>

This is just one small example of how using a live API endpoint powered by an HTTP function can make your Svelte app dynamic. Just think of all the things you can build this way!

Deploy your site

While not required, it's always a good idea to lint and run tests before pushing just to make sure you catch any errors:

npm run lint
npm t

Everything set? Now let's push this commit (and deploy the build to staging):

git add -A
git commit -am 'Just customizing my Begin site!'
git push origin master

Head on back to Begin and open your staging URL once your build is complete. Looking good? Excellent!

Now let's deploy to production: click the Deploy to production button in the upper left, pick a version, leave an optional message summarizing your changes, and Ship it!

When your next build is done, click the production link in the upper left corner to see the latest release of your app!

✨Tip: You can also deploy to production from your terminal by bumping your npm version (npm version [patch|minor|major] && git push origin) or by cutting a git tag (git tag -a 1.0.0 -m "1.0, here we come" && git push origin --tags)

Congratulations!

You've now got a shiny new Svelte app hosted on Begin – nice work.

Now go show it off – people need to see this thing!

Additional resources

Expand the capabilities of your app:
- Creating new routes
- Add Begin Data
Begin reference docs
Get help:
- Begin community
- Issue tracker
More about Svelte

Begin personal website example app

SHAWNHOSEA — Thu, 08 Apr 2021 13:16:25 +0000

⏱ This tutorial is an introductory walkthrough of creating a personal website on Begin. It should take less than 5 minutes.

Introduction

Hello there, Beginner!

This tutorial walks through setting up a fast, beautiful, custom personal site running on Begin. It uses example code that demonstrates server-side rendering, shared components, and static assets.

Prerequisites

You will need to have git and Node.js installed to your local computer to follow along with this tutorial. (Learn more about installing git and installing Node.js.)

You'll also need a GitHub account. (Learn more about signing up with GitHub.)

This tutorial also assumes some familiarity with such things as:

Text editors
Terminal / CLI
Git and version control
General software development using JavaScript

You do not need to be an expert in any of these things in order to follow along and make a new personal website with Begin!

Let's get started!

Get stoked, here's a little preview of your new site:

Getting started

Create your new personal website

Name your app & repo

You'll then be prompted to name your new app and repository – this is optional, feel free to use the default app and repo name if you like!

Note: your Begin app name and repository name cannot be changed later.

Once you've clicked the Create... button, Begin will spin up your new project on GitHub (under github.com/{your GH username}/{your repo name}).

By default your Begin app repo is created as a public GitHub repo; it can be set to private by granting Begin additional permissions from this screen (or later from the Settings screen found in the left nav of your Begin app).

Your first deploy

After creating your app, you'll be taken to its Activity stream. Welcome to the main backend interface of your Begin app!

From the Activity view, you'll be able to watch your app build & deploy in real-time. Any time you push to master, you'll see a new build get kicked off in Begin.

If no build steps fail, then the build containing your latest commit to master is automatically deployed to your staging environment.

Go ahead and click the Staging link in the upper left corner of your left nav to open your new app's staging URL. You should now see your personal site:

💡 Learn more! Head here to dig deeper into covers build pipelines, git tagging, and more.

Make your first commit

Look for this code, and try editing your basic bio (like your name or location):

// Customize your site by changing the data below
exports.handler = async function Index () {
  let body = Main({
    /**
     * Basic bio
     */
    fullname: 'Your Name', // ← Start by adding your name!
    title: 'My personal site!',
    occupation: 'Artist & Photographer',
    location: 'West Glacier, MT',
    bio: 'Lorem ipsum dolor sit amet...',

Click the commit changes button on GitHub, and head back to your Activity view to watch it build.

When it's done, don't forget to see your changes live in your staging environment!

Get set up locally

Next let's get your new site running in your local environment (i.e. the computer you work on).

First, head to your GitHub repo (from the first card in your Activity, or from the left nav). Find the clone or download button and copy the git URL.

Then head to your terminal and clone your repo to your local filesystem.

git clone https://github.com/your-github-username/your-new-begin-app.git

Once you've got your project cloned on your local machine, cd into the project directory, install your dependencies, and start the local dev server:

cd your-new-begin-app
npm install
npm start

You should see a localhost link in your terminal – go ahead and visit that in your browser.

That's all you need to do preview your changes locally before pushing them to staging!

Project structure

.
├── public/
└── src/
    ├── http/
    │   └── get-index/
    └── views/

Let's go over each of these directories and how you may use them:

`public/`

The public directory where you'll add images (like the background image for your site) and any other static assets or files you want to make publicly accessible in your app.

Each time your app deploys, the contents of this folder will automatically be published to your app's static asset bucket (on S3) as well as Begin's CDN.

Exercise caution! The full contents of this folder will be copied with each deploy, overwriting any existing files with the same name.

`src/http/get-index/`

The cloud function that handles requests to your site is found at src/http/get-index/.

Some Begin apps are inert static web sites – but not this one. Your personal website is built on a small, fast, individually executing cloud function that handles your HTTP requests and responses. (We call those HTTP functions, for short.)

The HTTP function that handles requests to the root of your app (GET /) is found in src/http/get-index/.

`src/views/`

By default, the contents of src/views/ gets copied into each of your project's GET HTTP functions (at node_modules/@architect/views for Node, or vendor/views for Ruby and Python) whenever you start the local dev server (or deploy your app).

This means the modules in this folder can be used by any GET HTTP function in your app.

For example, here's how you'd require src/views/main.js:

let layout = require('@architect/views/main')

💡 Learn more! Head here to dig deeper into the project structure of Begin apps.

Customize your site

Now for the fun part! Let's customize your personal website and really make it your own.

You've already changed the default name. Now let's add your social media links and change the background image.

As you saw earlier, /src/http/get-index/index.js is a great place to get started updating the content of your site. Open that file in your editor:

Now let's input your social media handles in place of the dummy data. Go ahead and change the values of the email, twitter, linkedin, instagram, and facebook keys – or remove any you don't want to keep.

// src/http/get-index/index.js

const Main = require('@architect/views/main.js')
const staticAssetsHelper = require('./static-assets-helper')

// Customize your site by changing the data below
exports.handler = async function Index () {
  let body = Main({
    /**
     * Basic bio
     */
    fullname: 'Your Name', // ←  Start by adding your name!
    title: 'My personal site!',
    occupation: 'Artist & Photographer',
    location: 'West Glacier, MT',
    bio: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Quis ipsum suspendisse ultrices gravida. Risus commodo viverra maecenas accumsan lacus vel facilisis.',

    /**
     * Contact / social
     * - Comment out any item below to remove it from your page
     */
    email: 'your@email.com',
    twitter: 'yourTwitter',
    linkedin: 'your-linkedin-name',
    instagram: 'yourInsta',
    facebook: 'your-facebook-name',

    /**
     * Layout
     */
    photographer: 'Ivana Cajina',
    service: 'Unsplash',
    credit: 'https://unsplash.com/@von_co',
    image: staticAssetsHelper('background.jpg')
    // or link to an external image URL such as ↓
    // image: 'https://images.unsplash.com/photo-1506535772317-9fdb71c959c6'
  })

  return {
    statusCode: 200,
    headers: {
      'content-type': 'text/html; charset=utf8',
      'cache-control': 'no-cache, no-store, must-revalidate, max-age=0, s-maxage=0'
    },
    body
  }
}

View source

Now we'll update your background image. Grab a new one Unsplash (or wherever you please) and place it in the public/. Let's name this new image background-2.jpg.

Go back to /src/http/get-index/index.js and replace the current reference to background.jpg with background-2.jpg.

You may notice that your background image is being returned by a module named staticAssetHelper. This helper demonstrates how to load static assets with the correct URLs locally, in staging, and via the Begin CDN in production.

Ok, let's see the finished product. With your local dev server running (npm start), preview your site.

That's one beautiful personal website you've got there – customized to your liking! Time to deploy and show the world what you've just created.

Deploy your site

While not required, it's always a good idea to lint and run tests before pushing just to make sure you catch any errors:

npm run lint
npm t

Everything set? Now let's push this commit (and deploy the build to staging):

git add -A
git commit -am 'Just customizing my Begin site!'
git push origin master

Head on back to Begin and open your staging URL once your build is complete. Looking good? Excellent.

Now let's deploy to production: click the Deploy to production button in the upper left, pick a version, leave an optional message summarizing your changes, and Ship it!

When your next build is done, click the production link in the upper left corner to see the latest release of your app.

✨Tip: You can also deploy to production from your terminal by bumping your npm version (npm version [patch|minor|major] && git push origin) or by cutting a git tag (git tag -a 1.0.0 -m "1.0, here we come" && git push origin --tags)

Congratulations!

You've now got a shiny new personal website hosted on Begin – nice work.

Now go show it off – people need to see this thing!

Additional resources

Expand the capabilities of your app:
- Creating new routes
- Add Begin Data
Begin reference docs
Get help:
- Begin community
- Issue tracker

CRUD app with data persistence

SHAWNHOSEA — Thu, 08 Apr 2021 12:48:25 +0000

⏱ This tutorial is an introductory walkthrough using Begin Data as your application's database. It should take less than 10 minutes.

Introduction

Begin Data is an easy to use, fast, durable, highly scalable, fully managed, SSD-based key-value and document database built on top of AWS DynamoDB. And access to it is available for every Begin app!

You can think of Begin Data as syntactic sugar for making DynamoDB easier to work with. Designed to accommodate most general persistence use cases, its core API has three simple methods: get, set, and destroy.

In this tutorial, we'll show you how to set up and start using Begin Data with a simple todo CRUD app.

Prerequisites

You will need to have git and Node.js installed to your local computer to follow along with this tutorial. (Learn more about installing git and installing Node.js.)

You'll also need a GitHub account. (Learn more about signing up with GitHub.)

This tutorial also assumes some familiarity with such things as:

Text editors
Terminal / CLI
Git and version control
General software development using JavaScript

You do not need to be an expert in any of these things in order to follow along and make your first database-enabled app in Begin!

Getting started

Name your app & repo

You'll then be prompted to name your new app and repository – this is optional, feel free to use the default app and repo name if you like!

Note: your Begin app name and repository name cannot be changed later.

Once you've clicked the Create... button, Begin will spin up your new project on GitHub (under github.com/{your GH username}/{your repo name}).

By default your Begin app repo is created as a public GitHub repo; it can be set to private by granting Begin additional permissions from this screen (or later from the Settings screen found in the left nav of your Begin app).

Your first deploy

After creating your app, you'll be taken to its Activity stream. Welcome to the main backend interface of your Begin app!

From the Activity view, you'll be able to watch your app build & deploy in real-time. Any time you push to master, you'll see a new build get kicked off in Begin.

If no build steps fail, then the build containing your latest commit to master is automatically deployed to your staging environment.

Go ahead and click the Staging link in the upper left corner of your left nav to open your new app's staging URL. You should now see your new app:

💡 Learn more! Head here to dig deeper into covers build pipelines, git tagging, and more.

Get set up locally

Next let's get your new site running in your local environment (i.e. the computer you work on).

First, head to your GitHub repo (from the first card in your Activity, or from the left nav). Find the clone or download button and copy the git URL.

Then head to your terminal and clone your repo to your local filesystem.

git clone https://github.com/your-github-username/your-new-begin-app.git

Once you've got your project cloned on your local machine, cd into the project directory and install your dependencies:

cd your-new-begin-app
npm install

Project structure

Now that your app is live on staging and running locally, let's take a quick look into how the project itself is structured so you'll know your way around. Here are the key folders and files in the source tree of your new todo app:

.
├── public/
└── src/
    └── http/
         ├── get-todos/
         ├── post-todos/
         └── post-todos-delete/

Let's go over each of these directories and how you may use them:

`public/`

The public directory is where we host our home page: index.html. This is also where our app's CSS styles and JavaScript live. Here, we'll fetch our todos from our HTTP functions and append them to elements in the DOM while manipulating the state of our app.

`src/http/get-todos/`

The GET /todos function allows you to read the current todos from your Begin Data todos table; these items are created by way of the HTML form on the home page.

// `src/http/get-todos/index.js`

let data = require('@begin/data')

exports.handler = async function todos (req) {
  let todos = await data.get({
    table: 'todos'
  })
  // Return oldest todo first
  todos.sort((a, b) => a.created > b.created)
  return {
    statusCode: 201,
    headers: {
      'content-type': 'application/json; charset=utf8',
      'cache-control': 'no-cache, no-store, must-revalidate, max-age=0, s-maxage=0'
    },
    body: JSON.stringify({
      todos
    })
  }
}

`src/http/post-todos/`

The POST /todos function creates or updates todos in your Begin Data todos table when input is posted from your app's HTML form.

// `src/http/post-todos/index.js`

let arc = require('@architect/functions')
let data = require('@begin/data')

exports.handler = async function post (req) {
  let todo = arc.http.helpers.bodyParser(req) // Base64 decodes + parses body
  todo.created = todo.created || Date.now()
  todo.completed = !!todo.completed
  await data.set({
    table: 'todos',
    ...todo
  })
  return {
    statusCode: 302,
    headers: {
      'location': '/',
      'cache-control': 'no-cache, no-store, must-revalidate, max-age=0, s-maxage=0'
    }
  }
}

`src/http/post-todos-delete/`

The POST /todos/delete function deletes any of the todos from your Begin Data todos table.

// `src/http/post-todos-delete/index.js`

let arc = require('@architect/functions')
let data = require('@begin/data')

exports.handler = async function destroy (req) {
  let key = arc.http.helpers.bodyParser(req).key // Base64 decodes + parses body
  await data.destroy({
    table: 'todos',
    key
  })
  return {
    statusCode: 302,
    headers: {
      'location': '/',
      'cache-control': 'no-cache, no-store, must-revalidate, max-age=0, s-maxage=0'
    }
  }
}

Add Begin Data

First things first. We must always require Begin Data at the top of our functions. The arc variable here is used for parsing request bodies in our functions. Follow the link to learn more about parsing request bodies.

let arc = require('@architect/functions')
let data = require('@begin/data')

Begin Data API

The core Begin Data API is three methods:

data.get(params[, callback]) → [Promise] for retrieving data
data.set(params[, callback]) → [Promise] for writing data
data.destroy(params[, callback]) → [Promise] for removing data

Some additional helper methods are also available:

data.incr(params[, callback]) → [Promise] increment an attribute on an item
data.decr(params[, callback]) → [Promise] decrement an attribute on an item
data.count(params[, callback]) → [Promise] get the number of items for a given table

All methods accept an object and, optionally, a Node-style errback. If no errback is supplied, a Promise is returned (thus, all methods support async / await).

Writes

Let's start by saving a single item to a table with the set method. We identify the table with the table parameter, and can optionally specify a key:

let taco = await data.set({
  table: 'tacos',
  key: 'al-pastor'
})

Since all items have a key, if no key is specified, a unique key will automatically be generated:

let token = await data.set({
  table: 'tokens',
})
// { table: 'tokens', key: 'LCJkYX9jYWwidW50RhSU' }

We can also batch save multiple items to multiple tables by passing set an array of objects:

let collection = await data.set([
  { table: 'ppl', name:'grace', email:'ghopper@navy.mil' },
  { table: 'ppl', name:'sutr0', email:'sutr0@harbl.net' },
  { table: 'tacos', key:'pollo' },
  { table: 'tacos', key:'carnitas' }
])

Reads

Read an item by key with the get method:

let yum = await data.get({
  table: 'tacos',
  key: 'baja'
})

As with set, get can also batch-read by passing it an array of objects. With these building blocks you can construct secondary indexes and joins, like one-to-many and many-to-many!

await data.get([
  { table: 'tacos', key: 'carnitas' },
  { table: 'tacos', key: 'al-pastor' }
])

Destroy

Delete an item by key with the destroy method:

await data.destroy({
  table: 'tacos',
  key: 'pollo'
})

Yep, you guessed it: you can also batch-read delete items bypassing destroy an array of objects.

await data.destroy([
  { table: 'tacos', key: 'carnitas' },
  { table: 'tacos', key: 'al-pastor' }
])

Begin Data in action

So how do all of these HTTP functions come together to compose the core functionality of the app? This happens inside public/index.html. In your index file, the <script> contains the code doing the heavy client-side lifting. Now let's take a look a bit closer at what's going on there.

First, we fetch all the todos that currently reside on in the database. To ensure that that this fetch call always runs when the page is loaded, our business logic is immediately invoked:

// Get all todos
function init () {
  fetch('/todos', {
    credentials: 'same-origin',
    headers: {
      'Content-Type': 'application/json'
    }
  })
  .then(res => res)
  .then(body => body.json())
  // Call update with fetched todos
  .then(json => update(json.todos))
}

// Kick off the app
init()

Now we'll define a set of variables (see: document.getElementById calls) that will append the correct state and data in our DOM (see: innerHTML calls):

// Update the DOM with data
function update(todos) {
  let list = document.getElementById('js-todos')
  let completed = document.getElementById('js-completed')
  let message = document.getElementById('js-message')
  let current = todos.filter(t => !t.completed)
  let complete = todos.filter(t => t.completed)
  let doneTitle = document.getElementById('js-done-title')
  let done = complete.length && !current.length
  let none = !complete.length && !current.length
  if (none) {
    message.innerHTML = Message({
      src: '/_static/rocket.svg',
      text: 'Let\'s get started!',
      alt: 'Rocket'
    })
  } else if (done) {
    message.innerHTML = Message({
      src: '/_static/astronaut.svg',
      text: 'You did it!',
      alt: 'Astronaut'
    })
  }

  if (complete.length) {
    doneTitle.classList.toggle('display-none')
  }

  list && current.length
    ? list.innerHTML = current.map(t => Todo(t)).join('')
    : ''

  completed && complete.length
    ? completed.innerHTML = complete.map(t => Todo(t)).join('')
    : ''
}

Deploy your site

While not required, it's always a good idea to lint and run tests before pushing just to make sure you catch any errors:

npm run lint
npm t

Everything set? Now let's push this commit (and deploy the build to staging):

git add -A
git commit -am 'Just customizing my Begin site!'
git push origin master

Head on back to Begin and open your staging URL once your build is complete. Looking good? Excellent!

Now let's deploy to production: click the Deploy to production button in the upper left, pick a version, leave an optional message summarizing your changes, and Ship it!

When your next build is done, click the production link in the upper left corner to see the latest release of your app.

✨Tip: You can also deploy to production from your terminal by bumping your npm version (npm version [patch|minor|major] && git push origin) or by cutting a git tag (git tag -a 1.0.0 -m "1.0, here we come" && git push origin --tags)

Congratulations!

You've just built a CRUD todo app and API, and understand how Begin Data can persist data for your application's storage needs.

Now go show it off – people need to see this thing!

Learn more about DynamoDB

AWS DynamoDB is a fully managed, highly durable, non-relational key value and document database for applications that need performance at any scale.

Learn more about DynamoDB here!

Additional resources

Expand the capabilities of your app:
- Creating new routes
- Add Begin Data
Begin reference docs
Get help:
- Begin community
- Issue tracker

Begin scheduled functions

SHAWNHOSEA — Thu, 08 Apr 2021 07:53:25 +0000

⏱ This tutorial is an introductory walkthrough on creating scheduled functions with Begin. It should take less than 10 minutes.

Introduction

Begin scheduled functions are an integral part of automating the background processes of your app. They enable you to set up recurring tasks to run on an interval.

This gives you the ability to do things like regularly back up your application's database, or generate monthly reports based on user interactions. They are the serverless equivalent of a cron job.

In this tutorial, we'll show you how you can backup some data in your Begin app with scheduled functions. First, let's discuss how to set up your project and get started.

Prerequisites

You will need to have git and Node.js installed to your local computer to follow along with this tutorial. (Learn more about installing git and installing Node.js.)

You'll also need a GitHub account. (Learn more about signing up with GitHub.)

This tutorial also assumes some familiarity with such things as:

Text editors
Terminal / CLI
Git and version control
General software development using JavaScript

You do not need to be an expert in any of these things to follow along though.

Getting started

First, click the Deploy to Begin button below. This starts the process of authorizing Begin with your GitHub account. (You may be prompted to log in to GitHub, and/or be asked to create a Begin username.)

Name your app & repo

You'll then be prompted to name your new app and repository – this is optional, feel free to use the default app and repo name if you like!

Note: your Begin app name and repository name cannot be changed later.

Once you've clicked the Create... button, Begin will spin up your new project on GitHub (under github.com/{your GH username}/{your repo name}).

By default your Begin app repo is created as a public GitHub repo; it can be set to private by granting Begin additional permissions from this screen (or later from the Settings screen found in the left nav of your Begin app).

Your first deploy

After creating your app, you'll be taken to its Activity stream. Welcome to the main backend interface of your Begin app!

From the Activity view, you'll be able to watch your app build & deploy in real-time. Any time you push to master, you'll see a new build get kicked off in Begin.

Each build undergoes several predefined build steps (learn more about build steps here); these build steps may install your app's dependencies (install), test your code's syntax (lint), generate any files or assets needed to run your app (build), and/or run an automated test suite (test).

If no build steps fail, then the build containing your latest commit to master is automatically deployed to your staging environment.

Go ahead and click the Staging link in the upper left corner of your left nav to open your new app's staging URL. You should now see your new app:

Hit the refresh button in your browser to see the view count rise higher. We'll learn more about what this application is doing under the hood after we've set up our project locally.

💡 Learn more! Head here to dig deeper into covers build pipelines, git tagging, and more.

Get set up locally

Next, let's get your new site running in your local environment (i.e. the computer you work on).

First, head to your GitHub repo (from the first card in your Activity, or the left nav). Find the clone or download button and copy the git URL.

Then head to your terminal and clone your repo to your local filesystem.

git clone https://github.com/your-github-username/your-new-begin-app.git

Once you've got your project cloned on your local machine, cd into the project directory and install your dependencies:

cd your-new-begin-app
npm install

Now you are all set to work on your app locally!

Project structure

.
├── src/
│   ├── http/
│   │   └── get-index/
│   ├── scheduled/
│   │   └── backup/
│   └── views/
│       └── doc.js
└── app.arc

`src/http/get-index/`

This is the root function of our app that serves the view. We must note that we are getting the actual HTML from our shared views directory (src/views), which we'll discuss below. This function is also incrementing and storing each page view into your app's Begin Data database.

// src/http/get-index/index.js

let data = require('@begin/data')
let HTML = require('@architect/views/doc')

exports.handler = async function http (req) {
  let { path } = req
  let visits

  if (path === '/') {
    let result = await data.incr({
      table: 'my-data',
      key: 'site',
      prop: 'visits'
    })
    visits = result.visits
    console.log('Stored a visit')
  }

  return {
    statusCode: 200,
    headers: {
      'cache-control': 'no-cache, no-store, must-revalidate, max-age=0, s-maxage=0',
      'content-type': 'text/html; charset=utf8'
    },
    body: HTML({ visits })
  }
}

`src/scheduled/backup/`

This is our scheduled function – the star of the app! We use this function to back up the view counts collected in Begin Data. This backup function's rate is defined in our app.arc file.

// src/scheduled/backup/index.js

const data = require('@begin/data')

exports.handler = async function scheduled (event) {
  console.log(JSON.stringify(event, null, 2))
  let pages = await data.page({
    table: 'my-data',
    limit: 100
  })

  let count = 0
  for await (let page of pages) {
    count = count + 1
    console.log(
      'Page: ', page, '\n',
      'Count: ', count, '\n'
    )
  }
  // Now save a copy wherever you like (S3, POST to an external endpoint, etc.)!
  return
}

`src/views/doc.js`

This file is serving the HTML view of our app. Every module inside our views folder is available to all of our GET functions. Note: for brevity, the actual HTML contents of this file are truncated.

// src/views/doc.js

module.exports = function Doc({ visits }) {
  visits = visits || ''
  return `
<!DOCTYPE html>
<html lang="en">
  ...
</html>
  `
}

`app.arc`

Your app.arc file is where you'll provision new scheduled functions and other infra for your app. (In this particular app, you'll see that we have provisioned a scheduled function named backup with a rate every 6 hours.)

Infrastructure-as-code is the practice of provisioning and maintaining cloud infrastructure using a declarative manifest file. It’s like package.json, except for cloud resources like API Gateway, Lambda, and DynamoDB (all of which Begin apps use).

By checking in your Begin app’s project manifest (app.arc) file with your code, you can ensure you have the cloud resources your code depends on. This is crucial for guaranteeing reproducibility and improving iteration speed.

💡 Learn more! Head here to dig deeper into provisioning and working with scheduled functions in Begin apps.

How scheduled functions work in this app

This app is designed to demonstrate the power of scheduled functions and Begin data.

Inside the app.arc file in the root of your project, we've added an entry to the @scheduled pragma to provision a new scheduled function named backup. This function runs on a 6 hour interval (rate(6 hours)) that backs up the current number of page views (which are written to the database by our get-index function). You can save this backup wherever you'd like, such as an S3 bucket.

⚠️ Scheduled function names are lowercase alphanumeric and can contain dashes. They must declare a rate with a number, and a time period with the appropriate singular / plural form, e.g. rate(1 day), rate(2 weeks)

Read more about the rate syntax here

You'll notice below the view count that there is a link to your scheduled functions logs inside the your Begin console. Clicking the link will take you this page to view these logs for your scheduled functions!

Awesome! Now let's move on to deploying this app to production.

Deploy your site

While not required, it's always a good idea to lint and run tests before pushing just to make sure you catch any errors:

npm run lint
npm t

Everything set? Now let's push this commit (and deploy the build to staging):

git add -A
git commit -am 'Just customizing my Begin site!'
git push origin master

Head on back to Begin and open your staging URL once your build is complete. Looking good? Excellent.

Now let's deploy to production: click the Deploy to production button in the upper left, pick a version, leave an optional message summarizing your changes, and Ship it!

When your next build is done, click the production link in the upper left corner to see the latest release of your app.

✨Tip: You can also deploy to production from your terminal by bumping your npm version (npm version [patch|minor|major] && git push origin) or by cutting a git tag (git tag -a 1.0.0 -m "1.0, here we come" && git push origin --tags)

Congratulations!

You now have a good idea of how scheduled functions work within Begin. Your next task is to learn Begin Data!

Now go show it off – people need to see this thing!

Additional resources

Expand the capabilities of your app:
- Creating new routes
- Add Begin Data
Begin reference docs
Get help:
- Begin community
- Issue tracker

Begin event functions

SHAWNHOSEA — Thu, 08 Apr 2021 07:36:12 +0000

⏱ This tutorial is an introductory walkthrough on creating event functions with Begin. It should take less than 10 minutes.

Introduction

Getting started with Begin event functions should take just a few minutes, but lay the groundwork for creating your own publish / subscribe message bus for your application.

Asynchronous tasks are a very common requirement in most modern applications. For example: say someone signs up for your newsletter.

You don’t want your user to wait around for your application to respond while it makes API calls to your mailing list service.

Instead, what you probably want is to publish a JSON payload to a dedicated, asynchronous subscribing event listener — this is commonly known as the pub / sub (or publish / subscribe) model.

In this tutorial, we'll show you how you can kick off background tasks in your Begin app with event functions. First, let's discuss how to set up your project and get started.

Prerequisites

You will need to have git and Node.js installed to your local computer to follow along with this tutorial. (Learn more about installing git and installing Node.js.)

You'll also need a GitHub account. (Learn more about signing up with GitHub.)

This tutorial also assumes some familiarity with such things as:

Text editors
Terminal / CLI
Git and version control
General software development using JavaScript

You do not need to be an expert in any of these things to follow along though.

Getting started

First, click the Deploy to Begin button below. This starts the process of authorizing Begin with your GitHub account. (You may be prompted to log in to GitHub, and/or be asked to create a Begin username.)

Name your app & repo

You'll then be prompted to name your new app and repository – this is optional, feel free to use the default app and repo name if you like!

Note: your Begin app name and repository name cannot be changed later.

Once you've clicked the Create... button, Begin will spin up your new project on GitHub (under github.com/{your GH username}/{your repo name}).

By default your Begin app repo is created as a public GitHub repo; it can be set to private by granting Begin additional permissions from this screen (or later from the Settings screen found in the left nav of your Begin app).

Your first deploy

After creating your app, you'll be taken to its Activity stream. Welcome to the main backend interface of your Begin app!

From the Activity view, you'll be able to watch your app build & deploy in real-time. Any time you push to master, you'll see a new build get kicked off in Begin.

If no build steps fail, then the build containing your latest commit to master is automatically deployed to your staging environment.

Go ahead and click the Staging link in the upper left corner of your left nav to open your new app's staging URL. You should now see your new app:

We'll learn more about what these three buttons do after the project is set up locally.

💡 Learn more! Head here to dig deeper into covers build pipelines, git tagging, and more.

Get set up locally

Next, let's get your new site running in your local environment (i.e. the computer you work on).

First, head to your GitHub repo (from the first card in your Activity, or the left nav). Find the clone or download button and copy the git URL.

Then head to your terminal and clone your repo to your local filesystem.

git clone https://github.com/your-github-username/your-new-begin-app.git

Once you've got your project cloned on your local machine, cd into the project directory and install your dependencies:

cd your-new-begin-app
npm install

Now you are all set to work on your app locally!

Project structure

.
├── public/
│   └── index.html
├── src/
│   ├── events/
│   │   └── my-event/
│   └── http/
│       └── post-my_event/
└── app.arc

`public/index.html`

public/index.html is the page served to the browser. Your app's styling can be found inside of this file along with our button form elements taking in attributes from the HTTP function post-my_event.

`src/events/my-event/`

Your app utilizes this built-in small, fast, individually executing cloud function that handle subscribing to events – (We call those event functions, for short.)

After receiving an incoming payload published from another function, this event handler then executes its business logic. (To tidy up the incoming event payloads, we suggest running your event functions through our runtime library, Architect Functions – which this example already does.)

`src/http/post-my_event/`

As we just mentioned, the recommended (and easiest) way to work with events is the Architect Functions. In this project, our HTTP post /my-event uses Architect Functions to publishing to the my-event event.

`app.arc`

Your app.arc file is where you will provision new events and functions.

By checking in your Begin app’s project manifest (app.arc) file with your code, you can ensure you have exactly the cloud resources your code depends on. This is crucial for ensuring reproducibility and improving iteration speed.

💡 Learn more! Head here to dig deeper into provisioning and working with event functions in Begin apps.

How events work in this app

This app is designed to demonstrate the power of event functions and Begin data. Each button is wire to an event publisher that increments a counter in the backend when clicked. Let's see what this looks like in code.

This is our event publisher:

// src/http/post-my_event/index.js

const arc = require('@architect/functions')

exports.handler = async function http (req) {
  const name = 'my-event'
  const payload = arc.http.helpers.bodyParser(req)
  await arc.events.publish({ name, payload })
  return {
    statusCode: 302,
    headers: {
      location: '/'
    }
  }
}

When you click on one of the three buttons, it posts to the post /my-event endpoint above, which in turn publishes an event to the my-event event subscriber.

Our subscriber holds updates an atomic counter whenever it receives a new event; to do this we have a table named interactions with key of clicks, which we'll increment with each invocation.

// src/events/my-event/index.js

const arc = require('@architect/functions')
const data = require('@begin/data')
const table = 'interactions'
const key = 'clicks'

async function myEvent(event) {
  let { name } = event
  await data.incr({
    table,
    key,
    prop: name
  })

  return
}

exports.handler = arc.events.subscribe(myEvent)

That’s it, you’re done! Now you have an infinitely scalable pub / sub message bus at your disposal, meaning your application can respond quickly to user requests, and handle complex background tasks asynchronously.

Our goal at Begin is to unlock the full power of modern application architectures with minimal effort and complexity. With Begin event functions, the potential capabilities of your apps just grew enormously!

Deploy your site

While not required, it's always a good idea to lint and run tests before pushing just to make sure you catch any errors:

npm run lint
npm t

Everything set? Now let's push this commit (and deploy the build to staging):

git add -A
git commit -am 'Just customizing my Begin site!'
git push origin master

Head on back to Begin and open your staging URL once your build is complete. Looking good? Excellent.

Now let's deploy to production: click the Deploy to production button in the upper left, pick a version, leave an optional message summarizing your changes, and Ship it!

When your next build is done, click the production link in the upper left corner to see the latest release of your app.

✨Tip: You can also deploy to production from your terminal by bumping your npm version (npm version [patch|minor|major] && git push origin) or by cutting a git tag (git tag -a 1.0.0 -m "1.0, here we come" && git push origin --tags)

Congratulations!

You now have a good idea of how event functions work within Begin. Your next task is to learn Begin Data!

Now go show it off – people need to see this thing!

Additional resources

Expand the capabilities of your app:
- Creating new routes
- Add Begin Data
Begin reference docs
Get help:
- Begin community
- Issue tracker

Begin HTTP functions

SHAWNHOSEA — Thu, 08 Apr 2021 06:50:55 +0000

⏱ This tutorial is an introductory walkthrough on creating HTTP Functions with Begin. It should take less than 10 minutes.

Introduction

Getting started with Begin HTTP functions should take just a few minutes, but lay the groundwork for creating your own APIs. In this article, you will learn how to provision a new function and then fetch JSON data from it to display in your app's frontend. This will be a great introduction to what goes in an HTTP function and how to use them to deliver data to your apps.

Prerequisites

You will need to have git and Node.js installed to your local computer to follow along with this tutorial. (Learn more about installing git and installing Node.js.)

You'll also need a GitHub account. (Learn more about signing up with GitHub.)

This tutorial also assumes some familiarity with such things as:

Text editors
Terminal / CLI
Git and version control
General software development using JavaScript

You do not need to be an expert in any of these things in order to follow along though.

Getting started

Name your app & repo

You'll then be prompted to name your new app and repository – this is optional, feel free to use the default app and repo name if you like!

Note: your Begin app name and repository name cannot be changed later.

Once you've clicked the Create... button, Begin will spin up your new project on GitHub (under github.com/{your GH username}/{your repo name}).

By default your Begin app repo is created as a public GitHub repo; it can be set to private by granting Begin additional permissions from this screen (or later from the Settings screen found in the left nav of your Begin app).

Your first deploy

After creating your app, you'll be taken to its Activity stream. Welcome to the main backend interface of your Begin app!

From the Activity view, you'll be able to watch your app build & deploy in real-time. Any time you push to master, you'll see a new build get kicked off in Begin.

If no build steps fail, then the build containing your latest commit to master is automatically deployed to your staging environment.

Go ahead and click the Staging link in the upper left corner of your left nav to open your new app's staging URL. You should now see your new app:

💡 Learn more! Head here to dig deeper into covers build pipelines, git tagging, and more.

Get set up locally

Next let's get your new site running in your local environment (i.e. the computer you work on).

First, head to your GitHub repo (from the first card in your Activity, or from the left nav). Find the clone or download button and copy the git URL.

Then head to your terminal and clone your repo to your local filesystem.

git clone https://github.com/your-github-username/your-new-begin-app.git

Once you've got your project cloned on your local machine, cd into the project directory and install your dependencies:

cd your-new-begin-app
npm install

Now you are all set to work on your app locally!

Add an HTTP function

Provisioning an HTTP Function

Create a new route in five easy steps

Make sure you are in your project's folder on your computer
Open the app.arc file in the root of your project
Find (or add) the @http pragma, and on a new line, add a route ( get /api )
Start the local dev environment (npm start) to generate any new HTTP Function handlers
Push your changes!

Your new route will automatically deploy to staging.
If you are happy with staging you can click the "Deploy to Production" button to see it live on your production environment.

For more in-depth instructions on how to provision new HTTP functions, you can checkout our docs here or this article on our blog.

Writing HTTP functions

We must first understand the anatomy of an HTTP function to be able to write them for our specific use cases. All basic HTTP functions consist of one handler function.

  exports.handler = async function(req) {
    console.log('REQUEST OBJECT: ', req);
  }

HTTP functions are invoked when you navigate to a URL in your app. This get /api function we just generated by running npm start is called when we navigate our browser to localhost:3333/api. These HTTP functions are passed a request object or req which contains information about the request to this function. Any data we return from this function is available to our app running in the browser, all we need to do now is request it.

💡 Learn more! To learn more about HTTP functions by reading this article from the Architect docs.

Project structure

.
├── public/
│   ├── index.html
│   └── index.js
├── src/
│   └── http/
│        └── get-api/
└── app.arc

`public/index.html` & `public/index.js`

public/index.html is the page served to the browser. This is where our JSON data will be appended to a DOM element of our choosing. public/index.js is where we will write our function that fetches the JSON data from get /api and displays it in our HTML page.

`src/http/get-api/`

Your app utilizes this built-in small, fast, individually executing cloud function that handles HTTP API requests and responses. (We call those HTTP functions, for short.)

The HTTP function that handles requests to get /api is found in src/http/get-api/.

In the next section, we will go more in-depth about how to fetch data from an HTTP Function.

`app.arc`

Your app.arc file is where you will provision new routes and functions.

💡 Learn more! Head here to dig deeper into provisioning and working with HTTP functions in Begin apps.

Fetching data from HTTP functions

Earlier we provisioned a new function called get /api. We will use this function to create an API that sends out a JSON object with a key:value pair of message: Hello from your Begin API!. Navigate to src/http/get-api/index.js and copy & paste the code below. Now you can fetch data from this function from anywhere inside of your app!

// src/http/get-api/index.js

exports.handler = async function http (req) {
  console.log('Begin API called')
  return {
    statusCode: 200,
    headers: {
      'content-type': 'application/json; charset=utf8',
      'cache-control': 'no-cache, no-store, must-revalidate, max-age=0, s-maxage=0'
    },
    body: JSON.stringify({
      message: 'Hello from your Begin API!'
    })
  }
}

Now navigate to localhost:3333/api to see your message being returned from you new API!

Now let's fetch this JSON data from our API and display it in our HTML page. First navigate to the root of your app and then open the public/index.html directory. Find the section below and add this <p> element with an id of #myData:

<!--public/index.html -->

 <div>
      <p style="margin-bottom: 8px">
        View documentation at:
      </p>
      <a class="link" href="https://docs.begin.com" target="_blank">https://docs.begin.com</a>
    </div>
    <p id="myData">...Testing</p>  <!-- Add this line.-->
</div>

Now open the public/index.js file and replace it's contents to use this function. This async function will fetch the JSON data from our API, the get /api function we provisioned earlier and then append it to the DOM.

// public/index.js
(async function main() {
  // Get a reference to the element to display our data in
  let display = document.getElementById('myData')
  // Declare a message variable to be set later
  let message
  try {
    // Attempt to fetch data from our API
    let data = await (await fetch('/api')).json()
    console.log(data)
    message = data.message
  } catch (err) {
    // If there was an error catch it and display the message
    console.log(err)
    message = err.message
  }
  // If we created the display element and added the ID correctly
  if (display) {
    // Show the message
    display.innerHTML = message
  }
}())

Now you can see the data from our get /api HTTP Function is being requested by our frontend code via fetch then displayed on our HTML page.

Deploy your site

While not required, it's always a good idea to lint and run tests before pushing just to make sure you catch any errors:

npm run lint
npm test

Everything set? Now let's push this commit (and deploy the build to staging):

git add -A
git commit -am 'Just customizing my Begin site!'
git push origin master

Head on back to Begin and open your staging URL once your build is complete. Looking good? Excellent.

Now let's deploy to production: click the Deploy to production button in the upper left, pick a version, leave an optional message summarizing your changes, and Ship it!

When your next build is done, click the production link in the upper left corner to see the latest release of your app.

✨Tip: You can also deploy to production from your terminal by bumping your npm version (npm version [patch|minor|major] && git push origin) or by cutting a git tag (git tag -a 1.0.0 -m "1.0, here we come" && git push origin --tags)

Congratulations!

You now have a good idea on how HTTP functions work within Begin. Your next task is to learn Begin Data!

Now go show it off – people need to see this thing!

Additional resources

Expand the capabilities of your app:
- Creating new routes
- Add Begin Data
Begin reference docs
Get help:
- Begin community
- Issue tracker

Begin Quickstart

SHAWNHOSEA — Thu, 08 Apr 2021 04:35:01 +0000

⏱ This guide should require less than 5 minutes

Getting started building with Begin is remarkably fast and simple.

Once you're finished with this guide, you'll be ready to build and scale just about any kind of web application, API, or site with speed, ease, and grace.

First, let's review what you need to get going.

Prerequisites

While this guide assumes general familiarity with such things as text editors, terminal interfaces, git, and basic software development in JS with Node.js, you do not need to be a CTO to use Begin (or this guide)!

tl;dr, you'll need:

A (free) GitHub account
Any computer running macOS, Windows, or Linux, with:
- Node.js 12
- npm 6.x

Platforms: macOS, Windows, and Linux

Begin supports local, offline development on just about all modern computers, including: macOS, Windows (10+), and Linux.

Runtimes: Node.js 12

Begin provisions and manages AWS infrastructure that runs solely on Node.js 12 (with support additional runtimes coming soon).

You can work locally with versions of Node other than 12, but your app shouldn't depend on any features, functionality, or fixes that are not available in Node 12.

You can grab Node.js here.

Package management: NPM 6.x

Begin requires npm 6.x for local development. Recent releases of Node bundle npm 5.x, so you'll want to make sure to upgrade with: npm install npm@latest -g

Version control: GitHub

Begin hosts project repos on GitHub; if you don't have one already, sign up for a free GitHub account here.

When you create a new app, Begin will provision your GitHub repo pre-wired with the integrations it needs, such as webhooks to Begin's CI.

Begin only requests the least-privileged set of permissions required to work with GitHub, and does not attempt to access any other repositories or personal data.

Create a Begin account

To create a Begin account, simply click the Login button on the Begin home page, authorize it with GitHub, and pick a username. That's it!

Creating an app

After creating your Begin account, select an app from the list of starter apps to build from. (We think the Personal website is a great place to start, but this guide applies to all Begin apps.)

Then name your app and repo, and Begin will spin up your new project repository under github.com/{your GH username}/{your repo name}, and populate it with a fully functional Begin app.

By default your Begin app repo is created as a public GitHub repo; it can be set to private by granting Begin additional permissions via in the Settings screen found in the left nav of your Begin app.

Your first deploy

Immediately after Begin is finished setting up your project repo, it will kick off its first deploy to your app's staging environment.

By default, each commit to master initiates a build; if the build is green, that build is immediately deployed to your app's staging environment. No fuss, no muss!

Every new build to staging and master appears in your Activity feed.

Learn more about building & deploying with Begin.

Accessing your live app

Once deployed, your app will be immediately live and available on the internets. Nice! 🎉

To access your staging environment, click Staging link in the build status module in the top of the left navbar.

Project structure

Now that your app is live in staging, a brief word about how Begin apps are structured so you'll know your way around.

Begin applications are comprised of many small, fast, individually executing cloud functions (or Functions, for short). Let's take a quick look at the source tree of a basic Begin app:

.
├── public/
├── src/
│   ├── http/
│   │   └── get-index/
│   ├── shared/
│   └── views/
└── test/

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

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

So if you want to make a change to your app's root view, you'll want to modify its src/http/get-index/index.js file.

Learn more about Begin app project structure.

Working locally

Get started working locally on your app in five easy steps. Assuming you used the default name of Begin app, open your terminal app, and:

Clone your app's repo to your local machine:

git clone https://github.com/{your GH username}/begin-app.git

cd to your Begin project directory:

cd begin-app

Install npm packages:

npm install

Start the app locally:

npm start

Learn more about getting set up in our Introduction.

That's it!

In just a few minutes, you now have a fresh app with dedicated staging and production environments, a fast local, offline dev environment, pre-wired CI/CD, and everything you need to rapidly iterate.

Happy building!

Ship to `production`

Lint and run tests, of course:

npm run lint && npm t

Release to production by:
- Using the Deploy to Production button in the left nav in Begin, or
- Creating a git tag, i.e.:

git tag -a 1.0.1 -m "This release includes 20% more cowbell"
git push origin 1.0.1

Or also by cutting a GitHub Release

👓 Note: We strongly encourage the use of SemVer when creating production releases!

Keep learning

There are many fun things to learn about building Begin apps, check out the rest of our docs here!

Configure AWS Lambda source paths with OpenJS Architect

SHAWNHOSEA — Tue, 16 Mar 2021 09:04:49 +0000

Architect originally relied on convention over configuration — meaning you could expect the placement of Lambda function handlers, to appear in default and deterministic locations. Recently, we introduced configurable file paths, which allow you to have more granular configurability over your Architect and Begin projects source code. This might be important for you because you have an existing project structure and conventions or you may need to point your Lambdas at generated build artifacts from something like TypeScript.

Configure source for get / in package.json

Define the application Infra as Code (IaC) in package.json under the arc key.

{
  "arc": {
    "app": "begin-app",
    "http": {
      "/": {
        "method": "get",
        "src": "path/to/code"
      }
    }
  }
}

Configure source for a larger app in package.json

Define IaC for a GraphQL app.

{
  "arc": {
    "http": {
      "/": { "method": "get", "src": "path/to/code"},
      "/api": { "method": "post", "src": "path/to/apollo"}
    }
  }
}

This enables you to configure separate source paths for your code for each Lambda function. It is a good idea to separate your code into single responsibility functions. Less code per function means faster cold-starts and deployments. This also makes sharing code and using transpilers a breeze!

Let's make a new Begin app!

SHAWNHOSEA — Wed, 10 Mar 2021 08:52:11 +0000

Introduction

There are various ways to spin up a new app on Begin. You have the option to:

Choose between Node or Deno for your runtime
Start with a framework-specific starter app
Use one of our example apps
Port one of your apps over to Begin by using an existing repo
Clone an existing repo from someone else

Choose a runtime:

You have the option to choose between Node or Deno for your runtime. With Node, you can use one of the framework-specific starter apps or a Begin example app. Deno only has the Begin example apps available. Both runtimes allow you to port an outside repository to get started.

Framework-specific starter apps

We have four different framework-specific starter apps to choose from. Each of these starter apps comes with an accompanying guide to help get you going.

You can view them all here.

Example apps

Six different example apps cover a particular feature or use-case that's possible with Begin. For example:

These example apps come with accompanying guides as well to help get you started.

You can view them all here.

Use your own

Use an existing repo

You have the option to port one of your apps over to Begin by using an existing repo. Use an existing repo will add the minimum necessary files to use Begin with an existing GitHub repo.

Clone an app

Cloning an app will allow you to clone an existing Begin or Architect app into a fresh GitHub repo.