Today we are releasing iceberg-js, a minimal, vendor-agnostic JavaScript client for the Apache Iceberg REST Catalog API.

Apache Iceberg is becoming the standard for large-scale analytics workloads. But until now, JavaScript and TypeScript developers have lacked a simple way to interact with Iceberg REST Catalogs.

‍

Why we built this

‍

We recently launched Analytics Buckets in the Supabase Dashboard. This feature lets you create and manage Iceberg tables directly from the Supabase UI. To power this experience, we needed a JavaScript library that could talk to Iceberg REST Catalogs.

We looked around and did not find what we needed. Most Iceberg tooling is built for JVM languages like Java and Scala. The JavaScript ecosystem had nothing lightweight and focused. So we built iceberg-js.

We care about supporting open-source tools and communities, and creating developer-friendly libraries is one of the ways we contribute.

‍

Testing

We recently launched Analytics Buckets in the Supabase Dashboard. This feature lets you create and manage Iceberg tables directly from the Supabase UI. To power this experience, we needed a JavaScript library that could talk to Iceberg REST Catalogs.

We looked around and did not find what we needed. Most Iceberg tooling is built for JVM languages like Java and Scala. The JavaScript ecosystem had nothing lightweight and focused. So we built iceberg-js.

We care about supporting open-source tools and communities, and creating developer-friendly libraries is one of the ways we contribute.

‍

What it does

‍

iceberg-js is a thin HTTP wrapper that mirrors the official Iceberg REST API. It provides a 1:1 mapping to the API, making it easy to manage namespaces and tables from any JavaScript or TypeScript environment.

The library is designed around a few core principles:

First, it is generic. It works with any Iceberg REST Catalog implementation. It is not tied to any specific vendor.

Second, it is minimal. There is no engine-specific logic and no heavy dependencies. It uses the native fetch API with support for custom implementations.

Third, it is type-safe. It provides full TypeScript support with strongly-typed request and response models.

‍

What it does not do

‍

We were deliberate about what iceberg-js should not do. Keeping the scope narrow is what makes the library maintainable.

• iceberg-js does not support data operations. It cannot read or write Parquet files. For that, use a query engine like DuckDB, Spark, or Trino.
• It does not support query execution. It is purely a catalog management tool.
• It does not include engine-specific integrations. No Spark, Flink, or other engine code.
• It does not support advanced features like branching, tagging, or time travel queries beyond basic metadata operations.

These boundaries exist on purpose. For data operations, pair iceberg-js with a query engine that supports Iceberg.