Install

This section takes you from an empty directory to a running API, one page at a time: install the packages, set up the database and the search index, then register the plugin.

Prerequisites

• Node.js 22.18 or later. These pages run TypeScript files directly with node, which strips types without a build step.
• pnpm. The commands use pnpm; npm and Yarn work too.
• PostgreSQL 18 or later. arocapi doesn’t support other databases.
• OpenSearch for search.

For local development, run the database and OpenSearch with Docker Compose:

compose.yaml

services:
  db:
    image: postgres:18
    ports:
      - 5432:5432
    environment:
      POSTGRES_PASSWORD: password
      POSTGRES_DB: catalog

  opensearch:
    image: opensearchproject/opensearch:3
    ports:
      - 9200:9200
    environment:
      - discovery.type=single-node
      - DISABLE_SECURITY_PLUGIN=true
      - OPENSEARCH_JAVA_OPTS=-Xms512m -Xmx512m

docker compose up -d

Create the project

arocapi is an ES module, so your project needs "type": "module":

mkdir my-repository && cd my-repository
pnpm init
pnpm pkg set type=module

Add the packages

pnpm add arocapi@beta fastify @opensearch-project/opensearch @prisma/client@7 @prisma/adapter-pg@7
pnpm add -D prisma@7 dotenv

• arocapi is the plugin. It depends on Fastify, but you install fastify yourself to create the server it runs in.
• @prisma/client is a peer dependency. arocapi reads entities through the Prisma client that you generate in your project. arocapi needs Prisma 7.10 or later 7.x; Prisma 8 isn’t supported.
• @prisma/adapter-pg is the driver adapter Prisma 7 needs to connect to PostgreSQL.
• prisma is the CLI that runs migrations and generates the client. Pin it to 7: prisma@latest is Prisma 8, which can’t read a Prisma 7 config.
• @opensearch-project/opensearch is the search client you pass to arocapi.
• dotenv loads .env for the Prisma CLI.

pnpm doesn’t run dependency build scripts until you allow them. The Prisma CLI needs the schema engine that @prisma/engines downloads when it installs, so allow that one in pnpm-workspace.yaml and rebuild it:

pnpm-workspace.yaml

allowBuilds:
  '@prisma/engines': true
  prisma: false

pnpm rebuild @prisma/engines

Type checking (optional)

Node runs your TypeScript without checking it. To check types in your editor or with tsc, add typescript and @types/node as dev dependencies and a tsconfig.json:

tsconfig.json

{
  "compilerOptions": {
    "target": "esnext",
    "module": "nodenext",
    "strict": true,
    "noEmit": true,
    "allowImportingTsExtensions": true,
    "skipLibCheck": true
  }
}

Next, set up the database.