@alpacacloud/js

@alpacabase/js

The official JavaScript/TypeScript client for AlpacaBase.

Install

npm install @alpacabase/js
# or
yarn add @alpacabase/js
# or
pnpm add @alpacabase/js

Quick Start

import { createClient } from '@alpacabase/js'

const alp = createClient(
  'https://your-project.alpaca-cloud.com',
  'your-anon-key'
)

Database

// Fetch rows
const { data, error } = await alp
  .from('posts')
  .select('id, title, author(name)')
  .eq('published', true)
  .order('created_at', { ascending: false })
  .limit(10)

// Insert
const { data } = await alp
  .from('posts')
  .insert({ title: 'Hello World', published: false })

// Update
await alp.from('posts').update({ published: true }).eq('id', 123)

// Delete
await alp.from('posts').delete().eq('id', 123)

// Single row
const { data: post } = await alp
  .from('posts')
  .select('*')
  .eq('id', 1)
  .single()

// Count
const { count } = await alp
  .from('posts')
  .select('*', { count: 'exact' })
  .eq('published', true)
  .count()

Auth

// Sign up
const { data, error } = await alp.auth.signUp({
  email: '[e-mail]',
  password: 'supersecret',
})

// Sign in
const { data, error } = await alp.auth.signInWithPassword({
  email: '[e-mail]',
  password: 'supersecret',
})

// OAuth (Google, GitHub, Discord...)
await alp.auth.signInWithOAuth({ provider: 'github' })

// Magic link
await alp.auth.signInWithOTP({ email: '[e-mail]' })

// Get current user
const { data: { user } } = await alp.auth.getUser()

// Listen for auth changes
alp.auth.onAuthStateChange((event, session) => {
  console.log(event, session?.user?.email)
})

// Sign out
await alp.auth.signOut()

Storage

// Upload a file
const { data, error } = await alp
  .storage
  .from('avatars')
  .upload('user-123.png', file, { contentType: 'image/png' })

// Get a public URL
const { data: { publicUrl } } = alp
  .storage
  .from('avatars')
  .getPublicUrl('user-123.png')

// Download
const { data: blob } = await alp.storage.from('avatars').download('user-123.png')

// List files
const { data: files } = await alp.storage.from('avatars').list('users/')

// Delete
await alp.storage.from('avatars').remove(['user-123.png'])

// Signed URL (private files)
const { data: { signedUrl } } = await alp
  .storage.from('private').createSignedUrl('report.pdf', 60) // 60 seconds

// Create a bucket
await alp.storage.createBucket('avatars', { public: true })

Realtime

// Subscribe to database changes
const channel = alp
  .realtime
  .channel('db-changes')
  .on('postgres_changes', { schema: 'public', table: 'messages', eventType: '*' }, (payload) => {
    console.log('Change:', payload.eventType, payload.new)
  })
  .subscribe()

// Broadcast (pub/sub between clients)
const room = alp.realtime.channel('room:general')

room.on('broadcast', { event: 'cursor' }, (msg) => {
  console.log('Cursor moved:', msg.payload)
})
room.subscribe()

room.send({ type: 'broadcast', event: 'cursor', payload: { x: 100, y: 200 } })

// Presence (who's online)
room.on('presence', { event: 'sync' }, ({ currentPresences }) => {
  console.log('Online users:', currentPresences)
})
room.track({ userId: 'abc', name: 'Mel' })

// Cleanup
await alp.realtime.removeChannel(channel)

TypeScript

Fully typed. Pass your row type as a generic:

interface Post { id: number; title: string; published: boolean }

const { data } = await alp.from<Post>('posts').select('*')
// data is Post[] | null

Made with 🦙 by the AlpacaBase team.