Concepts

Nitric is a multi-language framework for rapidly building cloud applications that run on many different cloud providers such as AWS, Google Cloud or Microsoft Azure, with reduced boilerplate and infrastructure automation. This is often called Infrastructure-from-Code (IfC), since the core of your application becomes the source of truth for both the application logic and deployment architecture.

Nitric achieves this by adding lightweight resource declarations to your application, as close as possible to where they're used. This also removes the often brittle relationship between IfC projects that deploy resources and the application code that depends on them.

Here's an example of using Nitric to create a secure bucket for file storage and granting read access to that bucket.

import { api, bucket } from '@nitric/sdk'

const profiles = bucket('profiles').for('reading')
const myApi = api('main')

myApi.get('/profiles/:name', async (ctx) => {
  const image = await profiles.file('users/bruce-wayne.png').read()
})

You'll notice in the example that there aren't any cloud-specific references, such as a call to AWS S3 or Google Cloud Storage. All of the deployment automation, identity/access management and runtime access are handled by Nitric through provider plugins, which you choose at deployment. This ensures applications built with Nitric maintain portability and allows you to focus on your product first and a cloud provider second. Apps built with Nitric can even be deployed to multiple cloud providers at once to improve reliability or to maximize availability of free-tier resources.

Components of the Nitric Framework

Nothing about Nitric is magic, it's just composed from a few components that work together to help you build cloud apps. The main components of Nitric are the CLI, language SDKs, then a runtime server and deployment engine for each provider.

How your application is deployed, configured, secured and interacts with cloud resources is all determined by the provider you choose during deployment. Providers are deployment and runtime plugins that target a cloud (or other host) and the specific services of that host chosen to fulfill each of the resources Nitric provides, such as a container runtime, buckets, key/value stores, API gateways, queues, etc.

Nitric has provider implementations for AWS, Google Cloud and Azure. You're also able to build your own with the infrastructure-as-code tools and cloud providers of your choice. There is also a local provider which can run your code on your own machine during development.

How it works

Using the nitric up command in the Nitric CLI will initiate a deployment. This command will build your code into containers, then run those containers and connect them to the Nitric CLI's deployment API. That API gathers the requirements of your project (resources, security and other configuration) and communicates them to your chosen provider. The provider takes care of translating those requirements into cloud-specific infrastructure and performing the deployment.

diagram

The containers that are built during deployment include a copy of the runtime implementation for the provider. The runtime server is a lightweight adapter that translates requests from the Nitric SDK to the cloud-specific APIs in your provider. It also listens for events/requests from the cloud provider, such as HTTP requests or messages on a topic, and forwards them to your application code in a common format.

diagram

Project structure

Application's built with Nitric don't have a strict project structure. However, we do provide templates for each supported language, which can be a good place to start when learning how to build with Nitric. There are only two types of files required by Nitric projects:

  • Project file, e.g. nitric.yaml
  • Stack files, e.g. nitric.develop.yaml

Project files

The existence of this file, typically nitric.yaml, indicates that the directory contains a project built with Nitric. The file defines the project's name and how to locate code entrypoint (handlers). This allows Nitric to find and build the code that serves your APIs, events and schedules.

A typical nitric.yaml file looks like this:

nitric.yaml
name: my-project
services:
  - match: ./services/*.ts
    start: yarn dev:services $SERVICE_PATH

Stack files

Nitric projects can be deployed to multiple environments and cloud providers, stack files identify these deployment targets. These files can be created by running the nitric stack new command and allow you to name the stack, as well as configure the provider to use when deploying. They also contain other stack specific configuration, such as the region to deploy to or CPU and memory customization for container instances.

The naming convention for stack files is nitric.[stack ID].yaml. Here is an example of a basic stack file created by the Nitric CLI:

nitric.aws.yaml
provider: nitric/aws@1.0.0
region: us-east-1