diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 0000000..c619e26
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,21 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+    types: [opened, synchronize, reopened]
+
+jobs:
+  test:
+    name: Run Tests
+    uses: ./.github/workflows/test.yml
+
+  integration-test:
+    name: Run Integration Tests
+    uses: ./.github/workflows/integration-test.yml
+
+  compatibility-test:
+    name: Run Compatibility Tests
+    uses: ./.github/workflows/compatibility.yml
diff --git a/.github/workflows/compatibility.yml b/.github/workflows/compatibility.yml
new file mode 100644
index 0000000..701b1b7
--- /dev/null
+++ b/.github/workflows/compatibility.yml
@@ -0,0 +1,37 @@
+name: Compatibility Tests
+
+on:
+  workflow_call:
+  workflow_dispatch:
+
+jobs:
+  compatibility-test:
+    name: Compatibility Tests
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: ['20', '22']
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: Setup Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Build
+        run: pnpm run build
+
+      - name: Run compatibility tests
+        run: pnpm run test:compatibility
diff --git a/.github/workflows/integration-test.yml b/.github/workflows/integration-test.yml
index f5ede4b..c04fc70 100644
--- a/.github/workflows/integration-test.yml
+++ b/.github/workflows/integration-test.yml
@@ -1,11 +1,8 @@
 name: Integration Tests
 
 on:
-  push:
-    branches: [main]
-  pull_request:
-    branches: [main]
-    types: [opened, synchronize, reopened]
+  workflow_call:
+  workflow_dispatch:
 
 jobs:
   integration-test:
diff --git a/.github/workflows/preview-release.yml b/.github/workflows/preview-release.yml
index 951c061..2617c88 100644
--- a/.github/workflows/preview-release.yml
+++ b/.github/workflows/preview-release.yml
@@ -29,7 +29,7 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: 22
+          node-version: 20
           cache: 'pnpm'
 
       - name: Install dependencies
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 011f4e7..23112e3 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -1,11 +1,8 @@
 name: Test
 
 on:
-  push:
-    branches: [main]
-  pull_request:
-    branches: [main]
-    types: [opened, synchronize, reopened]
+  workflow_call:
+  workflow_dispatch:
 
 jobs:
   test:
diff --git a/.gitignore b/.gitignore
index 11c0d87..3c44f97 100644
--- a/.gitignore
+++ b/.gitignore
@@ -7,6 +7,10 @@ coverage/
 .env.local
 tmp/
 
+# Compatibility test artifacts
+test-compatibility/**/package-lock.json
+test-compatibility/**/node_modules/
+
 CLAUDE.md
 WARP.md
 .claude/
\ No newline at end of file
diff --git a/CHANGELOG.md b/CHANGELOG.md
index bcf5d26..558fac9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,11 +2,10 @@
 
 ## [0.5.1](https://github.com/supabase/iceberg-js/compare/iceberg-js-v0.5.0...iceberg-js-v0.5.1) (2025-11-21)
 
-
 ### Bug Fixes
 
