No native modules, pod install, or Android linking steps are required. The package targets Node.js 18+ (ESM and CJS both supported via the package exports map).

Project setup

1. Copy the source/ directory into your project, e.g. src/weaviate/.

2. In tsconfig.json ensure:

{
  "compilerOptions": {
    "module": "Node16",
    "moduleResolution": "Node16",
    "target": "ES2020",
    "esModuleInterop": true,
    "strict": true
  }
}

3. If you use path aliases, add a mapping:

{
  "compilerOptions": {
    "paths": {
      "weaviate-client": ["./src/weaviate/index.ts"]
    }
  }
}

4. Set environment variables for your Weaviate instance:

WEAVIATE_HOST=localhost
WEAVIATE_PORT=8080
WEAVIATE_GRPC_PORT=50051
WEAVIATE_API_KEY=your-api-key   # optional

5. Import and connect (see examples below). No build-time code generation is required; the protobuf stubs are pre-generated in proto/.

Public API

ConnectToLocalOptions

import { ConnectToLocalOptions } from './connection/helpers.js';

type ConnectToLocalOptions = {
  host?: string;
  port?: number;
  grpcPort?: number;
  headers?: Headers;
  authCredentials?: AuthCredentials;
};

Passed to connectToLocal() to point the client at a self-hosted instance. Use this during local development or when running Weaviate in Docker.

ApiKey / AuthCredentials

import { ApiKey, AuthCredentials } from './connection/auth.js';

const creds: AuthCredentials = new ApiKey('your-api-key');

ApiKey is the simplest credential type. AuthCredentials is the union of ApiKey, AuthAccessTokenCredentials, AuthClientCredentials, and AuthUserPasswordCredentials. Pass any of them as authCredentials in a connect helper.

Aliases (alias module)

import alias, { Aliases } from './alias/index.js';

interface Aliases {
  create: (args: { collection: string; alias: string }) => Promise<void>;
  listAll: (opts?: { collection?: string })        => Promise<Alias[] | undefined>;
  get:     (alias: string)                          => Promise<Alias>;
  update:  (args: { alias: string; newTargetCollection: string }) => Promise<void>;
  delete:  (alias: string)                          => Promise<void>;
}

Use when you need to expose a stable name that can be hot-swapped to a new collection without changing downstream consumers.

Backup (backup module)

import backup, { Backend, BackupStatus } from './backup/index.js';

type Backend      = 'filesystem' | 's3' | 'gcs' | 'azure';
type BackupStatus = 'STARTED' | 'TRANSFERRING' | 'TRANSFERRED' | 'SUCCESS' | 'FAILED';

interface Backup {
  creator:           () => BackupCreator;
  createStatusGetter:() => BackupCreateStatusGetter;
  restorer:          () => BackupRestorer;
  restoreStatusGetter:() => BackupRestoreStatusGetter;
}

Use creator() to kick off a backup and createStatusGetter() to poll until SUCCESS or FAILED.

Batch (batch module)

import batch, { DeleteOutput, DeleteResultStatus } from './batch/index.js';

interface Batch {
  objectsBatcher:        () => ObjectsBatcher;
  objectsBatchDeleter:   () => ObjectsBatchDeleter;
  referencesBatcher:     () => ReferencesBatcher;
  referencePayloadBuilder:() => ReferencePayloadBuilder;
}

Use for high-throughput object ingestion or deletion to avoid per-request overhead.

Working examples

Scenario - Connect and manage aliases

Connect to a local Weaviate instance and swap a collection alias atomically.

import weaviate from 'weaviate-client';

async function swapAlias() {
  const client = await weaviate.connectToLocal({
    host: process.env.WEAVIATE_HOST ?? 'localhost',
    port: Number(process.env.WEAVIATE_PORT ?? 8080),
    grpcPort: Number(process.env.WEAVIATE_GRPC_PORT ?? 50051),
  });

  const aliases = client.alias;

  // Create an alias pointing at the current live collection
  await aliases.create({ collection: 'ArticlesV1', alias: 'Articles' });

  // Later: redirect the alias to a freshly built collection
  await aliases.update({ alias: 'Articles', newTargetCollection: 'ArticlesV2' });

  // Inspect all aliases
  const all = await aliases.listAll();
  console.log(all);

  await client.close();
}

swapAlias().catch(console.error);

Scenario - Trigger and poll a backup

Kick off an S3 backup and poll until completion.

import weaviate from 'weaviate-client';
import { BackupStatus } from './backup/index.js';

async function runBackup() {
  const client = await weaviate.connectToLocal();
  const bkp = client.backup;

  // Start backup
  const creator = bkp.creator();
  await creator
    .withBackend('s3')
    .withBackupId('nightly-2024-01-01')
    .withIncludeClassNames(['Articles', 'Authors'])
    .do();

  // Poll status
  const statusGetter = bkp.createStatusGetter();
  let status: BackupStatus = 'STARTED';

  while (status !== 'SUCCESS' && status !== 'FAILED') {
    await new Promise((r) => setTimeout(r, 2000));
    const result = await statusGetter
      .withBackend('s3')
      .withBackupId('nightly-2024-01-01')
      .do();
    status = result.status as BackupStatus;
    console.log('Backup status:', status);
  }

  await client.close();
}

