nodeworks/nivaro repository overview

cp .env.example .env
# fill in DB_*, OIDC_*, SESSION_SECRET

pnpm install
pnpm migrate
pnpm dev
# API → http://localhost:3055
# Admin → http://localhost:3056

pnpm dev:docker        # build + start all containers
pnpm dev:docker:down   # stop and remove

pnpm release patch     # bumps package.json, tags @app-x.x.x, pushes
pnpm release minor
pnpm release 2.3.0     # exact version

nodeworks/nivaro:2.3.0
nodeworks/nivaro:latest

pnpm sdk:release patch
pnpm sdk:release minor
pnpm sdk:release 1.7.0

pnpm www:release patch

docker pull nodeworks/nivaro:latest

services:
  nivaro:
    image: nodeworks/nivaro:latest
    ports:
      - "3055:3055"
    env_file: .env
    environment:
      REDIS_URL: redis://redis:6379
      INNGEST_BASE_URL: http://inngest:8288
      INNGEST_EVENT_KEY: ${INNGEST_SIGNING_KEY_DOCKER:-deadbeefcafebabedeadbeefcafebabedeadbeefcafebabedeadbeefcafebabe}
      INNGEST_SIGNING_KEY: ${INNGEST_SIGNING_KEY_DOCKER:-deadbeefcafebabedeadbeefcafebabedeadbeefcafebabedeadbeefcafebabe}
    volumes:
      - ./extensions:/app/api/extensions
      - uploads:/app/uploads
    depends_on:
      redis:
        condition: service_healthy
      inngest:
        condition: service_healthy

  redis:
    image: redis:7-alpine
    command: redis-server --appendonly yes
    volumes:
      - redis_data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 5

  postgres:
    image: postgres:15-alpine
    environment:
      POSTGRES_USER: inngest
      POSTGRES_PASSWORD: inngest
      POSTGRES_DB: inngest
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U inngest -d inngest"]
      interval: 5s
      timeout: 3s
      retries: 10

  inngest:
    image: inngest/inngest:latest
    command: inngest start --host 0.0.0.0
    ports:
      - "8288:8288"
    environment:
      INNGEST_EVENT_KEY: ${INNGEST_SIGNING_KEY_DOCKER:-deadbeefcafebabedeadbeefcafebabedeadbeefcafebabedeadbeefcafebabe}
      INNGEST_SIGNING_KEY: ${INNGEST_SIGNING_KEY_DOCKER:-deadbeefcafebabedeadbeefcafebabedeadbeefcafebabedeadbeefcafebabe}
      INNGEST_POSTGRES_URI: postgres://inngest:inngest@postgres:5432/inngest
      INNGEST_REDIS_URI: redis://redis:6379
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy

volumes:
  uploads:
  redis_data:
  postgres_data:

npm install @nivaro/sdk

import { createNivaro, readItems, createItem, _eq, desc } from '@nivaro/sdk'

const nivaro = createNivaro('https://your-nivaro-host', { token: 'your-static-token' })

// List items with filter + sort
const { data, total } = await nivaro.request(
  readItems('projects', {
    filter: { status: _eq('active') },
    sort: [desc('created_at')],
    limit: 25,
  })
)

// GraphQL
const result = await nivaro.graphql(`
  query { projects(filter: { status: { _eq: "active" } }) { data { id name } total } }
`)

// Realtime
import { createRealtime } from '@nivaro/sdk'
const rt = createRealtime()
rt.connect('https://your-nivaro-host', 'your-token')
const unsub = rt.subscribe('projects', { event: 'update' }, (data) => console.log(data))

api/extensions/
└── my-extension/
    ├── src/index.ts
    ├── index.js         ← compiled output (loaded by Nivaro)
    ├── package.json
    └── tsconfig.json

// src/index.ts
import type { FastifyInstance } from 'fastify'
import type { Knex } from 'knex'

interface ExtensionContext {
  app: FastifyInstance
  database: Knex
  logger: FastifyInstance['log']
  hooks: {
    before(collection: string | '*', action: string | '*', fn: (...args: unknown[]) => unknown): void
    after(collection: string | '*', action: string | '*', fn: (...args: unknown[]) => unknown): void
  }
  cron: {
    schedule(id: string, expression: string, fn: () => void | Promise<void>): void
  }
  callExternalApi(nameOrId: string | number, options?: Record<string, unknown>): Promise<unknown>
}

export default {
  id: 'my-extension',
  async register({ app, database, logger, hooks, cron, callExternalApi }: ExtensionContext) {
    // Custom route
    app.register(async (f) => {
      f.get('/my-route', async () => ({ ok: true }))
    }, { prefix: '/api' })

    // Hook into mutations
    hooks.after('projects', 'create', async ({ item }) => {
      logger.info({ item }, 'project created')
    })

    // Scheduled job
    cron.schedule('daily-cleanup', '0 2 * * *', async () => {
      await database('my_temp_table').where('created_at', '<', new Date()).delete()
    })
  },
}