-* format all files ([#11](https://github.com/supabase/iceberg-js/issues/11)) ([f95874b](https://github.com/supabase/iceberg-js/commit/f95874b3b94bb7fff32970ebebbbeb7745263e02))
-* update npm to latest for release ([#10](https://github.com/supabase/iceberg-js/issues/10)) ([7943aca](https://github.com/supabase/iceberg-js/commit/7943acab02005ad5e5be249a201fe2dce810b57b))
+- format all files ([#11](https://github.com/supabase/iceberg-js/issues/11)) ([f95874b](https://github.com/supabase/iceberg-js/commit/f95874b3b94bb7fff32970ebebbbeb7745263e02))
+- update npm to latest for release ([#10](https://github.com/supabase/iceberg-js/issues/10)) ([7943aca](https://github.com/supabase/iceberg-js/commit/7943acab02005ad5e5be249a201fe2dce810b57b))
 
 ## [0.5.0](https://github.com/supabase/iceberg-js/compare/iceberg-js-v0.4.0...iceberg-js-v0.5.0) (2025-11-21)
 
diff --git a/README.md b/README.md
index 4db6e7f..15292d9 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,8 @@
 # iceberg-js
 
+[![CI](https://github.com/supabase/iceberg-js/actions/workflows/ci.yml/badge.svg)](https://github.com/supabase/iceberg-js/actions/workflows/ci.yml)
+[![npm version](https://badge.fury.io/js/iceberg-js.svg)](https://www.npmjs.com/package/iceberg-js)
+
 A small, framework-agnostic JavaScript/TypeScript client for the **Apache Iceberg REST Catalog**.
 
 ## Features
@@ -11,6 +14,28 @@ A small, framework-agnostic JavaScript/TypeScript client for the **Apache Iceber
 - **Universal**: Targets Node 20+ and modern browsers (ES2020)
 - **Catalog-only**: Focused on catalog operations (no data reading/Parquet support in v0.1.0)
 
+## Compatibility
+
+This package is built to work in **all** Node.js and JavaScript environments:
+
+| Environment         | Module System        | Import Method                           | Status                |
+| ------------------- | -------------------- | --------------------------------------- | --------------------- |
+| Node.js ESM         | `"type": "module"`   | `import { ... } from 'iceberg-js'`      | ✅ Fully supported    |
+| Node.js CommonJS    | Default              | `const { ... } = require('iceberg-js')` | ✅ Fully supported    |
+| TypeScript ESM      | `module: "ESNext"`   | `import { ... } from 'iceberg-js'`      | ✅ Full type support  |
+| TypeScript CommonJS | `module: "CommonJS"` | `import { ... } from 'iceberg-js'`      | ✅ Full type support  |
+| Bundlers            | Any                  | Webpack, Vite, esbuild, Rollup, etc.    | ✅ Auto-detected      |
+| Browsers            | ESM                  | `<script type="module">`                | ✅ Modern browsers    |
+| Deno                | ESM                  | `import` from npm:                      | ✅ With npm specifier |
+
+**Package exports:**
+
+- ESM: `dist/index.mjs` with `dist/index.d.ts`
+- CommonJS: `dist/index.cjs` with `dist/index.d.cts`
+- Proper `exports` field for Node.js 12+ module resolution
+
+All scenarios are tested in CI on Node.js 20 and 22.
+
 ## Installation
 
 ```bash
@@ -338,6 +363,9 @@ pnpm test:integration
 # Run integration tests with cleanup (for CI)
 pnpm test:integration:ci
 
+# Run compatibility tests (all module systems)
+pnpm test:compatibility
+
 # Format code
 pnpm run format
 
@@ -359,6 +387,17 @@ npx tsx test/integration/test-local-catalog.ts
 docker compose down -v
 ```
 
+### Compatibility Testing
+
+The `test:compatibility` script verifies the package works correctly in all JavaScript/TypeScript environments:
+
+- **Pure JavaScript ESM** - Projects with `"type": "module"`
+- **Pure JavaScript CommonJS** - Traditional Node.js projects
+- **TypeScript ESM** - TypeScript with `module: "ESNext"`
+- **TypeScript CommonJS** - TypeScript with `module: "CommonJS"`
+
+These tests ensure proper module resolution, type definitions, and runtime behavior across all supported environments. See [test-compatibility/README.md](./test-compatibility/README.md) for more details.
+
 ## License
 
 MIT
diff --git a/eslint.config.ts b/eslint.config.ts
index 931773b..1621008 100644
--- a/eslint.config.ts
+++ b/eslint.config.ts
@@ -7,7 +7,7 @@ import { defineConfig, globalIgnores } from 'eslint/config'
 
 export default defineConfig([
   globalIgnores(['dist/**/*'], 'Ignore Build Directory'),
-  globalIgnores(['CLAUDE.md', 'WARP.md', 'tmp/**/*']),
+  globalIgnores(['CLAUDE.md', 'WARP.md', 'tmp/**/*', 'test-compatibility/**/*']),
   {
     files: ['**/*.{js,mjs,cjs,ts,mts,cts}'],
     plugins: { js },
diff --git a/package.json b/package.json
index e8fd70f..b7d8855 100644
--- a/package.json
+++ b/package.json
@@ -8,9 +8,15 @@
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.mjs",
-      "require": "./dist/index.cjs"
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      },
+      "default": "./dist/index.mjs"
     }
   },
   "files": [
@@ -26,6 +32,7 @@
     "test:watch": "vitest watch",
     "test:integration": "bash scripts/test-integration.sh",
     "test:integration:ci": "bash scripts/test-integration.sh --cleanup",
+    "test:compatibility": "bash test-compatibility/run-all.sh",
     "check": "pnpm lint && pnpm type-check && pnpm test && pnpm build"
   },
   "keywords": [
diff --git a/test-compatibility/README.md b/test-compatibility/README.md
new file mode 100644
index 0000000..6c297ec
--- /dev/null
+++ b/test-compatibility/README.md
@@ -0,0 +1,38 @@
+# Compatibility Tests
+
+This directory contains test projects to verify that `iceberg-js` works in all common Node.js environments.
+
+## Test Scenarios
+
+1. **esm-project/** - Pure JavaScript ESM (`"type": "module"`)
+2. **cjs-project/** - Pure JavaScript CommonJS (no type field)
+3. **ts-esm-project/** - TypeScript with ESM (`module: "ESNext"`)
+4. **ts-cjs-project/** - TypeScript with CommonJS (`module: "CommonJS"`)
+
+## Running Tests
+
+From the root of the `iceberg-js` project:
+
+```bash
+# Build the package first
+pnpm build
+
+# Run all compatibility tests
+bash test-compatibility/run-all.sh
+```
+
+Or test individually:
+
+```bash
+cd test-compatibility/esm-project
+npm install
+npm test
+```
+
+## What Gets Tested
+
+- ✅ Package can be imported/required
+- ✅ Classes and types are available
+- ✅ Instances can be created
+- ✅ TypeScript types resolve correctly
+- ✅ No module resolution errors
diff --git a/test-compatibility/cjs-project/index.js b/test-compatibility/cjs-project/index.js
new file mode 100644
index 0000000..9bd230f
--- /dev/null
+++ b/test-compatibility/cjs-project/index.js
@@ -0,0 +1,19 @@
+// CommonJS Test - tests that the package works in CJS mode
+const { IcebergRestCatalog } = require('iceberg-js')
+
+console.log('✅ CJS: Successfully required IcebergRestCatalog')
+console.log('✅ CJS: Type:', typeof IcebergRestCatalog)
+console.log('✅ CJS: Constructor name:', IcebergRestCatalog.name)
+
+// Test instantiation
+try {
+  const catalog = new IcebergRestCatalog({
+    baseUrl: 'http://localhost:8181',
+    auth: { type: 'none' },
+  })
+  console.log('✅ CJS: Successfully created catalog instance')
+  console.log('✅ CJS: ALL TESTS PASSED!')
+} catch (error) {
+  console.error('❌ CJS: Failed to create instance:', error)
+  process.exit(1)
+}
diff --git a/test-compatibility/cjs-project/package.json b/test-compatibility/cjs-project/package.json
new file mode 100644
index 0000000..8a2d9a6
--- /dev/null
+++ b/test-compatibility/cjs-project/package.json
@@ -0,0 +1,11 @@
+{
+  "name": "test-cjs-compatibility",
+  "version": "1.0.0",
+  "private": true,
+  "scripts": {
+    "test": "node index.js"
+  },
+  "dependencies": {
+    "iceberg-js": "file:../.."
+  }
+}
diff --git a/test-compatibility/esm-project/index.js b/test-compatibility/esm-project/index.js
new file mode 100644
index 0000000..b9d7dc7
--- /dev/null
+++ b/test-compatibility/esm-project/index.js
@@ -0,0 +1,19 @@
+// ESM Test - tests that the package works in ESM mode
+import { IcebergRestCatalog } from 'iceberg-js'
+
+console.log('✅ ESM: Successfully imported IcebergRestCatalog')
+console.log('✅ ESM: Type:', typeof IcebergRestCatalog)
+console.log('✅ ESM: Constructor name:', IcebergRestCatalog.name)
+
+// Test instantiation
+try {
+  const catalog = new IcebergRestCatalog({
+    baseUrl: 'http://localhost:8181',
+    auth: { type: 'none' },
+  })
+  console.log('✅ ESM: Successfully created catalog instance')
+  console.log('✅ ESM: ALL TESTS PASSED!')
+} catch (error) {
+  console.error('❌ ESM: Failed to create instance:', error)
+  process.exit(1)
+}
diff --git a/test-compatibility/esm-project/package.json b/test-compatibility/esm-project/package.json
new file mode 100644
index 0000000..a310188
--- /dev/null
+++ b/test-compatibility/esm-project/package.json
@@ -0,0 +1,12 @@
+{
+  "name": "test-esm-compatibility",
+  "version": "1.0.0",
+  "type": "module",
+  "private": true,
+  "scripts": {
+    "test": "node index.js"
+  },
+  "dependencies": {
+    "iceberg-js": "file:../.."
+  }
+}
diff --git a/test-compatibility/run-all.sh b/test-compatibility/run-all.sh
new file mode 100755
index 0000000..950591e
--- /dev/null
+++ b/test-compatibility/run-all.sh
@@ -0,0 +1,64 @@
+#!/bin/bash
+set -e
+
+# Get the directory where the script is located
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+echo "🧪 Running compatibility tests for iceberg-js..."
+echo ""
+
+# Make sure the package is built
+if [ ! -d "$ROOT_DIR/dist" ]; then
+  echo "❌ Error: dist/ folder not found. Run 'pnpm build' first."
+  exit 1
+fi
+
+# Change to test-compatibility directory
+cd "$SCRIPT_DIR"
+
+# Test ESM
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "🔵 Testing ESM (Pure JavaScript)"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+cd esm-project
+npm install ../..
+npm test
+cd ..
+echo ""
+
+# Test CJS
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "🟢 Testing CommonJS (Pure JavaScript)"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+cd cjs-project
+npm install ../..
+npm test
+cd ..
+echo ""
+
+# Test TS ESM
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "🔷 Testing TypeScript ESM"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+cd ts-esm-project
+npm install
+npm install ../..
+npm test
+cd ..
+echo ""
+
+# Test TS CJS
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "🟩 Testing TypeScript CommonJS"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+cd ts-cjs-project
+npm install
+npm install ../..
+npm test
+cd ..
+echo ""
+
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "✨ ALL COMPATIBILITY TESTS PASSED!"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
diff --git a/test-compatibility/ts-cjs-project/index.ts b/test-compatibility/ts-cjs-project/index.ts
new file mode 100644
index 0000000..e5792ea
--- /dev/null
+++ b/test-compatibility/ts-cjs-project/index.ts
@@ -0,0 +1,21 @@
+// TypeScript CJS Test - tests that the package works in TS CJS mode with types
+import { IcebergRestCatalog, type IcebergConfig } from 'iceberg-js'
+
+console.log('✅ TS-CJS: Successfully imported IcebergRestCatalog and types')
+
+// Test type checking
+const config: IcebergConfig = {
+  baseUrl: 'http://localhost:8181',
+  auth: { type: 'none' },
+}
+
+// Test instantiation
+try {
+  const catalog = new IcebergRestCatalog(config)
+  console.log('✅ TS-CJS: Successfully created catalog instance')
+  console.log('✅ TS-CJS: Type inference working:', typeof catalog.listNamespaces === 'function')
+  console.log('✅ TS-CJS: ALL TESTS PASSED!')
+} catch (error) {
+  console.error('❌ TS-CJS: Failed:', error)
+  process.exit(1)
+}
diff --git a/test-compatibility/ts-cjs-project/package.json b/test-compatibility/ts-cjs-project/package.json
new file mode 100644
index 0000000..100d95d
--- /dev/null
+++ b/test-compatibility/ts-cjs-project/package.json
@@ -0,0 +1,15 @@
+{
+  "name": "test-ts-cjs-compatibility",
+  "version": "1.0.0",
+  "private": true,
+  "scripts": {
+    "test": "tsx index.ts"
+  },
+  "devDependencies": {
+    "tsx": "^4.19.0",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "iceberg-js": "file:../.."
+  }
+}
diff --git a/test-compatibility/ts-cjs-project/tsconfig.json b/test-compatibility/ts-cjs-project/tsconfig.json
new file mode 100644
index 0000000..f5bf2c5
--- /dev/null
+++ b/test-compatibility/ts-cjs-project/tsconfig.json
@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "CommonJS",
+    "moduleResolution": "node",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true
+  }
+}
diff --git a/test-compatibility/ts-esm-project/index.ts b/test-compatibility/ts-esm-project/index.ts
new file mode 100644
index 0000000..e27ebad
--- /dev/null
+++ b/test-compatibility/ts-esm-project/index.ts
@@ -0,0 +1,21 @@
+// TypeScript ESM Test - tests that the package works in TS ESM mode with types
+import { IcebergRestCatalog, type IcebergConfig } from 'iceberg-js'
+
+console.log('✅ TS-ESM: Successfully imported IcebergRestCatalog and types')
+
+// Test type checking
+const config: IcebergConfig = {
+  baseUrl: 'http://localhost:8181',
+  auth: { type: 'none' },
+}
+
+// Test instantiation
+try {
+  const catalog = new IcebergRestCatalog(config)
+  console.log('✅ TS-ESM: Successfully created catalog instance')
+  console.log('✅ TS-ESM: Type inference working:', typeof catalog.listNamespaces === 'function')
+  console.log('✅ TS-ESM: ALL TESTS PASSED!')
+} catch (error) {
+  console.error('❌ TS-ESM: Failed:', error)
+  process.exit(1)
+}
diff --git a/test-compatibility/ts-esm-project/package.json b/test-compatibility/ts-esm-project/package.json
new file mode 100644
index 0000000..920683f
--- /dev/null
+++ b/test-compatibility/ts-esm-project/package.json
@@ -0,0 +1,16 @@
+{
+  "name": "test-ts-esm-compatibility",
+  "version": "1.0.0",
+  "type": "module",
+  "private": true,
+  "scripts": {
+    "test": "tsx index.ts"
+  },
+  "devDependencies": {
+    "tsx": "^4.19.0",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "iceberg-js": "file:../.."
+  }
+}
diff --git a/test-compatibility/ts-esm-project/tsconfig.json b/test-compatibility/ts-esm-project/tsconfig.json
new file mode 100644
index 0000000..f190f73
--- /dev/null
+++ b/test-compatibility/ts-esm-project/tsconfig.json
@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true
+  }
+}
diff --git a/test/catalog/tables.test.ts b/test/catalog/tables.test.ts
index bba7628..a1d11d1 100644
--- a/test/catalog/tables.test.ts
+++ b/test/catalog/tables.test.ts
@@ -352,7 +352,7 @@ describe('TableOperations', () => {
       expect(mockClient.request).toHaveBeenCalledWith({
         method: 'DELETE',
         path: '/v1/namespaces/analytics/tables/events',
-        query: {purgeRequested: "false"}
+        query: { purgeRequested: 'false' },
       })
     })
 
@@ -365,12 +365,12 @@ describe('TableOperations', () => {
       })
 
       const ops = new TableOperations(mockClient, '/v1')
-      await ops.dropTable({ namespace: ['analytics'], name: 'events' }, {purge: true})
+      await ops.dropTable({ namespace: ['analytics'], name: 'events' }, { purge: true })
 
       expect(mockClient.request).toHaveBeenCalledWith({
         method: 'DELETE',
         path: '/v1/namespaces/analytics/tables/events',
-        query: {purgeRequested: "true"}
+        query: { purgeRequested: 'true' },
       })
     })
 
@@ -388,7 +388,7 @@ describe('TableOperations', () => {
       expect(mockClient.request).toHaveBeenCalledWith({
         method: 'DELETE',
         path: '/v1/namespaces/analytics\x1Fprod/tables/events',
-        query: {purgeRequested: "false"}
+        query: { purgeRequested: 'false' },
       })
     })
   })
diff --git a/tsup.config.ts b/tsup.config.ts
index fb25a23..27aa92d 100644
--- a/tsup.config.ts
+++ b/tsup.config.ts
@@ -9,4 +9,9 @@ export default defineConfig({
   target: 'es2020',
   minify: false,
   treeshake: true,
+  outExtension({ format }) {
+    return {
+      js: format === 'esm' ? '.mjs' : '.cjs',
+    }
+  },
 })