Quick Start — SDK

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

Caution

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

1. Install the SDK

   npm install @aerostack/react

2. 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 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>
   )

3. Add authentication

   src/components/AuthForm.tsx

   import { useAuth } from '@aerostack/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>
     )
   }

4. 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'
   
   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>
     )
   }

5. Subscribe to realtime updates

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

   src/components/LiveOrders.tsx

   import { useSubscription } from '@aerostack/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 })