How Nitric works

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 during deployment

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 (services). This allows Nitric to find and build the code that serves your APIs, subscribers 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.1.0
region: us-east-1

Extending Nitric

In Nitric, you've got choices! You can extend our standard providers or create your own custom ones. Whether you're tweaking what's already there or inventing something new, Nitric's here to support you. Check out these guides to learn more:

If you have any questions, feel free to reach out on our Discord.