aws-blocks

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

AWS Blocks Application Development

AWS Blocks 应用开发

Package naming: All packages are published under the
@aws-blocks
scope (e.g.,
@aws-blocks/core
,
@aws-blocks/blocks
,
@aws-blocks/bb-kv-store
).

包命名规则： 所有包均发布在
@aws-blocks
作用域下（例如
@aws-blocks/core
、
@aws-blocks/blocks
、
@aws-blocks/bb-kv-store
）。

Overview

概述

AWS Blocks is an Infrastructure-from-Code framework where Building Blocks bundle CDK, SDK, and local mocks into a single API. It provides 18+ Building Blocks covering storage, authentication, real-time communication, background jobs, file management, AI/search, email, and observability — all working locally without AWS credentials.

Key characteristics:

One
```
aws-blocks/
```
directory defines the entire backend
Frontend imports are fully typed — no client generation needed
All Building Blocks work locally without AWS (mocks persist to
```
.bb-data/
```
)
Deploy ephemeral, individual testing environments with
```
npm run sandbox
```
and long-lived environments with
```
npm run deploy
```
using least-privilege credentials

AWS Blocks是一种基础设施即代码（Infrastructure-from-Code）框架，其中构建模块将CDK、SDK和本地模拟工具整合为单一API。它提供了18余种构建模块，涵盖存储、身份验证、实时通信、后台任务、文件管理、AI/搜索、邮件和可观测性等功能——所有模块无需AWS凭证即可在本地运行。

核心特性：

单个
```
aws-blocks/
```
目录定义整个后端
前端导入具备完整类型支持——无需生成客户端代码
所有构建模块无需AWS即可在本地运行（模拟数据持久化到
```
.bb-data/
```
目录）
使用最小权限凭证，通过
```
npm run sandbox
```
部署临时独立测试环境，通过
```
npm run deploy
```
部署长期运行环境

Scaffolding a New Project

搭建新项目

bash

npx @aws-blocks/create-blocks-app my-app
cd my-app

bash

npx @aws-blocks/create-blocks-app my-app
cd my-app

To add AWS Blocks to an existing project:

向现有项目添加AWS Blocks：

bash

npx @aws-blocks/create-blocks-app .

This detects the existing project and adds an

aws-blocks/

workspace alongside your code.

bash

npx @aws-blocks/create-blocks-app .

该命令会检测现有项目，并在代码旁添加

aws-blocks/

工作区。

To add AWS Blocks to an Amplify Gen 2 project:

向Amplify Gen 2项目添加AWS Blocks：

bash

npx @aws-blocks/create-blocks-app .

When the CLI detects

amplify/backend.ts

, it automatically integrates AWS Blocks with your Amplify backend.

bash

npx @aws-blocks/create-blocks-app .

当CLI检测到

amplify/backend.ts

时，会自动将AWS Blocks与你的Amplify后端集成。

With a specific template:

使用特定模板：

bash

npx @aws-blocks/create-blocks-app my-app --template demo
cd my-app

bash

npx @aws-blocks/create-blocks-app my-app --template demo
cd my-app

Available Templates

可用模板

Template	Description
`default`	Vite + lit-html starter app with basic authentication, data persistence, and realtime to help demonstrate basic app architecture and patterns (used when --template is omitted)
`bare`	Vite + lit-html starter with a single "hello world" API method and a bare frontend
`react`	React + Vite starter with a single API endpoint and typed React frontend
`backend`	Backend-only — no frontend, just the AWS Blocks API with a single endpoint
`demo`	Todo app with AuthBasic, KVStore, DistributedTable, Zod schemas, indexes, and auth-protected CRUD
`auth-cognito`	Full AuthCognito passwordless email-OTP with roles, device management, and Authenticator UI
`nextjs`	Next.js + React starter with AWS Blocks backend integration (SSR + Server Components)

