Getting Started

Prerequisites

Node.js v24+
Docker (for local Typesense) or a Typesense Cloud account

Create a Project

Run the interactive setup:


npx @tsproxy/cli init

The CLI will ask:

What to set up — Backend, Frontend, or Both
How you run Typesense — Docker (local), Typesense Cloud, or Self-hosted
Persistent queue — Redis for BullMQ (optional)
Frontend framework — React or Vanilla JS

This generates:

tsproxy.config.ts — proxy configuration
docker-compose.yml — Typesense + Redis (if Docker selected)
.env — connection details
Installs the right @tsproxy/* packages

Start Infrastructure

If you chose Docker:


docker compose up -d

Start the Proxy


npx tsproxy dev

The proxy starts on http://localhost:3000 with:

Search API at /api/search
Ingest API at /api/ingest/*
Health check at /api/health
API docs at /api/docs

Create Collections

Define your collections in tsproxy.config.ts:


import { defineConfig } from "@tsproxy/api";
 
export default defineConfig({
  typesense: {
    host: "localhost",
    port: 8108,
    apiKey: process.env.TYPESENSE_API_KEY || "your-key",
  },
  server: {
    port: 3000,
    apiKey: process.env.PROXY_API_KEY || "your-ingest-secret",
  },
  collections: {
    products: {
      fields: {
        name: { type: "string", searchable: true },
        description: { type: "string", searchable: true, optional: true },
        price: { type: "float", sortable: true },
        category: { type: "string", facet: true },
        brand: { type: "string", facet: true },
      },
    },
  },
});

Then sync the schema to Typesense:


npx tsproxy migrate --apply

Seed Data

Create a products.json file with your data:


[
  { "id": "1", "name": "Wireless Mouse", "price": 39.99, "category": "Electronics", "brand": "KeyCraft" },
  { "id": "2", "name": "Yoga Mat", "price": 29.99, "category": "Fitness", "brand": "ZenFlow" }
]

Seed via the ingest API (applies computed fields, uses the queue):


npx tsproxy seed products.json --collection products

Add Search to Your App

React


npm install @tsproxy/js @tsproxy/react react-instantsearch


import { SearchProvider, SearchBox, Hits, RefinementList } from "@tsproxy/react";
import { Configure } from "react-instantsearch";
 
export default function SearchPage() {
  return (
    <SearchProvider serverUrl="http://localhost:3000" indexName="products">
      <Configure hitsPerPage={12} />
      <SearchBox placeholder="Search..." />
      <RefinementList attribute="category" />
      <Hits hitComponent={({ hit }) => <div>{hit.name}</div>} />
    </SearchProvider>
  );
}

Vanilla JS


npm install @tsproxy/js


import { createSearchClient } from "@tsproxy/js";
 
const client = createSearchClient({ url: "http://localhost:3000" });
const results = await client.search([
  { indexName: "products", params: { query: "mouse", hitsPerPage: 10 } },
]);

Check Health


npx tsproxy health


  ✓ Proxy        ok
  ✓ Typesense    ok  http://localhost:8108
  ✓ Redis        ok  localhost:6379

  Status: healthy

Environment Variables

All settings from tsproxy.config.ts can be overridden via env vars:

Variable	Default	Description
`TYPESENSE_HOST`	`localhost`	Typesense host
`TYPESENSE_PORT`	`8108`	Typesense port
`TYPESENSE_API_KEY`	—	Typesense API key (required)
`PROXY_PORT`	`3000`	Proxy server port
`PROXY_API_KEY`	—	API key for ingest endpoints
`REDIS_HOST`	—	Redis host (enables BullMQ queue)
`REDIS_PORT`	`6379`	Redis port
`CACHE_TTL`	`60`	Cache TTL in seconds
`CACHE_MAX_SIZE`	`1000`	Max cached entries
`RATE_LIMIT_SEARCH`	`100`	Search requests/min per IP
`RATE_LIMIT_INGEST`	`30`	Ingest requests/min per IP