Best practices for AWS Blocks

This topic covers best practices for structuring, securing, testing, and scaling AWS Blocks applications.

Project structure

Organize your backend code for clarity and maintainability.

Keep the IFC layer thin. Your aws-blocks/index.ts should contain Block instantiations and API definitions. Move complex business logic into separate modules.

// aws-blocks/index.ts - thin orchestration layer
import { ApiNamespace, Scope, KVStore } from '@aws-blocks/blocks';
import { createOrder, listOrders } from './orders.js';

const scope = new Scope('my-app');
const store = new KVStore(scope, 'orders', {});

export const api = new ApiNamespace(scope, 'api', (context) => ({
  createOrder: (input) => createOrder(store, context, input),
  listOrders: () => listOrders(store, context),
}));

// aws-blocks/orders.ts - business logic, testable in isolation
export async function createOrder(store, context, input) {
  // validation, business rules, persistence
}

Use a single Scope per application. Multiple scopes in one backend create separate resource namespaces, which adds complexity without benefit for most applications.

Co-locate related Blocks. If your app has distinct domains (orders, users, notifications), group them logically but keep them in the same IFC layer file unless the file becomes unwieldy.

Error handling

AWS Blocks propagates errors from your API methods to the frontend with the error name preserved. Use named errors to enable structured error handling on the client.

// Backend
import { isBlocksError } from '@aws-blocks/blocks';

export const api = new ApiNamespace(scope, 'api', (context) => ({
  async getItem(id: string) {
    const item = await store.get(id);
    if (!item) {
      const err = new Error(`Item ${id} not found`);
      err.name = 'NotFoundError';
      throw err;
    }
    return item;
  },
}));

// Frontend
import { api } from '../aws-blocks/index.js';
import { isBlocksError } from '@aws-blocks/blocks';

try {
  await api.getItem('abc');
} catch (err) {
  if (isBlocksError(err, 'NotFoundError')) {
    // Handle not found
  }
}

Best practices for errors:

Authentication and authorization

Always validate the user in every API method that accesses user data. Don’t rely on frontend-only checks.

export const api = new ApiNamespace(scope, 'api', (context) => ({
  async getMyData() {
    // Always authenticate server-side
    const user = await auth.getCurrentUser(context);
    return store.get(`user:${user.userId}`);
  },
}));

Scope data access by user. Use the user ID as a key prefix to prevent users from accessing each other’s data:

// Good: scoped to user
await store.set(`${user.userId}:${itemId}`, data);

// Bad: no user scoping - any authenticated user can access any item
await store.set(itemId, data);

Choose the right auth Block:

Local development

Develop locally first. Use npm run dev as your primary development loop. Only deploy to a sandbox when you need to test behavior specific to real AWS services.

Understand local implementation limitations. Local implementations replicate the API surface but not all production behavior:

Clear local data when needed. Delete the .bb-data/ directory to reset all local state:

rm -rf .bb-data

Testing

Unit test your business logic independently. Extract logic from API handlers into pure functions that accept Block instances as parameters.

// orders.ts - testable without the full framework
export async function createOrder(store: KVStore, userId: string, input: OrderInput) {
  if (!input.title) throw new Error('Title required');
  const order = { id: crypto.randomUUID(), ...input, userId };
  await store.set(`${userId}:${order.id}`, order);
  return order;
}

// orders.test.ts
import { createOrder } from './orders.js';

it('creates an order', async () => {
  const mockStore = { set: vi.fn(), get: vi.fn() };
  const result = await createOrder(mockStore, 'user-1', { title: 'Test' });
  expect(result.title).toBe('Test');
  expect(mockStore.set).toHaveBeenCalled();
});

Integration test locally. Run your full application with npm run dev and test the API endpoints. Local implementations are deterministic and fast.

End-to-end test with sandbox. For critical paths, deploy to a sandbox and run tests against real AWS services to catch behavior differences.

Performance

Minimize Block instantiations. Each Block maps to AWS resources. Don’t create a new KVStore for every data type. Use key prefixes to partition data within a single store.

// Good: one store, partitioned by prefix
const store = new KVStore(scope, 'data', {});
await store.set(`users:${id}`, userData);
await store.set(`orders:${id}`, orderData);

// Avoid: separate stores for each entity (more DynamoDB tables, more cost)
const userStore = new KVStore(scope, 'users', {});
const orderStore = new KVStore(scope, 'orders', {});

Use DistributedTable for query-heavy workloads. If you need to query by multiple attributes or sort data, DistributedTable with indexes is more efficient than scanning a KVStore.

Keep API methods focused. Each ApiNamespace method becomes a Lambda invocation path. Avoid methods that do too many things. Split them into focused operations.

Deployment

Use sandbox for development, full deploy for production. Sandboxes use Lambda hot-swapping for speed but aren’t suitable for production traffic.

Set up separate AWS accounts for development, staging, and production. AWS Blocks deploys the same code to any account. The resources are derived from your code, not from environment-specific configuration.

Configure environment-specific settings in the CDK layer. Custom domains, VPC configuration, and other environment differences belong in aws-blocks/index.cdk.ts, not in your runtime code.

// aws-blocks/index.cdk.ts
const isProd = process.env.DEPLOY_ENV === 'production';

const stack = await BlocksStack.create(app, stackName, { /* ... */ });

if (isProd) {
  // Production-only: custom domain, WAF, etc.
  new Hosting(stack, 'Hosting', {
    customDomain: 'app.example.com',
  });
}

Working with AI agents

AWS Blocks is designed to work well with AI coding assistants. Steering files ship in the npm package, guiding agents to produce correct architecture from the start.

To get the best results from AI coding agents:

Example prompt for AI agents

The following prompt demonstrates how an AI agent can add multiple capabilities in a single interaction:

Add a FileBucket for user avatars, an AsyncJob that generates thumbnails on upload, and a Realtime channel that notifies the UI when processing completes.