fcakyon/claude-codex-settings / plugins/supabase-skills/skills/supabase-js
supabase-js
VerifiedThis skill should be used when user asks to "use supabase-js", "query Supabase database", "supabase auth", "supabase storage", "supabase realtime", "supabase edge functions", or works with the @supabase/supabase-js JavaScript/TypeScript SDK.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.3 KB |
| references/auth-js/README.md | markdown | 6.5 KB |
| references/functions-js/README.md | markdown | 4.8 KB |
| references/overview.md | markdown | 9.2 KB |
| references/postgrest-js/README.md | markdown | 6.9 KB |
| references/realtime-js/README.mdexecutable | script | 14.8 KB |
| references/storage-js/README.md | markdown | 35.7 KB |
| references/supabase-js/README.md | markdown | 11.7 KB |
references/postgrest-js/README.md
View on GitHub<br />
<p align="center">
<a href="https://supabase.io">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/supabase/supabase/master/packages/common/assets/images/supabase-logo-wordmark--dark.svg">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/supabase/supabase/master/packages/common/assets/images/supabase-logo-wordmark--light.svg">
<img alt="Supabase Logo" width="300" src="https://raw.githubusercontent.com/supabase/supabase/master/packages/common/assets/images/logo-preview.jpg">
</picture>
</a>
<h1 align="center">Supabase PostgREST JS SDK</h1>
<h3 align="center">Isomorphic JavaScript SDK for <a href="https://postgrest.org">PostgREST</a> with an ORM-like interface.</h3>
<p align="center">
<a href="https://supabase.com/docs/guides/database">Guides</a>
·
<a href="https://supabase.com/docs/reference/javascript/select">Reference Docs</a>
·
<a href="https://supabase.github.io/supabase-js/postgrest-js/v2/spec.json">TypeDoc</a>
</p>
</p>
<div align="center">
[](https://github.com/supabase/supabase-js/actions?query=branch%3Amaster)
[](https://www.npmjs.com/package/@supabase/postgrest-js)
[](#license)
[](https://pkg.pr.new/~/supabase/postgrest-js)
</div>
### Quick start
Install
```bash
npm install @supabase/postgrest-js
```
Usage
```js
import { PostgrestClient } from '@supabase/postgrest-js'
const REST_URL = 'http://localhost:3000'
const postgrest = new PostgrestClient(REST_URL)
```
- [select()](https://supabase.com/docs/reference/javascript/select)
- [insert()](https://supabase.com/docs/reference/javascript/insert)
- [update()](https://supabase.com/docs/reference/javascript/update)
- [delete()](https://supabase.com/docs/reference/javascript/delete)
#### Custom `fetch` implementation
`postgrest-js` uses the runtime's global `fetch` to make HTTP requests, but an alternative `fetch` implementation can be provided as an option. This is useful in environments where the global `fetch` is unavailable or where you want to customize request behavior:
```js
import { PostgrestClient } from '@supabase/postgrest-js'
const REST_URL = 'http://localhost:3000'
const postgrest = new PostgrestClient(REST_URL, {
fetch: (...args) => fetch(...args),
})
```
## Development
This package is part of the [Supabase JavaScript monorepo](https://github.com/supabase/supabase-js). To work on this package:
### Building
```bash
# Build (from monorepo root)
pnpm nx build postgrest-js
# Build with watch mode for development
pnpm nx build:watch postgrest-js
# TypeScript type checking
pnpm nx type-check postgrest-js
# Generate documentation
pnpm nx docs postgrest-js
```
### Testing
**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.
#### Quick Start
```bash
# Run all tests (from monorepo root)
pnpm nx test:ci:postgrest postgrest-js
```
This single command automatically:
1. Stops any existing Supabase CLI containers
2. Starts PostgreSQL database and PostgREST server via Supabase CLI
3. Resets and seeds the database
4. Runs all Jest unit tests with coverage
5. Cleans up containers
#### Individual Test Commands
```bash
# Run Jest tests with coverage (requires infrastructure running)
pnpm nx test:run postgrest-js
# Run type tests with tstyche
pnpm nx test:types postgrest-js
# Run smoke tests (CommonJS and ESM imports)
pnpm nx test:smoke postgrest-js
# Format code
pnpm nx format postgrest-js
# Check formatting
pnpm nx format:check postgrest-js
```
#### Test Infrastructure
The tests use Supabase CLI to spin up:
- **PostgreSQL** - Database with test schema and seed data (port 54322)
- **PostgREST** - REST API server that the client connects to (port 54321)
```bash
# Manually manage test infrastructure (from monorepo root)
pnpm nx test:infra postgrest-js # Start containers
pnpm nx test:clean-pre postgrest-js # Stop and remove containers
```
Or directly via Supabase CLI:
```bash
cd packages/core/postgrest-js
npx supabase --workdir ./test start # Start all services
npx supabase --workdir ./test db reset # Reset and seed database
npx supabase --workdir ./test stop # Stop all services
```
#### Regenerating TypeScript Types
When the database schema changes, regenerate TypeScript types from the actual database:
```bash
# From the monorepo root
pnpm run codegen:postgrest
```
This command automatically:
1. Cleans up any existing Supabase containers
2. Starts Supabase (PostgreSQL, PostgREST, and all services)
3. Generates TypeScript types from the database schema
4. Post-processes the generated types (updates JSON type definitions)
5. Formats the generated file with Prettier
6. Cleans up Supabase containers
The generated types are written to `test/types.generated.ts`.
#### Test Types Explained
- **Unit Tests** - Jest tests covering all client functionality (`pnpm nx test:run postgrest-js`)
- **Type Tests** - Validates TypeScript types using tstyche (`pnpm nx test:types postgrest-js`)
- **Smoke Tests** - Basic import/require tests for CommonJS and ESM (`pnpm nx test:smoke postgrest-js`)
#### Prerequisites
- **Supabase CLI** must be installed ([instructions](https://supabase.com/docs/guides/local-development/cli/getting-started)) or can be used through `npx` (`npx supabase`)
- **Docker** must be installed and running (Supabase CLI uses Docker under the hood)
- **Port 54321** - PostgREST API
- **Port 54322** - PostgreSQL database
- **Port 54323** - Supabase Studio (used for type generation)
#### PostgREST v12 Backward Compatibility Tests
We 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.
```bash
# Run v12 compatibility tests (requires Docker)
pnpm nx test:ci:v12 postgrest-js
```
This command:
1. Starts PostgREST v12 + PostgreSQL in Docker (ports 3012/5433)
2. Runs runtime tests that verify v12-specific behavior
3. Cleans up containers
**Type-only tests** for v12 compatibility also run as part of the regular type tests:
```bash
pnpm nx test:types postgrest-js # Includes v12-compat.test-d.ts
```
**Note:** These v12 tests will be removed when v3 ships (sometime in 2026).
### Contributing
We welcome contributions! Please see our [Contributing Guide](../../../CONTRIBUTING.md) for details on how to get started.
For major changes or if you're unsure about something, please open an issue first to discuss your proposed changes.
## License
This repo is licensed under MIT License.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |