---
id: gh-aws-blocks
name: "aws-blocks"
url: https://skills.yangsir.net/skill/gh-aws-blocks
author: aws
domain: ai-app-building-integration
tags: ["full-stack", "infrastructure-from-code", "aws-blocks", "building-blocks", "local-development"]
install_count: 5400
rating: 4.40 (120 reviews)
github: https://github.com/aws/agent-toolkit-for-aws/tree/main/plugins/aws-core/skills/aws-blocks
---

# aws-blocks

> 该 Skill 指导使用 AWS Blocks 框架构建全栈应用，提供 18+ 个预置的 Building Blocks（覆盖存储、认证、实时通信、后台任务、文件管理等），支持本地无 AWS 凭证开发、一键部署沙箱和生产环境，显著降低后端基础设施搭建成本并加速开发迭代。

**Stats**: 5,400 installs · 4.4/5 (120 reviews)

## Before / After 对比

### 搭建后端 API 的时间

**Before**:

在没有这个技能之前，开发者需要手动配置 CDK、IAM 权限、API Gateway、Lambda 等，并编写大量样板代码，搭建一个带认证和数据存储的后端 API 通常需要 2 小时以上。

**After**:

此 Skill 只需一条命令 `npx @aws-blocks/create-blocks-app` 即可生成完整项目脚手架，选择对应的 Building Blocks 后，后端 API 搭建时间缩短至 5 分钟。

| Metric | Before | After | Change |
|---|---|---|---|
| 搭建时间 | 120分钟 | 5分钟 | -96% |

## Readme

# AWS Blocks Application Development

> **Package naming:** All packages are published under the `@aws-blocks` scope (e.g., `@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

## Scaffolding a New Project

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

### To add AWS Blocks to an existing project:

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

This detects the existing project and adds an `aws-blocks/` workspace alongside your code.

### To add AWS Blocks to an Amplify Gen 2 project:

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

When the CLI detects `amplify/backend.ts`, it automatically integrates AWS Blocks with your Amplify backend.

### With a specific template:

```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) |

## 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.

## 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


---
*Source: https://skills.yangsir.net/skill/gh-aws-blocks*
*Markdown mirror: https://skills.yangsir.net/api/skill/gh-aws-blocks/markdown*