Quick Start

Get a React app connected to Aerostack with auth, database queries, and realtime subscriptions in under three minutes.

⚠️

Beta — The Aerostack SDK is in active beta. Pin your dependency versions for production use.

Install the SDK

npm install @aerostack/react

Wrap your app with the provider

Find your Project ID and Public API Key in the Aerostack Dashboard under Project Settings.

src/main.tsx

import React from 'react'
import ReactDOM from 'react-dom/client'
import { AerostackProvider } from '@aerostack/react'
import App from './App'
 
ReactDOM.createRoot(document.getElementById('root')!).render(
  <AerostackProvider
    projectId="proj_abc123"
    apiKey="pk_live_your_public_key"
    baseUrl="https://api.aerostack.dev/v1"
  >
    <App />
  </AerostackProvider>
)

Add authentication

src/components/AuthForm.tsx

import { useAuth } from '@aerostack/react'
import { useState } from 'react'
 
export function AuthForm() {
  const { user, signIn, signUp, signOut, loading, error } = useAuth()
  const [email, setEmail] = useState('')
  const [password, setPassword] = useState('')
 
  if (loading) return <p>Loading...</p>
 
  if (user) {
    return (
      <div>
        <p>Signed in as {user.email}</p>
        <button onClick={signOut}>Sign out</button>
      </div>
    )
  }
 
  return (
    <form onSubmit={async (e) => {
      e.preventDefault()
      await signIn(email, password)
    }}>
      <input
        type="email"
        value={email}
        onChange={(e) => setEmail(e.target.value)}
        placeholder="Email"
      />
      <input
        type="password"
        value={password}
        onChange={(e) => setPassword(e.target.value)}
        placeholder="Password"
      />
      {error && <p style={{ color: 'red' }}>{error}</p>}
      <button type="submit">Sign in</button>
      <button type="button" onClick={() => signUp(email, password, { name: 'New User' })}>
        Sign up
      </button>
    </form>
  )
}

Query your database

Use the useDb hook to run SQL queries from your React components. Queries run through your server-side Logic Modules, keeping API keys secure.

src/components/UserList.tsx

import { useDb } from '@aerostack/react'
import { useEffect, useState } from 'react'
 
export function UserList() {
  const { query, loading, error } = useDb()
  const [users, setUsers] = useState([])
 
  useEffect(() => {
    async function load() {
      const { results } = await query('SELECT id, name, email FROM users ORDER BY created_at DESC LIMIT 20')
      setUsers(results)
    }
    load()
  }, [])
 
  if (loading) return <p>Loading users...</p>
  if (error) return <p>Error: {error}</p>
 
  return (
    <ul>
      {users.map(u => <li key={u.id}>{u.name} ({u.email})</li>)}
    </ul>
  )
}

Get live updates when rows change in your database. No polling required.

src/components/LiveOrders.tsx

import { useSubscription } from '@aerostack/react'
import { useState } from 'react'
 
export function LiveOrders() {
  const [orders, setOrders] = useState([])
 
  useSubscription('orders', {
    onInsert: (payload) => {
      setOrders(prev => [payload.data, ...prev])
    },
    onUpdate: (payload) => {
      setOrders(prev => prev.map(o => o.id === payload.data.id ? payload.data : o))
    },
    onDelete: (payload) => {
      setOrders(prev => prev.filter(o => o.id !== payload.data.id))
    },
  })
 
  return (
    <div>
      <h2>Live Orders</h2>
      {orders.map(order => (
        <div key={order.id}>
          Order #{order.id} -- {order.status}
        </div>
      ))}
    </div>
  )
}

What to explore next

Module	Guide	What you can build
Auth	Authentication	Registration, OTP, magic links, password reset, profiles
Database	Database	CRUD, batch transactions, parameterized queries
Realtime	Realtime	Live chat, presence, DB subscriptions, collaborative editing
Storage	Storage	File uploads, CDN URLs, avatars, document management
AI	AI & Vector Search	Chat completions, streaming, RAG, semantic search
Cache & Queue	Cache & Queue	Session storage, background jobs, counters
Error Handling	Error Handling	Error types, retry strategies, debugging

Server-side quick start (Node.js)

If you are building a Node.js backend, Cloudflare Worker, or edge function instead of a React app:

server.ts

import { AerostackClient } from '@aerostack/sdk'
 
const client = new AerostackClient({
  projectId: process.env.PROJECT_ID,
  apiKey: process.env.API_KEY,
  baseUrl: 'https://api.aerostack.dev/v1',
})
 
const { sdk } = client
 
// Query the database
const { results: users } = await sdk.db.query('SELECT * FROM users WHERE active = 1')
 
// Cache a result
await sdk.cache.set('active-users', users, { ttl: 300 })
 
// Send a background job
await sdk.queue.enqueue('send-welcome-email', { userId: users[0].id })

Overview Authentication