Aerostack SDKs

Official multi-language SDK suite for the Aerostack Platform. Unified access to authentication, database, caching, queues, storage, AI, realtime, and e-commerce services.

Which SDK Should I Use?

I'm building...	Use this SDK
A Node.js server or API	@aerostack/node
A React web app	@aerostack/react
A vanilla JS / SPA browser app	@aerostack/web
A Cloudflare Worker (server + client)	@aerostack/sdk
A React Native mobile app	@aerostack/react-native
A Flutter mobile app	@aerostack/flutter
A Python backend	aerostack (Python)
CLI tooling / local dev	aerostack (CLI)

SDK Packages

Core

Package	Language	Description
@aerostack/core	TypeScript	Shared types and RPC client — build this first
@aerostack/sdk	TypeScript	Universal SDK for Workers + Browser (Client + Server)

Client SDKs

Package	Language	Environment
@aerostack/node	TypeScript	Node.js (CJS + ESM)
@aerostack/web	TypeScript	Browser / SPA
@aerostack/react	TypeScript + React	Browser / Next.js / SSR frameworks
@aerostack/react-native	TypeScript	iOS / Android (Expo compatible)
aerostack	Python	Backend services
aerostack_sdk	Dart	iOS / Android / Web / Desktop

Developer Tools

Package	Language	Description
aerostack CLI	Go	Project scaffolding, local dev, database management, deployment

Quick Start

Install the CLI

curl -fsSL https://get.aerostack.dev | sh

Create a New Project

aerostack init my-app --template=blog
cd my-app
aerostack dev

Use an SDK

Node.js

import { SDK } from '@aerostack/node';

const sdk = new SDK({ apiKeyAuth: process.env.AEROSTACK_API_KEY });
const result = await sdk.database.dbQuery({ sql: 'SELECT * FROM users' });

React

import { AerostackProvider, useAuth } from '@aerostack/react';

function App() {
  return (
    <AerostackProvider projectUrl="https://my-project.aerostack.dev" apiKey="pk_...">
      <LoginButton />
    </AerostackProvider>
  );
}

Python

import aerostack

config = aerostack.Configuration(host="https://api.aerostack.dev/v1")
config.api_key['ApiKeyAuth'] = os.environ["AEROSTACK_API_KEY"]

with aerostack.ApiClient(config) as client:
    db = aerostack.DatabaseApi(client)
    result = db.db_query(aerostack.DbQueryRequest(sql="SELECT * FROM users"))

Build Order

packages/core  →  packages/{node, web, react, sdk, react-native}  →  packages/{python, flutter}

Always build core first — all other TypeScript SDKs depend on its types.

cd packages/core && npm run build

Architecture

See SDK_ARCHITECTURE.md for detailed usage patterns and the SDK decision tree. See EXAMPLES.md for code examples across all SDKs.

OpenAPI Specification

The source of truth for the API surface is spec/openapi.yaml. This drives:

• Python SDK generation (OpenAPI Generator)
• Flutter SDK generation (OpenAPI Generator)
• API documentation (Redoc)

Do not hand-edit generated code in packages/python/aerostack/ or packages/flutter/lib/. Instead, edit the spec and regenerate:

./scripts/generate.sh

Versioning

Artifact	Version Source	Release Method
TypeScript SDKs	VERSION_CORE	./scripts/publish.sh
CLI	VERSION_CLI	GoReleaser via CI
Python / Flutter	spec/openapi.yaml	./scripts/generate.sh

SDK Sync

Each SDK has its own downstream GitHub repository. The sdk-sync.yml CI workflow pushes to them on merge to main. Manual sync:

./scripts/sync.sh

Development

Prerequisites

• Node.js 18+
• Go 1.24+ (for CLI)
• Python 3.7+ (for Python SDK)
• Flutter / Dart (for Flutter SDK)

Generate SDKs

npm run generate        # Generate Python + Flutter from OpenAPI spec

Test

npm test                # Run all tests
cd packages/cli && go test ./...   # CLI tests
cd packages/python && pytest       # Python tests

Publish

npm run publish:all     # Publish all SDKs to registries

Deployment & Release (CI/CD)

Required Repository Secrets

Secret	Description
NPM_TOKEN	npm automation token for publishing TypeScript packages
SDK_SYNC_PAT	GitHub PAT with repo scope for syncing to downstream repos

Development Workflow

1. Edit the OpenAPI spec or TypeScript source
2. Generate SDKs locally: npm run generate
3. Commit generated code: git add packages/* && git commit -m "chore(sdks): regenerate"
4. Push — CI validates, tests, and publishes on merge to main

Generation runs locally, not in CI. See docs/SDK_GENERATION_PLAN.md.

Directory Structure

sdks/
├── spec/
│   └── openapi.yaml              # API specification (single source of truth)
├── packages/
│   ├── core/                     # @aerostack/core — shared types
│   ├── node/                     # @aerostack/node — Node.js SDK
│   ├── web/                      # @aerostack/web — Browser SDK
│   ├── react/                    # @aerostack/react — React hooks
│   ├── sdk/                      # @aerostack/sdk — Universal (Workers + Browser)
│   ├── react-native/             # @aerostack/react-native — Mobile SDK
│   ├── python/                   # aerostack — Python SDK (generated)
│   ├── flutter/                  # aerostack_sdk — Flutter SDK (generated)
│   └── cli/                      # aerostack CLI (Go)
├── scripts/
│   ├── generate.sh               # Generate Python + Flutter SDKs
│   ├── publish.sh                # Publish TypeScript SDKs
│   └── sync.sh                   # Sync to downstream repos
└── .github/workflows/
    ├── generate-sdks.yml         # CI/CD automation
    ├── sdk-sync.yml              # Downstream repo sync
    └── release-cli.yml           # CLI release (GoReleaser)

Contributing

See CONTRIBUTING.md.

License

MIT