模板	描述
`default`	Vite + lit-html入门应用，包含基础身份验证、数据持久化和实时功能，用于演示基础应用架构和模式（省略--template参数时使用）
`bare`	Vite + lit-html入门应用，仅包含一个“hello world”API方法和极简前端
`react`	React + Vite入门应用，包含一个API端点和类型化React前端
`backend`	仅后端——无前端，仅包含带有单个端点的AWS Blocks API
`demo`	待办事项应用，集成AuthBasic、KVStore、DistributedTable、Zod模式、索引和受身份验证保护的CRUD操作
`auth-cognito`	完整的AuthCognito无密码邮件OTP功能，包含角色、设备管理和认证器UI
`nextjs`	Next.js + React入门应用，集成AWS Blocks后端（SSR + 服务端组件）

Development Workflow

开发工作流

After scaffolding, refer to node_modules/@aws-blocks/blocks/README.md for the complete development workflow including:

Core concepts (Architecture, Building Block selection)
Project structure and Scope organization
Error handling patterns
Schema validation
Local development
Best practices and common mistakes
Deployment IAM role setup and security guidance

When implementing a specific Building Block, read its package README for the detailed API reference (e.g.,

node_modules/@aws-blocks/bb-kv-store/README.md

). These are the authoritative docs for your installed version.

搭建项目后，请参考node_modules/@aws-blocks/blocks/README.md获取完整开发工作流，包括：

核心概念（架构、构建模块选择）
项目结构和作用域组织
错误处理模式
模式验证
本地开发
最佳实践和常见错误
部署IAM角色设置和安全指南

当实现特定构建模块时，请阅读其包的README以获取详细API参考（例如

node_modules/@aws-blocks/bb-kv-store/README.md

）。这些是对应已安装版本的权威文档。

Security Considerations

安全注意事项

Use
```
await auth.requireAuth(context)
```
in every method that shouldn't be public — ApiNamespace methods are unauthenticated by default
Use
```
new AppSetting(scope, id, { secret: true })
```
for API keys and credentials — never hardcode or use
```
.env
```
files
Always attach a schema to KVStore/AppSetting that accepts user data — the RPC layer validates structure but not business logic
Do not add broad
```
*
```
IAM policies — each Building Block already grants least-privilege scoped to its own resources
Never change
```
blockPublicAccess
```
on FileBucket — serve public files through CloudFront instead
Configure
```
CORS_ALLOWED_ORIGINS
```
explicitly for production — avoid wildcards
For cross-domain deployments, pass
```
crossDomain: true
```
to auth constructors (enables
```
SameSite=None; Secure; Partitioned
```
)

Enable

monitoring: { enabled: true, snsTopicArn: '...' }

on Hosting for production alerts

Add WAF and API Gateway throttling via CDK for public-facing apps — not included by default
Logger provides serialization safety (circular refs, type coercion) but does NOT redact sensitive content — never pass raw credentials, tokens, or secrets to Logger methods; sanitize context objects before logging

在所有不应公开的方法中使用
```
await auth.requireAuth(context)
```
——ApiNamespace方法默认未认证
使用
```
new AppSetting(scope, id, { secret: true })
```
存储API密钥和凭证——切勿硬编码或使用
```
.env
```
文件
始终为接收用户数据的KVStore/AppSetting附加模式——RPC层仅验证结构，不验证业务逻辑
不要添加宽泛的
```
*
```
IAM策略——每个构建模块已授予仅限于自身资源的最小权限
切勿修改FileBucket的
```
blockPublicAccess
```
设置——应通过CloudFront提供公共文件
生产环境中显式配置
```
CORS_ALLOWED_ORIGINS
```
——避免使用通配符
对于跨域部署，向auth构造函数传递
```
crossDomain: true
```
（启用
```
SameSite=None; Secure; Partitioned
```
）

为生产环境的Hosting启用

monitoring: { enabled: true, snsTopicArn: '...' }

以接收告警

面向公众的应用通过CDK添加WAF和API网关限流——默认不包含这些功能
Logger提供序列化安全（循环引用、类型转换）但不会脱敏敏感内容——切勿将原始凭证、令牌或机密传递给Logger方法；记录前请清理上下文对象