Noop Inc. noop_

Guide

December 15, 2023

Launch a Nodejs and Vue Monorepo

Joe Kendall Joe Kendall

Develop and launch a Nodejs API with a Vue frontend app. The backend uses Amazon DynamoDB for record storage and Amazon S3 for image upload storage. The whole process from creating the project to launching on the internet takes only a few minutes.

Overview

This guide produces a complete application ecosystem organized in a monorepo. The application includes an API backend (Nodejs), web frontend (Vue), record storage (Amazon DynamoDB) and image upload storage (Amazon S3). Using Noop, everything included in the application ecosystem is run together, locally or in the cloud.

To start a new application based on the Nodejs + Vue Template, install Workshop and select the Nodejs + Vue Template. The create-Template process in Workshop will automate everything outlined in this guide.

If, on the other hand, you want to modify an existing project to use Noop, the guide here can be used as reference.

The full source code constructed for this guide, including the Noop configuration, see the Template repository.

Setup

Noop Dependencies

Make sure you have Workshop installed locally, or a Github account connected to Noop Cloud. The remaining setup is identical in both.

Project Setup

The project repo contains one Component for the frontend app and one for the backend. Each Component has its own directory. They are in the project root, website-static and api-service respectively.

Each Component has its own setup. This guide won’t cover the Application-specific code, however feel free to use and modify it as you see fit.

Frontend

The frontend code creates a UI to interact with the API’s CRUD interface.

If you plan to create your own frontend, the Vue documentation provides great instructions.

Backend

The backend code creates a REST interface and manages the CRUD interface to the database and file storage.

Our API service uses Express.js version 5, see the version 5 docs for guides on how to create your own API service.

Blueprint Configuration

After your application project structure is set up, we need to configure Noop to run everything together.

Create a .noop directory in your project root.

mkdir .noop

Next create a blueprint.yaml file to define the application setup.

The content below is the necessary config for our app:

---
components:
  - name: TodoApi
    type: service
    image: node:18-alpine
    root: api-service
    port: 3000
    build:
      steps:
        - directory: /api-service
        - copy: package*.json
          destination: ./
        - run: npm ci
        - copy: index.js
        - copy: dynamodb.js
        - copy: s3.js
    runtime:
      command: npm start
      resources:
        - TodoItems
        - TodoUploads
      variables:
        AWS_REGION:
          $env: region
        DYNAMODB_TABLE:
          $resources: TodoItems.tableName
        DYNAMODB_ENDPOINT:
          $resources: TodoItems.endpoint
        S3_BUCKET:
          $resources: TodoUploads.bucket
        S3_ENDPOINT:
          $resources: TodoUploads.endpoint

  - name: TodoWebsite
    type: static
    image: node:18-alpine
    root: website-static
    hosting:
      spa: true
    build:
      steps:
        - directory: /website-static
        - copy: package*.json
          destination: ./
        - run: npm ci
        - copy: index.html
        - copy: vite.config.js
        - copy: public/
        - copy: src/
        - run: npm run build
        - directory: dist/

routes:
  - pattern: /api/**
    target:
      component: TodoApi

  - target:
      component: TodoWebsite

resources:
  - name: TodoItems
    type: dynamodb
    hashKeyName: id
    hashKeyType: S
  - name: TodoUploads
    type: s3

Let’s break that down. At the top level there are components, routes and resources. These are the major building blocks of the Application.

Components define the software our Application runs. In this case, the components property defines two application Components, TodoWebsite (the frontend) and TodoApi (the backend). Each component defines its type, runtime details and the build process including the image used as the basis for the build.

Routes define how web Traffic gets to the application components. In this case there are two routes, /api/** which sends traffic to the TodoApi Component, and a catchall (no path pattern specified), which routes all other traffic to the TodoWebsite component.

Resources define the stateful parts of your app. In this case our API service relies on Amazon DynamoDB and Amazon S3.

For a better understanding of the Application configuration, see our complete overview of blueprint.yaml.

Connecting To a Resource

In order for a Component to access a Resource, the Resource must be listed under the Component runtime property.

...
    runtime:
      command: npm start
      resources:
        - TodoItems
        - TodoUploads
        ...

The database connection parameters are defined on the Service Component component.[n].runtime.variables property using a special lookup property $resources: <RESOURCE_NAME>.<RESOURCE_PARAM>.

A complete list of all Resource parameters can be found on the Resource overview page.

Static Configuration

Static Components have a few details worth mentioning. First, if you intend to allow the frontend code handle routing, it’s important to set the hosting config to spa: true. This tells Noop router to send any route to the index document in the root of the uploaded static site. The index document name can be changed, see the Statics docs for full details.

...
    hosting:
      spa: true
...

Automating Cloud Setup

For Cloud users, most of the Application setup can be automated. Including Environment creation, database provisioning, building and deploying, etc., using a Runbook. To create a Runbook, make a file called quickstart.yaml in the .noop/runbooks directory.

Here is the Runbook content for the Nodejs + Vue app:

name: Quickstart Setup

description: Demo full stack setup of this app with internet endpoint

workflow:
  inputs:
    - name: EnvironmentName
      description: What should we name your new environment?
      type: string
      required: true
      default: Quickstart Demo

    - name: Cluster
      type: Cluster
      description: Which cluster should the environment launch on?
      required: true

  timeout: 300

  steps:
    - name: Environment
      action: EnvironmentCreate
      params:
        name:
          $inputs: EnvironmentName
        production: false
        appId:
          $runbook: Application.id
        clusterId:
          $inputs: Cluster.id

    - name: Build
      action: BuildExecute
      params:
        sourceCodeId:
          $runbook: SourceCode.id
        appId:
          $runbook: Application.id

    - name: Resources
      action: ResourceLaunch
      params:
        envId:
          $steps: Environment.id
        sourceCodeId:
          $runbook: SourceCode.id

    - name: Deploy
      action: DeploymentExecute
      params:
        envId:
          $steps: Environment.id
        buildId:
          $steps: Build.id

    - name: Endpoint
      action: InternetEndpointRandom
      params:
        orgId:
          $runbook: Organization.id
        routes:
          - name: 'Demo Environment'
            target:
              environments:
                - $steps: Environment.id

Launch on Noop

Cloud users can use the Runbook to automate most of the setup described below.

Create an Application

Select “New Application” and assign an appropriate name for your new app.

Cloud Setup

In Cloud, once the Application is created you will be asked if you want to execute a Runbook. The name of the Runbook for this Template is “Quick Start”.

Choose the default Cluster and run it. Behind the scenes this Runbook is:

  • Creating an Environment
  • Launching the database
  • Building the source code
  • Deploying the build
  • And finally, creating a public-facing endpoint to serve the application from

Once complete, visit the Application page to get the generated endpoint. Your new Nodejs and Vue monorepo app is now running at that URL.

The Noop Template Blueprint contains all the details about the application. Including build process, required resources, application routing rules, runtime configuration, etc.

Workshop Setup

While workshop doesn’t have a Runbook, the setup is also automated.

In Workshop select your Application, which should have been automatically detected by Workshop, or select the appropriate project directory (must include a .noop directory).

Workshop will automatically create a default environment with all Resources launched.

Once done, you should see your application running on the associated endpoint.

Testing It Out

Once your Application is deployed (locally in Workshop or in Cloud), visit the associated endpoint to interact with the example todo list app.

Once you have added a todo item, visit the launched Environment in the Noop Console and navigate to the Resource used by the API service.

On the Resource page you can interact directly with the database and block storage using the Resource Explorers. Once you scan the database, you should see the todo item that was just created.