\n\n### Quick start\n\nInstall\n\n```bash\nnpm install @supabase/postgrest-js\n```\n\nUsage\n\n```js\nimport { PostgrestClient } from '@supabase/postgrest-js'\n\nconst REST_URL = 'http://localhost:3000'\nconst postgrest = new PostgrestClient(REST_URL)\n```\n\n- [select()](https://supabase.com/docs/reference/javascript/select)\n- [insert()](https://supabase.com/docs/reference/javascript/insert)\n- [update()](https://supabase.com/docs/reference/javascript/update)\n- [delete()](https://supabase.com/docs/reference/javascript/delete)\n\n#### Custom `fetch` implementation\n\n`postgrest-js` uses the [`cross-fetch`](https://www.npmjs.com/package/cross-fetch) library to make HTTP requests, but an alternative `fetch` implementation can be provided as an option. This is most useful in environments where `cross-fetch` is not compatible, for instance Cloudflare Workers:\n\n```js\nimport { PostgrestClient } from '@supabase/postgrest-js'\n\nconst REST_URL = 'http://localhost:3000'\nconst postgrest = new PostgrestClient(REST_URL, {\n fetch: (...args) => fetch(...args),\n})\n```\n\n## Development\n\nThis package is part of the [Supabase JavaScript monorepo](https://github.com/supabase/supabase-js). To work on this package:\n\n### Building\n\n```bash\n# Build (from monorepo root)\nnpx nx build postgrest-js\n\n# Build with watch mode for development\nnpx nx build:watch postgrest-js\n\n# TypeScript type checking\nnpx nx type-check postgrest-js\n\n# Generate documentation\nnpx nx docs postgrest-js\n```\n\n### Testing\n\n**Supabase CLI Required!** The `postgrest-js` tests use the [Supabase CLI](https://supabase.com/docs/guides/local-development/cli/getting-started) to run a local PostgreSQL database and PostgREST server.\n\n#### Quick Start\n\n```bash\n# Run all tests (from monorepo root)\nnpx nx test:ci:postgrest postgrest-js\n```\n\nThis single command automatically:\n\n1. Stops any existing Supabase CLI containers\n2. Starts PostgreSQL database and PostgREST server via Supabase CLI\n3. Resets and seeds the database\n4. Runs all Jest unit tests with coverage\n5. Cleans up containers\n\n#### Individual Test Commands\n\n```bash\n# Run Jest tests with coverage (requires infrastructure running)\nnpx nx test:run postgrest-js\n\n# Run type tests with tstyche\nnpx nx test:types postgrest-js\n\n# Run smoke tests (CommonJS and ESM imports)\nnpx nx test:smoke postgrest-js\n\n# Format code\nnpx nx format postgrest-js\n\n# Check formatting\nnpx nx format:check postgrest-js\n```\n\n#### Test Infrastructure\n\nThe tests use Supabase CLI to spin up:\n\n- **PostgreSQL** - Database with test schema and seed data (port 54322)\n- **PostgREST** - REST API server that the client connects to (port 54321)\n\n```bash\n# Manually manage test infrastructure (from monorepo root)\nnpx nx test:infra postgrest-js # Start containers\nnpx nx test:clean-pre postgrest-js # Stop and remove containers\n```\n\nOr directly via Supabase CLI:\n\n```bash\ncd packages/core/postgrest-js\nnpx supabase --workdir ./test start # Start all services\nnpx supabase --workdir ./test db reset # Reset and seed database\nnpx supabase --workdir ./test stop # Stop all services\n```\n\n#### Regenerating TypeScript Types\n\nWhen the database schema changes, regenerate TypeScript types from the actual database:\n\n```bash\n# From the monorepo root\nnpm run codegen:postgrest\n```\n\nThis command automatically:\n\n1. Cleans up any existing Supabase containers\n2. Starts Supabase (PostgreSQL, PostgREST, and all services)\n3. Generates TypeScript types from the database schema\n4. Post-processes the generated types (updates JSON type definitions)\n5. Formats the generated file with Prettier\n6. Cleans up Supabase containers\n\nThe generated types are written to `test/types.generated.ts`.\n\n#### Test Types Explained\n\n- **Unit Tests** - Jest tests covering all client functionality (`npx nx test:run postgrest-js`)\n- **Type Tests** - Validates TypeScript types using tstyche (`npx nx test:types postgrest-js`)\n- **Smoke Tests** - Basic import/require tests for CommonJS and ESM (`npx nx test:smoke postgrest-js`)\n\n#### Prerequisites\n\n- **Supabase CLI** must be installed ([instructions](https://supabase.com/docs/guides/local-development/cli/getting-started)) or can be used through `npx` (`npx supabase`)\n- **Docker** must be installed and running (Supabase CLI uses Docker under the hood)\n- **Port 54321** - PostgREST API\n- **Port 54322** - PostgreSQL database\n- **Port 54323** - Supabase Studio (used for type generation)\n\n#### PostgREST v12 Backward Compatibility Tests\n\nWe maintain backward compatibility tests for PostgREST v12 (the current Supabase CLI uses v14+). These tests ensure the SDK works correctly for users still running older PostgREST versions.\n\n```bash\n# Run v12 compatibility tests (requires Docker)\nnpx nx test:ci:v12 postgrest-js\n```\n\nThis command:\n\n1. Starts PostgREST v12 + PostgreSQL in Docker (ports 3012/5433)\n2. Runs runtime tests that verify v12-specific behavior\n3. Cleans up containers\n\n**Type-only tests** for v12 compatibility also run as part of the regular type tests:\n\n```bash\nnpx nx test:types postgrest-js # Includes v12-compat.test-d.ts\n```\n\n**Note:** These v12 tests will be removed when v3 ships (sometime in 2026).\n\n### Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](../../../CONTRIBUTING.md) for details on how to get started.\n\nFor major changes or if you're unsure about something, please open an issue first to discuss your proposed changes.\n\n## License\n\nThis repo is licensed under MIT License.","users":{}}
![\"Supabase](\"https://raw.githubusercontent.com/supabase/supabase/master/packages/common/assets/images/logo-preview.jpg\"){kind=logo}
\n