Skip to content

README.md

Latest commit

 

History

History
131 lines (90 loc) · 4.14 KB

README.md

File metadata and controls

131 lines (90 loc) · 4.14 KB
Raw

AWS Blocks Dart

The Dart SDK for AWS Blocks.

AWS Blocks lets you define a backend in TypeScript — APIs, auth, databases, realtime channels, file storage — and deploy it to AWS. This SDK gives your Flutter app a typed client that talks to that backend with zero boilerplate.

How it works

You write your backend. AWS Blocks generates a spec file describing your API. This SDK reads that spec and produces a Dart client with typed methods, models, and realtime subscriptions — ready to drop into your Flutter app.

Your backend (TypeScript)  →  blocks.spec.json  →  blocks_codegen  →  Typed Dart client

What you get

final blocks = Blocks(baseUrl: 'https://your-api.example.com');

// Call your API methods with full type safety
final todo = await blocks.api.createTodo(title: 'Buy milk', priority: 1);
final todos = await blocks.api.listTodos(sortBy: SortBy.priority);

// Auth flows with exhaustive variants
await blocks.authApi.setAuthState(
  input: SignInInput(username: 'alice', password: 'secret'),
);

// Realtime — subscribe to live data over WebSocket
final channel = await blocks.api.getCursorChannel();
channel.subscribe().listen((cursor) {
  print('${cursor.userId} moved to (${cursor.x}, ${cursor.y})');
});

Packages

Package Role
blocks_runtime The runtime your app ships with — HTTP client, WebSocket realtime, file handles
blocks_codegen The code generator — reads your spec, outputs Dart. Only runs at build time.

Getting started

1. Add dependencies

# pubspec.yaml
dependencies:
  blocks_runtime: ^1.0.0

dev_dependencies:
  blocks_codegen: ^1.0.0
  build_runner: ^2.4.0

2. Add your spec and configure the builder

Drop your blocks.spec.json into lib/, then create a build.yaml:

targets:
  $default:
    builders:
      blocks_codegen|blocks_codegen:
        options:
          spec: lib/blocks.spec.json

3. Generate your client

dart run build_runner build

This produces a typed Dart client from your spec.

4. Use it

import 'package:blocks_runtime/blocks_runtime.dart';
import 'blocks.blocks.dart';

final blocks = Blocks(baseUrl: 'http://localhost:3001/aws-blocks/api');
final greeting = await blocks.hello.greet(name: 'World');
print(greeting.message); // "Hello, World!"

Features

Type-safe API calls — every method, parameter, and return type is generated from your spec. Typos and type mismatches are caught at compile time.

Realtime subscriptions — if your backend has realtime channels (e.g., cursor tracking, live updates), the generated client gives you typed Stream<T> subscriptions over WebSocket.

Auth flows — discriminated unions become sealed classes. The compiler ensures you handle every auth state variant.

File transfers — presigned upload/download URLs are wrapped in handle objects with simple .upload(bytes) / .download() methods.

No Flutter dependency — blocks_runtime is pure Dart. Works in CLI apps, server-side Dart, or Flutter.

Project structure

native/dart/
├── packages/
│   ├── blocks_runtime/          # Runtime library (ships with your app)
│   ├── blocks_codegen/          # Code generator (build-time only)
│   └── blocks_runtime_flutter/  # Flutter integration (secure storage, browser launcher)
├── example/                     # Demo Flutter app with auth, todos, realtime cursors
└── README.md

Requirements

  • Dart 3.3+
  • Flutter (for the demo app — the SDK itself is pure Dart)
  • Node.js 22+ (for running the AWS Blocks backend locally)

How the codegen works

The generator has three stages:

  1. Parse — reads the OpenRPC JSON spec, extracts methods, schemas, and type relationships
  2. Build — resolves types, deduplicates identical shapes, groups methods into namespaces
  3. Generate — outputs Dart source with data classes, sealed hierarchies, API methods, and a Blocks facade

The output is a single self-contained .blocks.dart file. For backends with realtime or file features, it also imports blocks_runtime for WebSocket and presigned URL support.

License

MIT