runBackup().catch(console.error);

Scenario - Bulk object ingestion with ApiKey auth

Connect to Weaviate Cloud and insert objects in batch.

import weaviate from 'weaviate-client';
import { ApiKey } from './connection/auth.js';

async function bulkIngest() {
  const client = await weaviate.connectToWeaviateCloud(
    'https://my-cluster.weaviate.network',
    {
      authCredentials: new ApiKey(process.env.WEAVIATE_API_KEY ?? ''),
    }
  );

  const batcher = client.batch.objectsBatcher();

  for (let i = 0; i < 500; i++) {
    batcher.withObject({
      class: 'Article',
      properties: { title: `Article ${i}`, body: `Content ${i}` },
    });
  }

  const result = await batcher.do();
  console.log(`Inserted ${result.length} objects`);

  await client.close();
}

bulkIngest().catch(console.error);

File walkthrough

• alias/ - Implements Aliases interface: create/list/get/update/delete alias operations over REST.
• backup/ - BackupCreator and BackupRestorer builders plus status-polling getters for backup lifecycle.
• batch/ - ObjectsBatcher, ObjectsBatchDeleter, ReferencesBatcher, and ReferencePayloadBuilder for bulk writes.
• c11y/ - Contextionary API: ConceptsGetter fetches word vectors; ExtensionCreator adds custom concepts.
• classifications/ - Scheduler triggers kNN/zero-shot classification; Getter retrieves job status.
• cluster/ - NodesStatusGetter returns per-node shard and object statistics.
• collections/ - The richest module: query, aggregate, configure, data CRUD, filters, generate (RAG), iterator, references, serialize/deserialize, sort, tenants, and vector management.
• connection/ - HTTP and gRPC connection classes, all auth credential types, and the connectTo* helper factories.
• data/ - ConsistencyLevel enum (ONE, QUORUM, ALL) for replication-aware reads/writes.
• graphql/ - Fluent builders for Get, Aggregate, Explore, and Raw GraphQL queries.
• groups/ - Group CRUD operations.
• grpc/ - Low-level gRPC channel setup and interceptors.
• misc/ - LiveChecker, ReadyChecker, and OpenidConfigurationGetter for health and OIDC discovery.
• openapi/ - Auto-generated TypeScript types matching the Weaviate OpenAPI spec.
• proto/ - Pre-generated protobuf/gRPC stubs; do not hand-edit.
• roles/ - Role and permission management with a permissions helper for constructing permission objects.
• schema/ - Legacy v1 schema CRUD (class, property, shard management).
• users/ - User creation, deletion, and role assignment.
• utils/ - DbVersion detection, BeaconPath construction, and other internal helpers.
• v2/ - Thin wrapper exposing the older v2-style client for backwards compatibility.
• validation/ - Common input guards used across builders.
• errors.ts - Typed error classes (WeaviateError, WeaviateInvalidInputError, etc.).
• index.ts - Aggregates and re-exports everything; the single import surface for consumers.
• version.ts - Exports the CLIENT_VERSION string constant.

Common pitfalls and fixes

• ESM .js extensions in imports: The source uses import ... from './foo.js' even in .ts files. If your bundler or ts-node complains, set "moduleResolution": "Node16" or "Bundler" in tsconfig.json.
• gRPC port not set: Forgetting grpcPort causes silent fallback to HTTP-only mode; always pass grpcPort: 50051 (or your configured port) explicitly in ConnectToLocalOptions.
• ApiKey vs OIDC: Passing a plain string instead of new ApiKey(...) to authCredentials will throw at runtime; always construct the credential object.
• connectToWeaviateCloud URL format: The URL must include the scheme (https://). Omitting it causes a malformed-URL error in the connection layer.
• Backup backend credentials: BackupCreator does not accept cloud credentials directly; configure the backend credentials in your Weaviate server's environment variables (BACKUP_S3_BUCKET, etc.).
• Node.js version: The gRPC transport (nice-grpc) requires Node.js 18+. Running on Node 16 will cause ERR_UNSUPPORTED_ESM_URL_SCHEME or missing fetch errors.

Vibe-coding prompt template

I have dropped the Weaviate TypeScript client source into `src/weaviate/` in my project.
The USAGE.md for this block is at `src/weaviate/USAGE.md`.
The upstream package is `user@example.com`.

Please integrate the client into my project step by step:

1. Read `src/weaviate/USAGE.md` and `src/weaviate/index.ts` to understand available exports.
2. Install all required npm dependencies listed in USAGE.md § "Required dependencies".
3. Update `tsconfig.json` as described in USAGE.md § "Project setup".
4. Create `src/db.ts` that connects to Weaviate using `connectToLocal()` (or `connectToWeaviateCloud()` if I am targeting WCD) and exports a singleton `client`.
5. Wire the `client.alias`, `client.backup`, and `client.batch` APIs into my existing service layer, following the patterns in USAGE.md § "Working examples".
6. Do not invent any exports. Only use symbols documented in USAGE.md § "Public API" and visible in `src/weaviate/index.ts`.
7. Show the final file diff for each changed file.

License and credit

The upstream project is licensed under the BSD 3-Clause License (see source/LICENSE if present, or the GitHub repository). This block is derived from user@example.com published by Weaviate B.V.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.