react-github-backend

A standalone React hooks library for utilizing a GitHub repository as a serverless CMS backend.

Features

• OAuth Authentication: Uses mavo.io bridge for passwordless GitHub OAuth flow.
• Git Database Read/Write: Reads file trees, creates blobs, and forms atomic commits.
• Client-side Image Optimization: Built-in canvas image compression inside the browser before commuting.
• Deployment Tracking: Real-time polling of GitHub commit statuses to track Netlify/Vercel build deployments.
• Vite Compatible: Exports lightweight target ESM modules with explicit tree-shaking support.

Installation

npm install ./libs/react-github-backend

Setup (Provider)

Wrap your application in GitHubProvider and provide your GitHub App details:

import { GitHubProvider } from "react-github-backend";

function App() {
  return (
    <GitHubProvider config={{
      githubClientId: "YOUR_CLIENT_ID",
      repoOwner: "your-username",
      repoName: "your-repo",
      branch: "main",
      authServer: "https://auth.mavo.io" // Optional
    }}>
      <YourApp />
    </GitHubProvider>
  );
}

Exposed Hooks

`useAuth()`

Manages authentication state via GitHub OAuth.

const { user, token, isReady, login, logout } = useAuth();

`useGitHub()`

Reads files and creates atomic commits.

const { readFile, commitFiles, resolveLocal } = useGitHub();

// read a file:
const { content, sha } = await readFile("public/data.json");

// perform an atomic commit:
await commitFiles([
  { path: "public/data.json", content: btoa("new content") },
  { path: "public/image.jpg", content: base64ImageData }
], "Update my database");

`useDeploy()`

Tracks CI/CD automated deployment status (e.g. Netlify) by polling commit statuses.

const { deployState, errorMessage, startTracking, resetTracking } = useDeploy();
// deployState: 'IDLE' | 'WAITING_FOR_TRIGGER' | 'BUILDING' | 'READY' | 'ERROR'

Utility Functions

• `compressImage(file, { maxWidth: 1800, quality: 0.8 })`: Compresses browser `File` blobs.
• `fileToBase64(file)`: Converts a file buffer into a base64 string.