Skip to content
This repository was archived by the owner on May 20, 2025. It is now read-only.

Commit 95c5c10

Browse files
jyecuschjyecusch
committed
update 'why nitric' with a practical example
1 parent 905a6d0 commit 95c5c10

File tree

1 file changed

+252
-25
lines changed

1 file changed

+252
-25
lines changed

‎docs/get-started/foundations/why-nitric.mdx‎

Lines changed: 252 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -4,49 +4,276 @@ description: 'The problems with modern cloud development'
44

55
# Why Nitric
66

7-
Building and deploying cloud applications should be simple. But in practice, cloud development comes with numerous challenges, from managing provider-specific services to wrestling with deployment automation. Nitric was designed to address these pain points and provide a modern, highly declarative, and flexible approach to building cloud apps that work across providers.
7+
### Infrastructure as Code: A System Out Approach
88

9-
## The Problems
9+
Infrastructure as Code (IaC) tools like Terraform, AWS CloudFormation, and Pulumi have reshaped how cloud infrastructure is managed. They allow teams to define resources and configurations in code, leading to reproducibility, automation, and more consistent environments.
1010

11-
### Provider Lock-in and Highly Coupled Architectures
11+
However, these tools typically approach the problem from the point-of-view of the system: "What can the cloud platform do? What configuration options are available on this resource?". They expose these capabilities through configuration files, making infrastructure management more systematic but also tied to cloud/service/platform specific details.
1212

13-
Many applications are built with deep dependencies on a single cloud provider's services (think the AWS S3 client library or the specific shape of a Google Pub/Sub message, or any number of other subtle and not-so-subtle dependencies on cloud services).
13+
### Nitric: A Developer In Approach
1414

15-
These dependencies makes it difficult to port your app to another service, or move to a different cloud get the best price, or run your app locally for testing, or even work in hybrid cloud environments. As the app grows, so does the reliance on specific cloud services, leading to vendor lock-in, making it harder to scale and evolve over time.
15+
Nitric builds on this with a focus on what you want to achieve as the developer: "What workflow do you need to be productive? What system design are you trying to achieve?". From there, it's capable of mapping your application's needs down to the Infrastructure-as-Code required to achieve those goals.
1616

17-
Nitric abstracts these details, giving you the flexibility to deploy across different cloud providers without having to rewrite your application code. By decoupling your logic from the underlying infrastructure, Nitric ensures your app works wherever you need it to.
17+
This approach keeps application code clean and focused on functionality, leaving the management and interaction with infrastructure to a new layer that supports the applications you develop.
1818

19-
### Deployment Automation: A Second Application
19+
In a typical cloud application **you already make declarations of your system's requirements**.
2020

21-
Building a cloud app you can easily find yourself building a second application—deployment automation—that manages the infrastructure and services your app depends on. This includes provisioning cloud resources, managing permissions, configuring networking, and more. The deployment scripts become an integral part of your project, with a complex set of instructions that must be maintained alongside your app.
21+
Consider the following code:
2222

23-
While this is a necessary part of cloud development, it can be a significant burden - one that can be simplified and made more robust.
23+
<CodeSwitcher tabs>
2424

25-
Nitric simplifies this by automatically collecting what your app needs to run and providing this to plugins that can generate the deployment automation for you. You no longer need to manually craft unique and complex Infrastructure-as-Code (IaC) files to describe each app's requirements. Instead, use independently testable and reusable deployment automation layers.
25+
```javascript !!
26+
import { GetObjectCommand, S3Client } from '@aws-sdk/client-s3'
2627

27-
### Hidden Details in the Code
28+
const s3 = new S3Client({})
29+
const RECEIPT_DOCUMENTS_BUCKET = process.env.RECEIPT_DOCUMENTS_BUCKET
2830

29-
Many of the details about how an application interacts with its infrastructure are buried in the code. For example, the permissions required to access services, the environment variables needed to function, or the correct configuration of cloud resources are often implied by the codebase, but not explicitly defined. Keeping track of these is challenging, and small mistakes can lead to broken deployments or runtime failures.
31+
if (!RECEIPT_DOCUMENTS_BUCKET) {
32+
throw new Error('RECEIPT_DOCUMENTS_BUCKET environment variable not set')
33+
}
3034

31-
Nitric brings these details to the surface, ensuring that the infrastructure requirements are automatically generated based on how your app is written. This eliminates the need to manually interrogate the code (or more likely its author) to specify the needed permissions, environment variables, and cloud resource dependencies.
35+
export async function getReceiptDoc(filename) {
36+
const command = new GetObjectCommand({
37+
Bucket: RECEIPT_DOCUMENTS_BUCKET,
38+
Key: filename,
39+
})
3240

33-
### Automation Sync & Zombies
41+
const response = await s3.send(command)
42+
return await response.Body.transformToByteArray()
43+
}
44+
```
3445

