usePublicCollection

Name: Flowstack
Author: Flowstack

hook

Anonymous, no-auth public collection reads and inserts for leaderboards, guestbooks, comment threads, and voting.

import { usePublicCollection } from 'flowstack-sdk'

Anonymous public submissions — leaderboards, guestbooks, comment threads, voting. No auth required. Any visitor can read and insert. The collection must be declared in app_config.publicCollections.

Key differences from `useCollection`: - No credentials needed — works for anonymous visitors - Insert only (no update/remove — data is owned by the app, not the user) - Rate-limited server-side (default 10 writes/min, 100/day per IP) - The collection must be in app_config.publicCollections (ask the builder to configure it; the build pipeline sets this up based on usePublicCollection usage in the source)

Signature

const { documents, count, total, isLoading, error, insert, refresh } = usePublicCollection<T>(name, options?)

Parameters

Param	Type	Notes	Description
`name`	`string`	required	Public collection name (must be declared in `app_config.publicCollections`).
`options.filter`	`Filter<T>`	—	MongoDB query filter, e.g. `{ album: 'yeezus' }`.
`options.sort`	`Record<string, 1 \| -1>`	—	Sort spec, e.g. `{ score: -1 }`.
`options.limit`	`number`	—	Max documents to return.

Returns

Field	Type	Description
`documents`	`T[]`	The fetched documents.
`count`	`number`	Documents returned.
`total`	`number`	Total matching documents.
`isLoading`	`boolean`	Fetch in flight.
`error`	`string \| null`	Last error message.
`insert`	`(doc: Partial<T>) => Promise<{ inserted_id: string }>`	Insert a public document (rate-limited per IP).
`refresh`	`() => Promise<void>`	Manual re-fetch.

Examples

Anonymous leaderboard

import { usePublicCollection } from 'flowstack-sdk';

const {
  documents,   // T[]
  count,       // number
  total,       // number
  isLoading,   // boolean
  error,       // string | null
  insert,      // (doc: Partial<T>) => Promise<{ inserted_id: string }>
  refresh,     // () => Promise<void>
} = usePublicCollection<HighScore>('high_scores', {
  filter: { album: 'yeezus' },
  sort: { score: -1 },
  limit: 25,
});

await insert({ album: 'yeezus', name: 'KEON', score: 12500 });

Builder config required in app_config.json

{
  "publicCollections": {
    "high_scores": {
      "schema": {
        "album": { "type": "string", "required": true, "maxLength": 32 },
        "name":  { "type": "string", "required": true, "maxLength": 24 },
        "score": { "type": "number", "required": true, "min": 0 }
      },
      "rateLimit": { "writesPerMinute": 5, "writesPerDay": 50 }
    }
  }
}

NoteNo auth required — any visitor can read and insert. Insert only: there is no update or remove because data is owned by the app, not the user.

WarningWrites are rate-limited server-side (default 10 writes/min, 100/day per IP). The collection must be declared in app_config.publicCollections.

CriticalRequires `tenantId` on `FlowstackProvider`. Anonymous visitors have no token, so the backend can't derive the tenant — this is the one hook that needs tenantId set explicitly. If it's missing, the hook raises a clear error instead of silently using a default. Authenticated hooks don't need it (tenant comes from the JWT).

usePublicCollection

Signature

Parameters

Returns

Examples

See also