Ir para o conteúdo
Aura Logo
aurabase

SDK JavaScript

@aurabase/aurabase-js — cliente digitado para Node, Bun, Deno, Next.js, React, SvelteKit, Vue. Abrange banco de dados, autenticação, tempo real, armazenamento, funções.

Referência10 min lidoNível referênciaRevisado em 15 de abr. de 2026

Esta página foi traduzida automaticamente. A versão em inglês é oficial.

Um pacote, quatro gerentes#

terminalbash
pnpm add @aurabase/aurabase-js
Dica

O SDK inclui diretamente a exportação @aurabase/aurabase-js/ssr para Next.js (App Router, Server Actions, Middleware), Remix, Nuxt e SvelteKit com gerenciamento automático de cookies de sessão e fragmentação anti-truncamento.

Crie o cliente#

src/lib/aurabase.tstypescript
import { createClient } from '@aurabase/aurabase-js'
import type { Database } from './aurabase.types'

export const aura = createClient<Database>(
  process.env.NEXT_PUBLIC_AURABASE_URL!,
  process.env.NEXT_PUBLIC_AURABASE_ANON_KEY!,
  { auth: { persistSession: true } }
)

Suporte para renderização nativa do lado do servidor#

Para arquiteturas SSR (Next.js App Router, Middleware, Server Actions, SvelteKit), importe createServerClient de @aurabase/aurabase-js/ssr. A sessão do usuário é armazenada automaticamente em cookies httpOnly seguros, com suporte a vários blocos para tokens grandes:

src/middleware.tstypescript
import { createServerClient } from '@aurabase/aurabase-js/ssr'
import { NextResponse, type NextRequest } from 'next/server'

export async function middleware(request: NextRequest) {
  let response = NextResponse.next({ request })
  const aura = createServerClient(
    process.env.NEXT_PUBLIC_AURABASE_URL!,
    process.env.NEXT_PUBLIC_AURABASE_ANON_KEY!,
    {
      cookies: {
        getAll() { return request.cookies.getAll() },
        setAll(cookies) {
          cookies.forEach(({ name, value, options }) => {
            request.cookies.set(name, value)
            response.cookies.set(name, value, options)
          })
        },
      },
    })
  await aura.auth.getSession()
  return response
}

Codegen do seu esquema#

npx @aurabase/gen --out lib/aurabase.types.ts (ou aura db generate, que escreve types.ts na pasta atual) gera o arquivo de tipos do seu esquema completo (tabelas, visualizações, enums, funções RPC). Para conectar-se a createClient<Database> para digitar todas as suas consultas.

package.jsonjson
{
  "scripts": {
    "types:gen": "npx @aurabase/gen --out src/aurabase.types.ts",
    "migrate": "aura db push && pnpm types:gen"
  }
}

Por serviço#

Banco de dados

  • .from(table).select(cols?) → SelectBuilder<T>
  • .from(table).insert(row) → Promise<{ data, error }>
  • .from(table).update(patch) → UpdateBuilder<T>
  • .from(table).delete() → DeleteBuilder<T>
  • .rpc(fn, args) → Promise<{ data, error }>
  • .nosql.collection(name) → NoSqlCollectionClient (find(), insertOne(), aggregate(), createIndex())

Autenticação

  • .auth.signUp({ email, password, options? }) → Promise<AuraResponse<LoginResponse>>
  • .auth.signInWithPassword({ email, password }) → Promise<AuraResponse<LoginResponse>>
  • .auth.signInWithOAuth(provider, opts?) | ({ provider, ... }) → Promise<AuraResponse<{ url }>>
  • .auth.getSession() → Promise<{ data: { session }, error }>
  • .auth.signOut() → Promise<AuraResponse<void>>
  • .auth.mfa.enroll() | .auth.mfaEnroll() → Promise<AuraResponse<MfaEnrollResponse>>

Tempo real

  • .channel(name, config?) → Channel
  • channel.on(event, filter, cb) → Channel
  • channel.subscribe() → Channel
  • channel.send({ type, event, payload }) → Promise<void>
  • channel.unsubscribe() → Promise<void>

Armazenamento

  • .storage.from(bucket).upload(path, file, opts?) → Promise<{ data, error }>
  • .storage.from(bucket).download(path) → Promise<Blob>
  • .storage.from(bucket).getPublicUrl(path, opts?) → { publicUrl }
  • .storage.from(bucket).createSignedUrl(path, expiresIn) → Promise<{ signedUrl }>
  • .storage.from(bucket).remove(paths[]) → Promise<{ data, error }>

Funções

  • .functions.invoke(name, { body?, method?, path?, headers?, responseType?, signal?, timeout? }) → Promise<{ data, error }>
  • .functions.list() → Promise<{ data: FunctionDef[], error }>
  • .functions.get(nameOrId) → Promise<{ data: FunctionDef, error }>
  • .functions.listJobs({ status?, limit? }) → Promise<{ data: Job[], error }>
  • .functions.getJob(jobId) → Promise<{ data: Job, error }>
  • .functions.enqueueJob(functionName, { payload?, delaySecs?, maxAttempts? }) → Promise<{ data: Job, error }>
  • .functions.listCronJobs() → Promise<{ data: CronJob[], error }>
  • .functions.createCronJob(name, schedule, functionName, { payload? }) → Promise<{ data: CronJob, error }>
  • .functions.deleteCronJob(name) → Promise<{ data, error }>

Apenas invoke está aberto à chave pública (anon). list, get, listJobs, getJob, enqueueJob, listCronJobs, createCronJob e deleteCronJob requerem uma chave service_role e pertencem ao seu servidor: um FunctionDef carrega o código-fonte da função e as variáveis de ambiente, então essas chamadas respondem 403 para uma chave pública. invoke relata erros como FunctionsHttpError (a função respondeu com erro, qualquer status) ou FunctionsRelayError (a plataforma falhou: rede, 502, 503, 504), ambos exportados por @aurabase/aurabase-js.

Forma uniforme {dados, erro}#

Cada método assíncrono retorna { data, error }. error é null em caso de sucesso, caso contrário, uma instância AuraError (também exportada sob o alias AurabaseError) com code, message, status e details. Passe { parseBigIntAsString: true } nas opções createClient se seu esquema usar valores bigint de 64 bits além de Number.MAX_SAFE_INTEGER.

errors.tstypescript
import { AurabaseError } from '@aurabase/aurabase-js'

const { data, error } = await aura.from('users').select('*').single()

if (error) {
  if (error.code === 'PGRST116') notFound()
  throw error // instância de AuraError / AurabaseError
}

Para ir mais longe#