docs(repo): enhance support policy (#1834)

mandarini · web-flow · commit dd0fee1477fe · 2025-11-05T12:11:48.000-03:00
diff --git a/README.md b/README.md
@@ -50,77 +50,58 @@ This monorepo contains the complete suite of Supabase JavaScript SDK:
 | **[@supabase/storage-js](./packages/core/storage-js)**     | File storage SDK                      |
 | **[@supabase/functions-js](./packages/core/functions-js)** | Edge Functions SDK                    |
 
-## Requirements
+## Support Policy
 
-- **Node.js 20 or later** (Node.js 18 support was dropped as of October 31, 2025)
-- For browser support, all modern browsers are supported
+This section outlines the scope of support for various runtime environments in Supabase JavaScript client.
 
-> ⚠️ **Node.js 18 Deprecation Notice**
->
-> Node.js 18 reached end-of-life on April 30, 2025. As announced in [our deprecation notice](https://github.com/orgs/supabase/discussions/37217), support for Node.js 18 was dropped on October 31, 2025.
->
-> If you must use Node.js 18, please use version `2.x.x` of these libraries where `x` is the last version that supported Node.js 18.
+### Node.js
 
-> **💡 Note for Package Users:** If you install and use these packages, **nothing has changed**. Continue installing packages normally:
+We only support Node.js versions that are in **Active LTS** or **Maintenance** status as defined by the [official Node.js release schedule](https://nodejs.org/en/about/previous-releases#release-schedule). This means we support versions that are currently receiving long-term support and critical bug fixes.
+
+When a Node.js version reaches end-of-life and is no longer in Active LTS or Maintenance status, Supabase will drop it in a **minor release**, and **this won't be considered a breaking change**.
+
+> ⚠️ **Node.js 18 Deprecation Notice**
 >
-> ```bash
-> npm install @supabase/supabase-js
-> npm install @supabase/auth-js
-> ```
+> Node.js 18 reached end-of-life on April 30, 2025. As announced in [our deprecation notice](https://github.com/orgs/supabase/discussions/37217), support for Node.js 18 was dropped in version `2.79.0`.
 >
-> The monorepo structure **only affects contributors**. This is how we develop and maintain the code, not how you use it.
+> If you must use Node.js 18, please use version `2.78.0`, which is the last version that supported Node.js 18.
 
-## 🚀 Quick Start
+### Deno
 
-### Installation
+We support Deno versions that are currently receiving active development and security updates. We follow the [official Deno release schedule](https://docs.deno.com/runtime/fundamentals/stability_and_releases/) and only support versions from the `stable` and `lts` release channels.
 
-```bash
-# Clone the repository
-git clone https://github.com/supabase/supabase-js.git
-cd supabase-js
+When a Deno version reaches end-of-life and is no longer receiving security updates, Supabase will drop it in a **minor release**, and **this won't be considered a breaking change**.
 
-# Install dependencies
-npm install
+### Browsers
 
-# Build all packages
-npx nx run-many --target=build --all
+All modern browsers are supported. We support browsers that provide native `fetch` API. For Realtime features, browsers must also support native `WebSocket` API.
 
-```
+### Bun
 
-## 🏗️ Development
+We support Bun runtime environments. Bun provides native fetch support and is compatible with Node.js APIs. Since Bun does not follow a structured release schedule like Node.js or Deno, we support current stable versions of Bun and may drop support for older versions in minor releases without considering it a breaking change.
 
-### Workspace Commands
+### React Native
 
-```bash
-# Build a specific library
-npx nx build auth-js
+We support React Native environments with fetch polyfills provided by the framework. Since React Native does not follow a structured release schedule, we support current stable versions and may drop support for older versions in minor releases without considering it a breaking change.
 
-# Test a specific library
-npx nx test postgrest-js
+### Cloudflare Workers
 
-# Build affected projects (only build what changed)
-npx nx affected --target=build
+We support Cloudflare Workers runtime environments. Cloudflare Workers provides native fetch support. Since Cloudflare Workers does not follow a structured release schedule, we support current stable versions and may drop support for older versions in minor releases without considering it a breaking change.
 
-# Generate dependency graph
-npx nx graph
+### Important Notes
 
-# Format all code
-npx nx format
+- **Experimental features**: Features marked as experimental may be removed or changed without notice
 
-# Check code formatting
-npx nx format:check
-```
-
-### Working with Individual Libraries
+## 🚀 Quick Start
 
-Each library can be developed independently:
+### Installation
 
 ```bash
-# Start development with watch mode
-npx nx build auth-js --watch
-npx nx test auth-js --watch
+npm install @supabase/supabase-js
 ```
 
+Read more in each package's README file.
+
 ## 🤝 Contributing
 
 We welcome contributions! Please see our [Contributing Guide](./CONTRIBUTING.md) for details.
@@ -147,16 +128,6 @@ We welcome contributions! Please see our [Contributing Guide](./CONTRIBUTING.md)
 
 Testing varies per package. See the top-level [TESTING.md](docs/TESTING.md) for an overview and links to package-specific guides.
 
-Quick examples:
-
-```bash
-# Run tests for a specific package
-npx nx test <package-name>
-
-# Run tests with coverage
-npx nx test <package-name> --coverage
-```
-
 ## 📚 Documentation
 
 ### API Documentation
@@ -200,25 +171,6 @@ audited 1 package in 0s
 
 Because provenance attestations are a new capability, security features may evolve over time. Ensure you are using the latest npm CLI to verify attestation signatures reliably. This may require updating npm beyond the version bundled with Node.js.
 
-## 🏛️ Architecture
-
-### Monorepo Structure
-
-```tree
-supabase-js/
-├── packages/
-│   └── core/                  # Published libraries
-│       ├── auth-js/           # Authentication SDK
-│       ├── functions-js/      # Edge Functions SDK
-│       ├── postgrest-js/      # PostgREST database SDK
-│       ├── realtime-js/       # Real-time subscriptions SDK
-│       ├── storage-js/        # File storage SDK
-│       └── supabase-js/       # Main isomorphic SDK
-├── nx.json                    # npx nx workspace configuration
-├── package.json               # Root package.json and workspaces setup
-└── ...
-```
-
 ## 📄 License
 
 This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.
diff --git a/packages/core/supabase-js/README.md b/packages/core/supabase-js/README.md
@@ -30,15 +30,6 @@
 
 </div>
 
-## Requirements
-
-- **Node.js 20 or later** (Node.js 18 support dropped as of October 31, 2025)
-- For browser support, all modern browsers are supported
-
-> ⚠️ **Node.js 18 Deprecation Notice**
->
-> Node.js 18 reached end-of-life on April 30, 2025. As announced in [our deprecation notice](https://github.com/orgs/supabase/discussions/37217), support for Node.js 18 was dropped on October 31, 2025.
-
 ## Usage
 
 First of all, you need to install the library:
@@ -129,19 +120,43 @@ We only support Node.js versions that are in **Active LTS** or **Maintenance** s
 
 When a Node.js version reaches end-of-life and is no longer in Active LTS or Maintenance status, Supabase will drop it in a **minor release**, and **this won't be considered a breaking change**.
 
+> ⚠️ **Node.js 18 Deprecation Notice**
+>
+> Node.js 18 reached end-of-life on April 30, 2025. As announced in [our deprecation notice](https://github.com/orgs/supabase/discussions/37217), support for Node.js 18 was dropped in version `2.79.0`.
+>
+> If you must use Node.js 18, please use version `2.78.0`, which is the last version that supported Node.js 18.
+
 ### Deno
 
 We support Deno versions that are currently receiving active development and security updates. We follow the [official Deno release schedule](https://docs.deno.com/runtime/fundamentals/stability_and_releases/) and only support versions from the `stable` and `lts` release channels.
 
 When a Deno version reaches end-of-life and is no longer receiving security updates, Supabase will drop it in a **minor release**, and **this won't be considered a breaking change**.
 
+### Browsers
+
+All modern browsers are supported. We support browsers that provide native `fetch` API. For Realtime features, browsers must also support native `WebSocket` API.
+
+### Bun
+
+We support Bun runtime environments. Bun provides native fetch support and is compatible with Node.js APIs. Since Bun does not follow a structured release schedule like Node.js or Deno, we support current stable versions of Bun and may drop support for older versions in minor releases without considering it a breaking change.
+
+### React Native
+
+We support React Native environments with fetch polyfills provided by the framework. Since React Native does not follow a structured release schedule, we support current stable versions and may drop support for older versions in minor releases without considering it a breaking change.
+
+### Cloudflare Workers
+
+We support Cloudflare Workers runtime environments. Cloudflare Workers provides native fetch support. Since Cloudflare Workers does not follow a structured release schedule, we support current stable versions and may drop support for older versions in minor releases without considering it a breaking change.
+
 ### Important Notes
 
 - **Experimental features**: Features marked as experimental may be removed or changed without notice
 
-## Development
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guide](../../../CONTRIBUTING.md) for details on how to get started.
 
-This package is part of the [Supabase JavaScript monorepo](https://github.com/supabase/supabase-js). To work on this package:
+For major changes or if you're unsure about something, please open an issue first to discuss your proposed changes.
 
 ### Building
 
@@ -157,12 +172,6 @@ npx nx build supabase-js --watch
 
 There's a complete guide on how to set up your environment for running locally the `supabase-js` integration tests. Please refer to [TESTING.md](./TESTING.md).
 
-### 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.
-
 ## Badges
 
 [![Coverage Status](https://coveralls.io/repos/github/supabase/supabase-js/badge.svg?branch=master)](https://coveralls.io/github/supabase/supabase-js?branch=master)
