@airdraft/react

React hooks and provider for Airdraft CMS. Handles all data fetching, auth state, media management, and team management through a simple hook API.

Installation

npm install @airdraft/react

Setup

Wrap your CMS UI with AirdraftProvider:

import { AirdraftProvider } from '@airdraft/react'

export default function CmsLayout({ children }: { children: React.ReactNode }) {
  return (
    <AirdraftProvider apiUrl="/api/cms">
      {children}
    </AirdraftProvider>
  )
}

With authentication:

<AirdraftProvider
  apiUrl="/api/cms"
  auth={{ type: 'session' }}
  adminKey={process.env.NEXT_PUBLIC_CMS_ADMIN_KEY}
>
  {children}
</AirdraftProvider>

Hooks

Content

useEntries(collection, options?)

const { entries, total, loading, error, refresh } = useEntries('posts', {
  status: 'published',
  limit: 10,
  page: 1,
  sort: 'createdAt',
  order: 'desc',
})

useEntry(collection, slug)

const { entry, loading, error, refresh } = useEntry('posts', 'hello-world')

useMutateEntry(collection)

const { creating, createEntry, updateEntry, deleteEntry } = useMutateEntry('posts')

await createEntry({ title: 'Hello', body: '' })
await updateEntry('hello-world', { title: 'Updated' }, sha)
await deleteEntry('hello-world', sha)

useCms(collection, listOptions?)

Combined read + write hook for collection management. Returns all fields from useEntries and useMutateEntry in one object.

const { entries, loading, createEntry, updateEntry, deleteEntry } = useCms('posts')

Authentication

useAuth()

const {
  user,           // CmsUser | null
  isLoading,
  isAuthenticated,
  role,           // CmsRole | null ('admin' | 'publisher' | 'editor')
  can,            // RolePermissions | null
  error,
  login,          // (email, password) => Promise<void>
  logout,         // () => Promise<void>
  refresh,        // () => Promise<void>
} = useAuth()

can is an object of booleans derived from the user's role:

interface RolePermissions {
  publish: boolean
  deletePublished: boolean
  manageSchema: boolean
  manageTeam: boolean
}

Media

useMedia(options?)

Composite hook combining library, upload, and delete. Auto-refreshes the library after upload or delete.

const {
  items,       // MediaItem[]
  loading,
  error,
  upload,      // (file: File) => Promise<MediaItem>
  deleteItem,  // (key: string) => Promise<void>
  refresh,
} = useMedia({ prefix: 'uploads' })

useMediaLibrary(options?)

const { items, loading, error, refresh } = useMediaLibrary({ prefix: 'uploads' })

useMediaUpload()

const { upload, uploading, error } = useMediaUpload()
const item = await upload(file)

useMediaDelete()

const { deleteItem, deleting, error } = useMediaDelete()
await deleteItem(key)

Team

useTeam()

const {
  users,         // CmsUser[]
  invites,       // CmsInvite[]
  loading,
  error,
  createInvite,  // (email, role) => Promise<CmsInvite>
  revokeInvite,  // (token) => Promise<void>
  changeRole,    // (userId, role) => Promise<void>
  removeUser,    // (userId) => Promise<void>
} = useTeam()

Schema Editor

useSchemaEditor()

Returns state and actions for the visual schema editor UI. Used internally by @airdraft/react-ui's <SchemaEditor>.

Utilities

usePagination()

const { page, limit, setPage, setLimit, offset } = usePagination({ defaultLimit: 10 })

useAirdraftClient()

Returns the raw AirdraftClient instance for custom queries.

Exports

// Provider
export { AirdraftProvider }
export type { AirdraftProviderProps }

// Content hooks
export { useEntries, useEntry, useMutateEntry, useCms }
export type { UseEntriesState, UseEntryState, UseMutateEntryState, UseCmsState }

// Auth hooks
export { useAuth }
export type { UseAuthState, CmsRole, CmsUser, CmsInvite, RolePermissions }

// Media hooks
export { useMedia, useMediaLibrary, useMediaUpload, useMediaDelete }
export type { UseMediaState, UseMediaLibraryState, UseMediaUploadState, UseMediaDeleteState, UseMediaLibraryOptions }

// Team hooks
export { useTeam }
export type { UseTeamState }

// Schema editor
export { useSchemaEditor }
export type { UseSchemaEditorState }

// Utilities
export { usePagination, useAirdraftClient }
export type { UsePaginationState }

Changelog

See CHANGELOG.md.