35-
Keeping your app code in sync with the deployment automation is a constant battle. When you make changes to your app—such as removing a resource—the deployment automation must be manually updated to prevent zombie resources. Conversely, if your deployment script creates a resource and passes its ARN as an environment variable, any typo in that variable can cause your app to fail at runtime. These issues are hard to catch because there's no strong link between the app and the IaC code.
46+
```typescript !!
47+
import { GetObjectCommand, S3Client } from '@aws-sdk/client-s3'
3648

37-
With Nitric, your app and deployment automation are always in sync. The resources your app uses are automatically aggregated, and environment variables are no longer needed, with resource ID resolution built directly into your app at runtime. No more hunting for missing or misconfigured settings. Everything your app needs is declared in one place—your application code.
49+
const s3 = new S3Client({})
50+
const RECEIPT_DOCUMENTS_BUCKET = process.env.RECEIPT_DOCUMENTS_BUCKET
3851

39-
## Nitric's Solution
52+
if (!RECEIPT_DOCUMENTS_BUCKET) {
53+
throw new Error('RECEIPT_DOCUMENTS_BUCKET environment variable not set')
54+
}
4055

41-
Nitric addresses these challenges by taking a fundamentally different approach:
56+
export async function getReceiptDoc(filename: string): Promise<Uint8Array> {
57+
const command = new GetObjectCommand({
58+
Bucket: RECEIPT_DOCUMENTS_BUCKET,
59+
Key: filename,
60+
})
4261

43-
- **Decoupling App Logic from Infrastructure**: Nitric handles the cloud infrastructure for you, so your app can focus on what matters—delivering functionality. No more writing and maintaining complex deployment scripts specific to just one app.
44-
- **Automatic Infrastructure Management**: Nitric automatically provisions the resources your app needs based on its code. There's no need to manually declare and update cloud resources. Or worse, forget to update them.
45-
- **Built-in Permissions and Configuration**: Nitric configures permissions and resource resolution for you, so your app is ready to run securely and with the correct settings.
46-
- **Cross-Cloud Flexibility**: Whether you want to deploy to AWS, Azure, GCP, all three, or somewhere else entirely, Nitric ensures your app works consistently across cloud providers.
62+
const response = await s3.send(command)
63+
return await response.Body.transformToByteArray()
64+
}
65+
```
4766

48-
Nitric makes cloud development a frictionless experience. By eliminating the tedious and error-prone aspects of deployment, you can focus on building great applications, confident that they will deploy reliably.
67+
```python !!
68+
import os
69+
import boto3
4970

50-
## The Limits
71+
RECEIPT_DOCUMENTS_BUCKET = os.getenv('RECEIPT_DOCUMENTS_BUCKET')
5172

52-
Nitric is not a silver bullet. It can't solve every problem in cloud development, nor is it a one-size-fits-all solution. However, it does provide a powerful set of tools and practices that can significantly simplify and streamline your cloud development workflow.
73+
if not RECEIPT_DOCUMENTS_BUCKET:
74+
raise EnvironmentError('RECEIPT_DOCUMENTS_BUCKET environment variable not set')
75+
76+
s3_client = boto3.client('s3')
77+
78+
def get_receipt_doc(filename):
79+
response = s3_client.get_object(Bucket=RECEIPT_DOCUMENTS_BUCKET, Key=filename)
80+
return response['Body'].read()
81+
82+
```
83+
84+
```go !!
85+
package main
86+
87+
import (
88+
"context"
89+
"os"
90+
"github.com/aws/aws-sdk-go-v2/aws"
91+
"github.com/aws/aws-sdk-go-v2/config"
92+
"github.com/aws/aws-sdk-go-v2/service/s3"
93+
"io"
94+
)
95+
96+
var receiptDocumentsBucket = os.Getenv("RECEIPT_DOCUMENTS_BUCKET")
97+
98+
func init() {
99+
if receiptDocumentsBucket == "" {
100+
panic("RECEIPT_DOCUMENTS_BUCKET environment variable not set")
101+
}
102+
}
103+
104+
func getReceiptDoc(filename string) ([]byte, error) {
105+
cfg, _ := config.LoadDefaultConfig(context.TODO())
106+
s3Client := s3.NewFromConfig(cfg)
107+
108+
resp, _ := s3Client.GetObject(context.TODO(), &s3.GetObjectInput{
109+
Bucket: aws.String(receiptDocumentsBucket),
110+
Key: aws.String(filename),
111+
})
112+
113+
defer resp.Body.Close()
114+
return io.ReadAll(resp.Body)
115+
}
116+
```
117+
118+
```dart !!
119+
import 'dart:io';
120+
import 'package:aws_s3_api/s3-2006-03-01.dart';
121+
122+
final receiptDocumentsBucket = Platform.environment['RECEIPT_DOCUMENTS_BUCKET'];
123+
124+
void checkBucketEnv() {
125+
if (receiptDocumentsBucket == null || receiptDocumentsBucket!.isEmpty) {
126+
throw Exception('RECEIPT_DOCUMENTS_BUCKET environment variable not set');
127+
}
128+
}
129+
130+
Future<List<int>> getReceiptDoc(String filename) async {
131+
checkBucketEnv();
132+
final client = S3(region: 'us-west-2'); // Adjust region
133+
final request = GetObjectRequest(
134+
bucket: receiptDocumentsBucket!,
135+
key: filename,
136+
);
137+
138+
final response = await client.getObject(request);
139+
return await response.body.toBytes();
140+
}
141+
```
142+
143+
</CodeSwitcher>
144+
145+
Code like this makes very clear demands of the environment it expects to run in:
146+
147+
- I need a bucket to be available
148+
- I need to be able to read objects from that bucket
149+
- The bucket must be an AWS S3 bucket
150+
- I need to know the ARN/Name of the bucket
151+
152+
The problem is that these requirements are implicit. They're hidden throughout the code and for non-trivial apps it's challenging to collect them all and be sure the requirements are met.
153+
154+
In a IaC approach, you would write something like Terraform or CloudFormation by hand to declare these requirements, setup the necessary permissions, and set the appropriate values in the environment variables of the container/function/etc. running the code.
155+
156+
This manual process requires a detailed knowledge of the cloud platform's capabilities and how to safely configure them, while simultaneously understanding the numerous requirements of the application code. Unfortunately, this process is error-prone and leads to inconsistency, misconfigurations, time-consuming debugging, and in the worst cases—security vulnerabilities.
157+
158+
Nitric's primary goal is to flip this around. Making implicit requirements explicit and automating the process of collecting these requirements into a specification that can be used to automatically generate the appropriate IaC.
159+
160+
Additionally, Nitric wants to make application code concise, portable and cloud-agnostic, so that you can run your application on any cloud provider, replace underlying services at will, or run on alternate infrastructure like Kubernetes, on-premises or your own laptop.
161+
162+
Here's how the above code looks with Nitric:
163+
164+
<CodeSwitcher tabs>
165+
166+
```javascript !!
167+
import { bucket } from '@nitric/sdk'
168+
169+
const receiptDocs = bucket('receipt-docs').allow('read')
170+
171+
export async function getReceiptDoc(filename) {
172+
return await receiptDocs.file(filename).read()
173+
}
174+
```
175+
176+
```typescript !!
177+
import { bucket } from '@nitric/sdk'
178+
179+
const receiptDocs = bucket('receipt-docs').allow('read')
180+
181+
export async function getReceiptDoc(filename: string): Promise<Uint8Array> {
182+
return await receiptDocs.file(filename).read()
183+
}
184+
```
185+
186+
```python !!
187+
from nitric.resources import bucket
188+
189+
receipts_docs = bucket("receipts").allow("read")
190+
191+
async def get_receipt_doc(filename):
192+
return await receipts_docs.file(filename).read()
193+
194+
```
195+
196+
```go !!
197+
import (
198+
"context"
199+
200+
"github.com/nitrictech/go-sdk/nitric"
201+
"github.com/nitrictech/go-sdk/nitric/storage"
202+
)
203+
204+
var receiptDocs storage.BucketClient
205+
206+
func init() {
207+
receiptDocs = *nitric.NewBucket("receipt-docs").Allow(storage.BucketRead)
208+
}
209+
210+
func getReceiptDoc(ctx context.Context, filename string) ([]byte, error) {
211+
return receiptDocs.Read(ctx, filename)
212+
}
213+
```
214+
215+
```dart !!
216+
import 'package:nitric_sdk/nitric.dart';
217+
218+
final receiptDocs = Nitric.bucket("receipt-docs").allow([
219+
BucketPermission.read,
220+
]);
221+
222+
Future<List<int>> getReceiptDoc(String filename) async {
223+
return await receiptDocs.file(filename).read();
224+
}
225+
```
226+
227+
</CodeSwitcher>
228+
229+
There are a few key differences here:
230+
231+
- The requirements are explicit. The code declares that it needs a bucket named `receipt-docs` and that it needs to be able to read from it.
232+
- The code is concise and focused on the application logic. The infrastructure requirements are declared in a separate layer, making the application code cleaner and more maintainable.
233+
- The code is cloud-agnostic. Nitric can map the requirements to the appropriate cloud services, allowing the application to run on any cloud provider or infrastructure.
234+
- There are no environment variables, so typos or missing values are less likely to cause runtime errors.
235+
- You don't need to read the code to find these requirements. Nitric can gather them all into a specification that can be used to automatically generate the necessary IaC.
236+
237+
### Why Nitric?
238+
239+
#### 1. **Developer-Centric Workflow**
240+
241+
Amazing tools already exist for specifying _how_ to deploy infrastructure, Nitric focuses on _what_ infrastructure is needed. Nitric lets you design your application architecture, independent of the deployment automation tool or target platform. With highly declarative in-app infrastructure requirements.
242+
243+
Instead of writing project-specific Terraform, Pulumi or CloudFormation scripts, Nitric centralizes this code and automatically generates the project-specific scripts based on your application's declarations. As we said earlier, your code already defines what the system needs—Nitric just makes that explicit and automates the rest.
244+
245+
#### 2. **Making Implicit Requirements Explicit**
246+
247+
In a typical application, your code defines its infrastructure needs implicitly—like when you access an S3 bucket or connect to a queue. Nitric makes requirements explicit declarations, ensuring the required cloud resources are provisioned, permissions are configured, and the app is connected to them in a consistent and reliable way.
248+
249+
Instead of tracking these dependencies manually, Nitric automates this process. If your app needs storage, a database, or a message queue, Nitric ensures these resources are properly set up and integrated into your app, removing the friction of manual configuration.
250+
251+
#### 3. **Cloud-Agnostic and Portable**
252+
253+
Nitric decouples your application from the underlying cloud infrastructure. Whether you're using AWS, Azure, GCP, or Kubernetes, Nitric allows you to map your application's requirements to the appropriate services across platforms. This allows your app to run anywhere without the need for platform-specific code to be embedded in the application.
254+
255+
This portability is key to future-proofing applications and avoiding lock-in to any one cloud provider or service. Nitric ensures that your app's architecture remains flexible and adaptable, so switching providers or moving between environments (cloud, on-premises, local) becomes seamless.
256+
257+
#### 4. **Automated Infrastructure, Best Practices Included**
258+
259+
One of the most error-prone aspects of cloud development is managing permissions, configurations, and security policies. Nitric automates this, making security best practices—like least privilege access and proper service configurations easy.
260+
261+
This reduces the risk of misconfigurations, inconsistency, security holes, and the burden of having to write boilerplate IaC scripts to handle service permissions. Nitric offloads this work to consistent plugins for each target platform, ensuring your infrastructure is provisioned correctly without adding overhead to your development process.
262+
263+
#### 5. **Focus on Application Logic**
264+
265+
Nitric's approach allows you to focus on building your application, instead of the scaffolding required to run it in the cloud. By removing the manual steps from the IaC process, Nitric eliminates significant boilerplate and reduces the runtime checking needed to handle configuration errors.
266+
267+
This isn't about skipping important cloud knowledge—you still benefit from understanding how your app interacts with the cloud. But by making infrastructure explicit and automating it, Nitric reduces the time spent configuring, debugging, and maintaining cloud services. This gives you more bandwidth to focus on what really matters: your app's features and functionality.
268+
269+
#### 6. **Plugin-Based Architecture**
270+
271+
Nitric's plugin-based architecture allows you to use the deployment plugins we provide, which use Pulumi or Terraform for deployment, or write your own. This flexibility allows you to use the tools you're comfortable with, while still benefiting from Nitric's infrastructure automation and cloud-agnostic approach.
272+
273+
It can also act as a protocol for communication between app development and infrastructure teams, ensuring that the infrastructure requirements are clear and consistent. This ensures the two teams can work independently, with the infrastructure team focusing on the best way to provision the resources, and the development team focusing on building the application.
274+
275+
### Conclusion
276+
277+
Nitric simplifies the way you build your app—enhancing it with automatic gathering of infrastructure requirements, and decoupling the tools used to deploy that infrastructure. Your code already defines what resources are needed, Nitric just makes that clear, flexible, and portable.
278+
279+
Nitric is designed to make cloud development more efficient, secure, and focused on what you're building—not how you're building it. It's a developer-centric layer added to cloud infrastructure automation and streamlines the development process, reduces complexity, and lets you build better applications faster.

0 commit comments

Comments
 (0)