From 3a619c0381032a5d76c582b47ea79280c89966cd Mon Sep 17 00:00:00 2001 From: Katerina Skroumpelou Date: Thu, 2 Oct 2025 11:56:18 +0300 Subject: [PATCH 1/4] chore(repo): change main to master --- .github/ISSUE_TEMPLATE/bug_report.yml | 2 +- .github/ISSUE_TEMPLATE/feature_request.yml | 2 +- .github/PULL_REQUEST_TEMPLATE.md | 2 +- .github/workflows/main-ci-release.yml | 9 ++++----- CLAUDE.md | 17 ++++++----------- CONTRIBUTING.md | 12 ++++++------ README.md | 4 ++++ WARP.md | 20 ++++++++++---------- docs/MIGRATION.md | 4 ++-- docs/RELEASE.md | 14 +++++++------- nx.json | 1 + packages/core/auth-js/README.md | 2 +- packages/core/auth-js/package.json | 2 +- packages/core/functions-js/README.md | 7 +++++++ packages/core/functions-js/package.json | 2 +- packages/core/postgrest-js/README.md | 2 +- packages/core/postgrest-js/package.json | 2 +- packages/core/realtime-js/package.json | 2 +- packages/core/storage-js/README.md | 1 + packages/core/storage-js/package.json | 2 +- packages/core/supabase-js/package.json | 2 +- scripts/release-stable.ts | 2 +- 22 files changed, 60 insertions(+), 53 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index d3915d2de..0a5affe6d 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -91,7 +91,7 @@ body: options: - label: Follow our [Code of Conduct](https://github.com/supabase/.github/blob/main/CODE_OF_CONDUCT.md) required: true - - label: Read the [Contributing Guidelines](https://github.com/supabase/supabase-js/blob/main/CONTRIBUTING.md). + - label: Read the [Contributing Guidelines](https://github.com/supabase/supabase-js/blob/master/CONTRIBUTING.md). required: true - label: Read the [docs](https://supabase.com/docs/reference/javascript/introduction). required: true diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml index 22670e8dd..ece5d7811 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.yml +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -40,7 +40,7 @@ body: options: - label: Follow our [Code of Conduct](https://github.com/supabase/.github/blob/main/CODE_OF_CONDUCT.md) required: true - - label: Read the [Contributing Guidelines](https://github.com/supabase/supabase-js/blob/main/CONTRIBUTING.md). + - label: Read the [Contributing Guidelines](https://github.com/supabase/supabase-js/blob/master/CONTRIBUTING.md). required: true - label: Read the [docs](https://supabase.com/docs/reference/javascript/introduction). required: true diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 903d14b43..2b5c907b6 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -29,7 +29,7 @@ Closes #(issue_number) -- [ ] I have read the [Contributing Guidelines](https://github.com/supabase/supabase-js/blob/main/CONTRIBUTING.md) +- [ ] I have read the [Contributing Guidelines](https://github.com/supabase/supabase-js/blob/master/CONTRIBUTING.md) - [ ] My PR title follows the [conventional commit format](https://www.conventionalcommits.org/): `(): ` - [ ] I have run `npx nx format` to ensure consistent code formatting - [ ] I have added tests for new functionality (if applicable) diff --git a/.github/workflows/main-ci-release.yml b/.github/workflows/main-ci-release.yml index 75febfad0..c3d886524 100644 --- a/.github/workflows/main-ci-release.yml +++ b/.github/workflows/main-ci-release.yml @@ -34,18 +34,17 @@ jobs: contents: read # ========================================== - # CANARY RELEASE (only on main, after all CI passes) + # CANARY RELEASE (only on master, after all CI passes) # ========================================== release-canary: name: Release Canary runs-on: ubuntu-latest needs: [ci-core, ci-supabase-js, ci-auth-js-node18] - # Only run on main branch pushes, and only if all CI jobs succeeded + # Only run on master branch pushes, and only if all CI jobs succeeded if: | - github.ref == 'refs/heads/main' && - github.event_name == 'push' - && + github.ref == 'refs/heads/master' && + github.event_name == 'push' && needs.ci-core.result == 'success' && needs.ci-supabase-js.result == 'success' && needs.ci-auth-js-node18.result == 'success' diff --git a/CLAUDE.md b/CLAUDE.md index 180ba8c9f..b8833ad26 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -57,14 +57,14 @@ Every change must maintain full backward compatibility. The migration itself int Uses automated canary releases with batched stable releases: -- **Canary**: Every commit to main โ†’ prerelease (e.g., `2.80.1-canary.0`) with `canary` dist-tag +- **Canary**: Every commit to master โ†’ prerelease (e.g., `2.80.1-canary.0`) with `canary` dist-tag - **Stable**: Manual promotion of validated canary to `latest` dist-tag - **Fixed Versioning**: All packages share identical version numbers (e.g., all at 2.80.0) - **Version Line**: Continuing with v2.x.x to maintain ecosystem stability **Three Release Workflows:** -1. **Canary** (`.github/workflows/main-ci-release.yml`) - Automated on every main commit +1. **Canary** (`.github/workflows/main-ci-release.yml`) - Automated on every master commit 2. **Stable** (`.github/workflows/release-stable.yml`) - Manual by repository owners 3. **Preview** (`.github/workflows/preview-release.yml`) - PR-based testing via pkg.pr.new @@ -262,7 +262,6 @@ Tests run against multiple environments: - Requires Docker for integration tests (GoTrue + PostgreSQL) - Complex session management logic - Security-critical - extra review care needed -- Default branch: **master** - See [auth-js README](packages/core/auth-js/README.md) for details ### realtime-js @@ -270,28 +269,24 @@ Tests run against multiple environments: - WebSocket-based, timing-sensitive - Mock time in tests when possible - No Docker required (uses mock WebSockets) -- Default branch: **master** - See [realtime-js README](packages/core/realtime-js/README.md) for details ### storage-js - Requires Docker for integration tests (Storage API + PostgreSQL + Kong) - File handling varies by platform -- Default branch: **main** - See [storage-js README](packages/core/storage-js/README.md) for details ### postgrest-js - Pure HTTP client, easiest to test - Requires Docker for integration tests (PostgREST + PostgreSQL) -- Default branch: **master** - See [postgrest-js README](packages/core/postgrest-js/README.md) for details ### functions-js - Simplest library, minimal dependencies - Uses testcontainers for Deno relay -- Default branch: **main** - See [functions-js README](packages/core/functions-js/README.md) for details ## Code Style Guidelines @@ -487,10 +482,10 @@ cat docs/TESTING.md 1. **Ensure branch is up to date:** ```bash - git checkout main - git pull upstream main + git checkout master + git pull upstream master git checkout your-feature-branch - git rebase main + git rebase master ``` 2. **Run all necessary checks:** @@ -643,7 +638,7 @@ nx test auth-js --testFile=GoTrueClient.test.ts **Canary Releases (Automated)**: ```bash -# Triggered automatically on every commit to main +# Triggered automatically on every commit to master git commit -m "fix(auth): resolve token issue" # โ†’ Automatic CI: nx release --tag=canary --yes # โ†’ Published: 2.80.1-canary.0 to 'canary' dist-tag diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0bd060946..2abf83786 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -56,7 +56,7 @@ Thank you for your interest in contributing to the Supabase JavaScript client li ### Making Changes -1. **Create a new branch** from `main`: +1. **Create a new branch** from `master`: ```bash git checkout -b feature/your-feature-name @@ -186,13 +186,13 @@ ci(release): add preview package generation ### Before Submitting -1. **Ensure your branch is up to date** with `main`: +1. **Ensure your branch is up to date** with `master`: ```bash - git checkout main - git pull upstream main + git checkout master + git pull upstream master git checkout your-branch - git rebase main + git rebase master ``` 2. **Run the full test suite**: @@ -283,7 +283,7 @@ npx nx test --coverage We automatically generate TypeScript API documentation that is used by the main [Supabase documentation site](https://supabase.com/docs). The process works as follows: 1. **TypeDoc generates JSON specifications** from TypeScript source code -2. **GitHub Actions publishes** these specs to GitHub Pages on every push to `main` +2. **GitHub Actions publishes** these specs to GitHub Pages on every push to `master` 3. **Main Supabase repository** uses these JSON files to generate the official API docs via `make` commands #### Available Documentation Commands diff --git a/README.md b/README.md index 1966f9546..a67e97d69 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,9 @@ # Supabase JS Client Libraries +
+[![pkg.pr.new](https://pkg.pr.new/badge/supabase/supabase-js)](https://pkg.pr.new/badge/supabase/supabase-js) +
+ _The Supabase JS monorepo containing all the Supabase JavaScript client libraries._ > **๐Ÿ“ฃ Coming from our old repositories?** The `supabase-js` repository has been converted into a monorepo and all other client libraries have been absorbed into it. If you previously contributed to individual repositories like `auth-js`, `postgrest-js`, `realtime-js`, `storage-js`, or `functions-js`, please see our **[Migration Guide](./docs/MIGRATION.md)** to learn about the new structure and workflows. diff --git a/WARP.md b/WARP.md index b353491cb..32239c190 100644 --- a/WARP.md +++ b/WARP.md @@ -256,14 +256,14 @@ nx affected --target=test ### Library Characteristics -| Library | Default Branch | Docker Required | Primary Use Case | -| ------------ | -------------- | --------------- | -------------------------- | -| supabase-js | master | โŒ No | Main isomorphic client | -| auth-js | master | โœ… Yes | Authentication & user mgmt | -| postgrest-js | master | โœ… Yes | Database queries | -| realtime-js | master | โŒ No | Real-time subscriptions | -| functions-js | main | โœ… Yes | Edge Functions invocation | -| storage-js | main | โœ… Yes | File storage operations | +| Library | Docker Required | Primary Use Case | +| ------------ | --------------- | -------------------------- | +| supabase-js | โŒ No | Main isomorphic client | +| auth-js | โœ… Yes | Authentication & user mgmt | +| postgrest-js | โœ… Yes | Database queries | +| realtime-js | โŒ No | Real-time subscriptions | +| functions-js | โœ… Yes | Edge Functions invocation | +| storage-js | โœ… Yes | File storage operations | ## Nx Workspace Features @@ -343,7 +343,7 @@ All packages in this monorepo use **fixed version mode**, meaning they share the #### 1. Canary Releases (Automated) -**Trigger**: Every commit to `main` branch +**Trigger**: Every commit to `master` branch **Workflow**: `.github/workflows/main-ci-release.yml` - Automatically creates pre-release version (e.g., `2.80.1-canary.0`) @@ -489,7 +489,7 @@ feat(realtime)!: remove deprecated subscribe method ### Before Submitting -1. Ensure your branch is up to date with `main` +1. Ensure your branch is up to date with `master` 2. Run affected tests: `nx affected --target=test` 3. Run affected builds: `nx affected --target=build` 4. Format code: `nx format` diff --git a/docs/MIGRATION.md b/docs/MIGRATION.md index dbb220c81..0d425425f 100644 --- a/docs/MIGRATION.md +++ b/docs/MIGRATION.md @@ -263,8 +263,8 @@ Commands that weren't available in separate repos: # Visualize project dependencies npx nx graph -# Build only what changed since main -npx nx affected --target=build --base=main +# Build only what changed since master +npx nx affected --target=build --base=master # Test only what changed npx nx affected --target=test diff --git a/docs/RELEASE.md b/docs/RELEASE.md index 8f64fcc7b..727454890 100644 --- a/docs/RELEASE.md +++ b/docs/RELEASE.md @@ -1,6 +1,6 @@ # Release Workflows -- [.github/workflows/main-ci-release.yml](.github/workflows/main-ci-release.yml) - Main branch CI & automated canary releases +- [.github/workflows/main-ci-release.yml](.github/workflows/main-ci-release.yml) - Main CI & automated canary releases - [.github/workflows/release-stable.yml](.github/workflows/release-stable.yml) - Manual stable releases - [.github/workflows/preview-release.yml](.github/workflows/preview-release.yml) - PR preview releases @@ -8,7 +8,7 @@ This monorepo uses a fixed release model where all packages share a single version number and are released together. There are three types of releases: -1. **Canary Releases** - Automated pre-releases on every commit to main +1. **Canary Releases** - Automated pre-releases on every commit to master 2. **Stable Releases** - Manual releases for production use 3. **Preview Releases** - PR-specific releases for testing changes @@ -17,7 +17,7 @@ This monorepo uses a fixed release model where all packages share a single versi ### ๐Ÿค– Canary Releases (Automated) **File:** `main-ci-release.yml` -**Trigger:** Every push to `main` branch +**Trigger:** Every push to `master` branch **Purpose:** Immediate feedback with pre-release versions #### What it does @@ -37,7 +37,7 @@ This monorepo uses a fixed release model where all packages share a single versi git commit -m "fix(auth): resolve token refresh issue" ``` -- Open PR and get it merged to `main` +- Open PR and get it merged to `master` - Then: โ†’ CI runs and passes @@ -119,7 +119,7 @@ Canary releases are **fully automated**. Simply: 1. Make changes in your feature branch 2. Use conventional commits with type and scope (e.g., `fix(auth):`, `feat(realtime):`, `chore(repo):`) -3. Create and merge PR to `main` branch +3. Create and merge PR to `master` branch 4. Workflow automatically: - Runs CI checks - Creates pre-release version @@ -197,7 +197,7 @@ The workflows rely on `nx.json` release configuration: ### For Repository Owners 1. **Release cadence**: - - Canary: Automatic on every `main` commit + - Canary: Automatic on every `master` commit - Stable: Weekly or as needed - Major: Coordinate with team and users 2. **Version strategy**: @@ -209,7 +209,7 @@ The workflows rely on `nx.json` release configuration: ### For Emergency Releases -1. **Fix in `main` first** - Apply fix and let canary release +1. **Fix in `master` first** - Apply fix and let canary release 2. **Test canary** - Verify fix works in canary version 3. **Release stable** - Use stable workflow with `patch` 4. **Document incident** - Update changelog with details diff --git a/nx.json b/nx.json index 292dcd6a7..87f4c8de7 100644 --- a/nx.json +++ b/nx.json @@ -1,5 +1,6 @@ { "$schema": "./node_modules/nx/schemas/nx-schema.json", + "defaultBase": "master", "namedInputs": { "default": ["{projectRoot}/**/*", "sharedGlobals"], "production": [ diff --git a/packages/core/auth-js/README.md b/packages/core/auth-js/README.md index b369d5d57..ac918e44a 100644 --- a/packages/core/auth-js/README.md +++ b/packages/core/auth-js/README.md @@ -11,7 +11,7 @@ An isomorphic JavaScript client library for the [Supabase Auth](https://github.c ## Docs - Using `auth-js`: https://supabase.com/docs/reference/javascript/auth-signup -- TypeDoc: https://supabase.github.io/auth-js/v2 +- TypeDoc: https://supabase.github.io/supabase-js/auth-js/v2/spec.json ## Quick start diff --git a/packages/core/auth-js/package.json b/packages/core/auth-js/package.json index ee87525f3..90a901a2e 100644 --- a/packages/core/auth-js/package.json +++ b/packages/core/auth-js/package.json @@ -9,7 +9,7 @@ "auth", "authentication" ], - "homepage": "https://github.com/supabase/supabase-js/tree/main/packages/core/auth-js", + "homepage": "https://github.com/supabase/supabase-js/tree/master/packages/core/auth-js", "bugs": "https://github.com/supabase/supabase-js/issues", "license": "MIT", "author": "Supabase", diff --git a/packages/core/functions-js/README.md b/packages/core/functions-js/README.md index 09e596eb6..d8d17a9dd 100644 --- a/packages/core/functions-js/README.md +++ b/packages/core/functions-js/README.md @@ -1,11 +1,18 @@ # `functions-js` +
+ +[![pkg.pr.new](https://pkg.pr.new/badge/supabase/functions-js)](https://pkg.pr.new/~/supabase/functions-js) + +
+ JS Client library to interact with Supabase Functions. ## Docs - **API Reference**: - **Functions Guide**: +- **Typedoc**: ## Quick Start diff --git a/packages/core/functions-js/package.json b/packages/core/functions-js/package.json index b2e637d0e..b39b66d95 100644 --- a/packages/core/functions-js/package.json +++ b/packages/core/functions-js/package.json @@ -35,7 +35,7 @@ "bugs": { "url": "https://github.com/supabase/supabase-js/issues" }, - "homepage": "https://github.com/supabase/supabase-js/tree/main/packages/core/functions-js", + "homepage": "https://github.com/supabase/supabase-js/tree/master/packages/core/functions-js", "dependencies": { "@supabase/node-fetch": "2.6.15" }, diff --git a/packages/core/postgrest-js/README.md b/packages/core/postgrest-js/README.md index 01cfb9c1c..61b094c5d 100644 --- a/packages/core/postgrest-js/README.md +++ b/packages/core/postgrest-js/README.md @@ -7,7 +7,7 @@ Isomorphic JavaScript client for [PostgREST](https://postgrest.org). The goal of this library is to make an "ORM-like" restful interface. -Full documentation can be found [here](https://supabase.github.io/postgrest-js/v2). +Full documentation can be found [here](https://supabase.github.io/supabase-js/postgrest-js/v2/spec.json). ### Quick start diff --git a/packages/core/postgrest-js/package.json b/packages/core/postgrest-js/package.json index c586b1f53..d1ccf2e5c 100644 --- a/packages/core/postgrest-js/package.json +++ b/packages/core/postgrest-js/package.json @@ -6,7 +6,7 @@ "postgrest", "supabase" ], - "homepage": "https://github.com/supabase/supabase-js/tree/main/packages/core/postgrest-js", + "homepage": "https://github.com/supabase/supabase-js/tree/master/packages/core/postgrest-js", "bugs": "https://github.com/supabase/supabase-js/issues", "license": "MIT", "author": "Supabase", diff --git a/packages/core/realtime-js/package.json b/packages/core/realtime-js/package.json index 02a256b76..3cb2a3b9e 100644 --- a/packages/core/realtime-js/package.json +++ b/packages/core/realtime-js/package.json @@ -11,7 +11,7 @@ "firebase", "supabase" ], - "homepage": "https://github.com/supabase/supabase-js/tree/main/packages/core/realtime-js", + "homepage": "https://github.com/supabase/supabase-js/tree/master/packages/core/realtime-js", "bugs": "https://github.com/supabase/supabase-js/issues", "files": [ "dist", diff --git a/packages/core/storage-js/README.md b/packages/core/storage-js/README.md index 1396310d4..4eda3e826 100644 --- a/packages/core/storage-js/README.md +++ b/packages/core/storage-js/README.md @@ -9,6 +9,7 @@ JS Client library to interact with Supabase Storage. - Documentation: https://supabase.io/docs/reference/javascript/storage-createbucket +- Typedoc: https://supabase.github.io/supabase-js/storage-js/v2/spec.json ## Quick Start Guide diff --git a/packages/core/storage-js/package.json b/packages/core/storage-js/package.json index 5ded1a08e..789519e13 100644 --- a/packages/core/storage-js/package.json +++ b/packages/core/storage-js/package.json @@ -7,7 +7,7 @@ "typescript", "supabase" ], - "homepage": "https://github.com/supabase/supabase-js/tree/main/packages/core/storage-js", + "homepage": "https://github.com/supabase/supabase-js/tree/master/packages/core/storage-js", "bugs": "https://github.com/supabase/supabase-js/issues", "license": "MIT", "author": "Supabase", diff --git a/packages/core/supabase-js/package.json b/packages/core/supabase-js/package.json index 196d425ad..1727c69fc 100644 --- a/packages/core/supabase-js/package.json +++ b/packages/core/supabase-js/package.json @@ -7,7 +7,7 @@ "typescript", "supabase" ], - "homepage": "https://github.com/supabase/supabase-js/tree/main/packages/core/supabase-js", + "homepage": "https://github.com/supabase/supabase-js/tree/master/packages/core/supabase-js", "bugs": "https://github.com/supabase/supabase-js/issues", "license": "MIT", "author": "Supabase", diff --git a/scripts/release-stable.ts b/scripts/release-stable.ts index 7f7b9a791..e77bb29cd 100644 --- a/scripts/release-stable.ts +++ b/scripts/release-stable.ts @@ -114,7 +114,7 @@ if (!validSpecifiers.includes(versionSpecifier) && !isValidVersion) { // Open PR using GitHub CLI execSync( - `gh pr create --base main --head ${branchName} --title "chore(release): ${version}" --body "Automated release PR for ${version}"`, + `gh pr create --base master --head ${branchName} --title "chore(release): ${version}" --body "Automated release PR for ${version}"`, { stdio: 'inherit' } ) From 2eb2ad781429b5d67dd1bfb680cdcf8ac692e771 Mon Sep 17 00:00:00 2001 From: Katerina Skroumpelou Date: Thu, 2 Oct 2025 12:03:05 +0300 Subject: [PATCH 2/4] chore(repo): update docs for contributors --- CONTRIBUTING.md | 6 ++- README.md | 17 +++++++- docs/MIGRATION.md | 100 +++++++++++++++++++++++++++++++++++++++++----- 3 files changed, 112 insertions(+), 11 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2abf83786..d4e1ee3bf 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,7 +2,11 @@ Thank you for your interest in contributing to the Supabase JavaScript client libraries! This guide will help you get started with contributing to the Supabase JS monorepo. -> **๐Ÿ“ฃ Coming from a separate repository?** The `supabase-js` repository has been converted into a monorepo and all other Supabase JS libraries have been absorbed into it. If you previously contributed to `auth-js`, `postgrest-js`, `realtime-js`, `storage-js`, or `functions-js`, please read our **[Migration Guide](docs/MIGRATION.md)** to understand the new structure, workflow changes, and command mappings. +> **Repository Structure Changed:** This repository has been restructured as a monorepo. **All libraries, including `supabase-js`, are now under `packages/core/`**. If you previously contributed to `supabase-js`, `auth-js`, `postgrest-js`, `realtime-js`, `storage-js`, or `functions-js`, please read our **[Migration Guide](docs/MIGRATION.md)** to understand: +> +> - Where your code moved (everything is now in `packages/core//`) +> - How commands changed (`npm test` โ†’ `npx nx test `) +> - New workflow with Nx ## ๐Ÿ“‹ Table of Contents diff --git a/README.md b/README.md index a67e97d69..773684c44 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,22 @@ _The Supabase JS monorepo containing all the Supabase JavaScript client libraries._ -> **๐Ÿ“ฃ Coming from our old repositories?** The `supabase-js` repository has been converted into a monorepo and all other client libraries have been absorbed into it. If you previously contributed to individual repositories like `auth-js`, `postgrest-js`, `realtime-js`, `storage-js`, or `functions-js`, please see our **[Migration Guide](./docs/MIGRATION.md)** to learn about the new structure and workflows. +> **IMPORTANT: Repository Structure Changed** +> +> This repository has been restructured as a monorepo. **All libraries, including `supabase-js` itself, have moved to `packages/core/`**: +> +> | What You're Looking For | Where It Is Now | +> |------------------------|-----------------| +> | Main supabase-js code | `packages/core/supabase-js/` | +> | Auth library code | `packages/core/auth-js/` | +> | Database library code | `packages/core/postgrest-js/` | +> | Other libraries | `packages/core/*/` | +> +> **If you contributed to ANY of these repositories before**, please read our **[Migration Guide](./docs/MIGRATION.md)** to understand: +> +> - Where your code moved +> - How commands changed (e.g., `npm test` โ†’ `npx nx test supabase-js`) +> - How to update your development workflow ## ๐Ÿ“ฆ Libraries diff --git a/docs/MIGRATION.md b/docs/MIGRATION.md index 0d425425f..a9dcae787 100644 --- a/docs/MIGRATION.md +++ b/docs/MIGRATION.md @@ -1,6 +1,61 @@ -# Migration Guide: From Separate Repos to the Supabase JS Monorepo +# Migration Guide: Transitioning to the Supabase JS Monorepo -> ๐Ÿš€ **Welcome to the Supabase JS monorepo!** This guide will help you transition from the old separate repository structure to our new Nx monorepo. +> ๐Ÿš€ **Welcome to the Supabase JS monorepo!** This repository has been completely restructured. Whether you contributed to `supabase-js`, `auth-js`, `postgrest-js`, or any other Supabase JS library, this guide will help you understand what changed and how to work with the new structure. + +## ๐ŸŽฏ Who This Guide Is For + +This guide is for: + +- **Contributors to the old `supabase-js` repository** - Yes, even supabase-js moved! +- **Contributors to separate libraries** (`auth-js`, `postgrest-js`, `realtime-js`, `storage-js`, `functions-js`) +- **Anyone with open PRs** in any of the old repositories +- **New contributors** who want to understand the architecture + +## What Changed: The Big Picture + +### The Repository URL Stayed the Same, But Everything Inside Changed + +**Important:** The repository is still at `github.com/supabase/supabase-js`, but: + +**OLD Structure** (what you remember): + +```tree +github.com/supabase/supabase-js/ +โ”œโ”€โ”€ src/ โ† supabase-js code was here +โ”œโ”€โ”€ test/ +โ”œโ”€โ”€ package.json +โ””โ”€โ”€ README.md + +github.com/supabase/auth-js/ โ† Separate repo +github.com/supabase/postgrest-js/ โ† Separate repo +github.com/supabase/realtime-js/ โ† Separate repo +github.com/supabase/storage-js/ โ† Separate repo +github.com/supabase/functions-js/ โ† Separate repo +``` + +**NEW Structure** (what you'll see now): + +```tree +github.com/supabase/supabase-js/ โ† Same URL, different structure! +โ”œโ”€โ”€ packages/ +โ”‚ โ””โ”€โ”€ core/ +โ”‚ โ”œโ”€โ”€ supabase-js/ โ† YOUR supabase-js code is HERE now +โ”‚ โ”‚ โ”œโ”€โ”€ src/ +โ”‚ โ”‚ โ”œโ”€โ”€ test/ +โ”‚ โ”‚ โ””โ”€โ”€ package.json +โ”‚ โ”œโ”€โ”€ auth-js/ โ† auth-js moved here +โ”‚ โ”œโ”€โ”€ postgrest-js/ โ† postgrest-js moved here +โ”‚ โ”œโ”€โ”€ realtime-js/ โ† realtime-js moved here +โ”‚ โ”œโ”€โ”€ storage-js/ โ† storage-js moved here +โ”‚ โ””โ”€โ”€ functions-js/ โ† functions-js moved here +โ”œโ”€โ”€ nx.json โ† New: Nx workspace config +โ”œโ”€โ”€ package.json โ† New: Root workspace config +โ””โ”€โ”€ README.md +``` + +### Key Point: EVERYTHING Moved + +**All six libraries**, including `supabase-js` itself, now live under `packages/core/`. This is not a case where some libraries moved "into" supabase-js - rather, **all libraries were reorganized into a shared monorepo structure**. ## ๐Ÿ“‹ Table of Contents @@ -285,6 +340,28 @@ npx nx run-many --target=docs --all ## FAQ +### Q: I contributed to the old supabase-js repo. Where did my code go? + +**A:** The old `supabase-js` repository code is now in `packages/core/supabase-js/`. The repository URL (`github.com/supabase/supabase-js`) stayed the same, but the internal structure changed completely. What used to be in the root (`src/`, `test/`, etc.) is now nested under `packages/core/supabase-js/`. + +Example mappings: + +- **Old:** `src/SupabaseClient.ts` +- **New:** `packages/core/supabase-js/src/SupabaseClient.ts` + +This was necessary to accommodate all the other libraries in a unified structure. + +### Q: Why does it say supabase-js "absorbed" other libraries if supabase-js also moved? + +**A:** That's admittedly confusing wording! What actually happened: + +- The `supabase-js` **repository URL** stayed the same (`github.com/supabase/supabase-js`) +- But **all libraries** (including supabase-js itself) moved into a `packages/core/` structure +- Other library repositories (`auth-js`, `postgrest-js`, etc.) were archived +- So the repository "absorbed" them in the sense that it now contains all libraries, but supabase-js code itself also relocated + +Think of it as: the **repository** absorbed other libraries, but the **supabase-js package code** also moved. + ### Q: Why fixed versioning instead of independent versions? **A:** Fixed versioning ensures all Supabase JS libraries are always compatible with each other. Users don't need to worry about compatibility matrices or which version of auth-js works with which version of supabase-js. @@ -308,7 +385,12 @@ npx nx test auth-js --watch ### Q: How do I know which files to edit? -**A:** The structure within each package is the same as before. If you edited `src/GoTrueClient.ts` in the old auth-js repo, you'll now edit `packages/core/auth-js/src/GoTrueClient.ts`. +**A:** The structure within each package is the same as before. Examples: + +- **Old auth-js repo:** `src/GoTrueClient.ts` โ†’ **New:** `packages/core/auth-js/src/GoTrueClient.ts` +- **Old supabase-js repo:** `src/SupabaseClient.ts` โ†’ **New:** `packages/core/supabase-js/src/SupabaseClient.ts` + +The internal structure of each library is unchanged, just the top-level location changed. ### Q: Do I need to learn Nx? @@ -350,13 +432,13 @@ npm install @supabase/supabase-js ### Important Links -- **Supabase JS Monorepo**: https://github.com/supabase/supabase-js +- **Supabase JS Monorepo**: - **Old Repos** (archived/read-only): - - https://github.com/supabase/auth-js - - https://github.com/supabase/postgrest-js - - https://github.com/supabase/realtime-js - - https://github.com/supabase/storage-js - - https://github.com/supabase/functions-js + - + - + - + - + - --- From fbf08877217e64d2cebec9b71db238e8d1cc0c2d Mon Sep 17 00:00:00 2001 From: Katerina Skroumpelou Date: Thu, 2 Oct 2025 12:26:17 +0300 Subject: [PATCH 3/4] chore(repo): update docs --- .cursorrules | 23 ++++++--- CLAUDE.md | 43 +++++++++------- README.md | 54 +++++++++++++------ WARP.md | 28 +++++----- docs/MIGRATION.md | 128 +++++++++++++++++++++++++++------------------- 5 files changed, 166 insertions(+), 110 deletions(-) diff --git a/.cursorrules b/.cursorrules index 4e7b5c3fd..5d05a8303 100644 --- a/.cursorrules +++ b/.cursorrules @@ -30,9 +30,11 @@ This monorepo contains 6 JavaScript/TypeScript libraries previously maintained a ### Testing - Test all: `nx run-many --target=test --all` -- Test specific: `nx test auth-js` -- Test affected: `nx affected --target=test` +- Test specific: `nx test auth-js` (some packages may have special targets like `nx test:auth auth-js` or `nx test:storage storage-js`) +- Test affected: `nx affected --target=test` (recommended for efficiency) - Integration tests: `nx run-many --target=test:integration --all` +- Watch mode: `nx test --watch` +- Coverage: `nx test --coverage` ### Code Quality - Lint all: `nx run-many --target=lint --all` @@ -109,10 +111,12 @@ packages/core/[library-name]/ ## Important Notes -- **Different Default Branches**: Original repos used either `master` or `main` - be aware when referencing history +- **Current Default Branch**: `master` (confirmed current default branch) +- **Original Branch Differences**: Original repos used either `master` or `main` - be aware when referencing history - **Package Names**: All packages maintain original npm names (@supabase/[package-name]) - **Shared Code**: Extract common patterns (HTTP client, error handling) to shared packages when identified -- **Docker Required**: Integration tests for auth-js and storage-js require Docker to be running +- **Docker Required**: Integration tests for auth-js, functions-js, postgrest-js, and storage-js require Docker to be running +- **Special Test Commands**: Some packages may use special test targets (check individual package READMEs) ## Release Process @@ -156,7 +160,10 @@ The `*` is replaced with actual version during release. 1. Always consider the monorepo structure - changes might affect multiple packages 2. Use Nx commands rather than npm/yarn directly for workspace operations -3. Suggest running affected tests, not all tests, for better performance -4. Remember that all packages version together in fixed mode -5. Consider Docker requirements for integration tests -6. Maintain backward compatibility at all costs +3. Suggest running affected tests (`nx affected --target=test`), not all tests, for better performance +4. Remember that all packages version together in fixed mode - no independent versioning +5. Consider Docker requirements for integration tests (auth-js, functions-js, postgrest-js, storage-js) +6. Maintain backward compatibility at all costs - breaking changes require special process +7. Check for special test commands in package READMEs (some may use `test:auth`, `test:storage`, etc.) +8. Always suggest conventional commit format with proper scope +9. Prefer `nx affected` commands over `nx run-many` for efficiency diff --git a/CLAUDE.md b/CLAUDE.md index b8833ad26..7ade2eb21 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -129,7 +129,7 @@ nx test auth-js # Test specific package nx test postgrest-js # Test specific package nx test functions-js # Test specific package nx test realtime-js # Test specific package -nx test storage-js # Test specific package +nx test storage-js # Test specific package (may use special test:storage target) nx test supabase-js # Test specific package nx affected --target=test # Test only affected (recommended) nx test auth-js --watch # Watch mode @@ -138,14 +138,14 @@ nx test supabase-js --coverage # Test with coverage **Docker Requirements:** -| Package | Docker Required | Infrastructure | -| ------------ | --------------- | ------------------------------- | -| auth-js | โœ… Yes | GoTrue + PostgreSQL | -| functions-js | โœ… Yes | Deno relay (testcontainers) | -| postgrest-js | โœ… Yes | PostgREST + PostgreSQL | -| storage-js | โœ… Yes | Storage API + PostgreSQL + Kong | -| realtime-js | โŒ No | Mock WebSockets | -| supabase-js | โŒ No | Unit tests only | +| Package | Docker Required | Infrastructure | Special Commands | +| ------------ | --------------- | ------------------------------- | ---------------- | +| auth-js | โœ… Yes | GoTrue + PostgreSQL | May use `nx test:auth auth-js` | +| functions-js | โœ… Yes | Deno relay (testcontainers) | Standard `nx test functions-js` | +| postgrest-js | โœ… Yes | PostgREST + PostgreSQL | Standard `nx test postgrest-js` | +| storage-js | โœ… Yes | Storage API + PostgreSQL + Kong | May use `nx test:storage storage-js` | +| realtime-js | โŒ No | Mock WebSockets | Standard `nx test realtime-js` | +| supabase-js | โŒ No | Unit tests only | Standard `nx test supabase-js` | > **๐Ÿ“– See [TESTING.md](docs/TESTING.md) for complete testing guide and troubleshooting** @@ -311,10 +311,13 @@ Tests run against multiple environments: ## Important Context -### Branch Differences +### Branch Information -Original repositories use different default branches: +**Current Repository:** +- **Default branch**: `master` (confirmed current default) +- **Repository URL**: `github.com/supabase/supabase-js` +**Original Repository Branches** (for historical reference): - **master**: auth-js, postgrest-js, realtime-js, supabase-js - **main**: functions-js, storage-js @@ -736,14 +739,16 @@ _No user-facing changes in this release._ ## When Providing Code Suggestions -1. **Consider Monorepo Impact**: Changes might affect multiple packages - always check -2. **Use Nx Commands**: Prefer `nx` over direct `npm` for workspace operations -3. **Suggest Affected Testing**: `nx affected --target=test` over full test suite -4. **Respect Fixed Versioning**: All packages version together -5. **Maintain Compatibility**: Never introduce breaking changes -6. **Extract Shared Code**: Identify patterns that could be shared -7. **Follow Conventions**: Use existing patterns and structures -8. **Document Changes**: Update JSDoc and READMEs when changing APIs +1. **Consider Monorepo Impact**: Changes might affect multiple packages - always check dependencies +2. **Use Nx Commands**: Always prefer `nx` over direct `npm` for workspace operations +3. **Suggest Affected Testing**: Use `nx affected --target=test` over full test suite for efficiency +4. **Respect Fixed Versioning**: All packages version together - no independent versioning +5. **Maintain Compatibility**: Never introduce breaking changes without proper process +6. **Check Testing Requirements**: Be aware of Docker requirements for integration tests +7. **Extract Shared Code**: Identify patterns that could be shared across packages +8. **Follow Conventions**: Use existing patterns and structures within each library +9. **Document Changes**: Update JSDoc and READMEs when changing public APIs +10. **Use Conventional Commits**: Always suggest proper commit format with scope ## Quick Decision Tree diff --git a/README.md b/README.md index 773684c44..877c4b098 100644 --- a/README.md +++ b/README.md @@ -1,27 +1,38 @@ -# Supabase JS Client Libraries +
+

+ + + + + Supabase Logo + + + +

Supabase JS Client Libraries

+ +

+ Guides + ยท + Reference Docs +

+

-[![pkg.pr.new](https://pkg.pr.new/badge/supabase/supabase-js)](https://pkg.pr.new/badge/supabase/supabase-js) -
-_The Supabase JS monorepo containing all the Supabase JavaScript client libraries._ +[![pkg.pr.new](https://pkg.pr.new/badge/supabase/supabase-js)](https://pkg.pr.new/~/supabase/supabase-js) -> **IMPORTANT: Repository Structure Changed** -> -> This repository has been restructured as a monorepo. **All libraries, including `supabase-js` itself, have moved to `packages/core/`**: + + +> **For contributors: Repository Structure Changed** > -> | What You're Looking For | Where It Is Now | -> |------------------------|-----------------| -> | Main supabase-js code | `packages/core/supabase-js/` | -> | Auth library code | `packages/core/auth-js/` | -> | Database library code | `packages/core/postgrest-js/` | -> | Other libraries | `packages/core/*/` | +> This repository has been restructured as a monorepo. All libraries, including `supabase-js` itself, have moved to `packages/core/`: > -> **If you contributed to ANY of these repositories before**, please read our **[Migration Guide](./docs/MIGRATION.md)** to understand: +> | What You're Looking For | Where It Is Now | +> | ----------------------- | ---------------------------- | +> | Main supabase-js code | `packages/core/supabase-js/` | +> | Other libraries | `packages/core/*/` | > -> - Where your code moved -> - How commands changed (e.g., `npm test` โ†’ `npx nx test supabase-js`) -> - How to update your development workflow +> Read the **[Migration Guide](./docs/MIGRATION.md)** to learn more. ## ๐Ÿ“ฆ Libraries @@ -36,6 +47,15 @@ This monorepo contains the complete suite of Supabase JavaScript client librarie | **[@supabase/storage-js](./packages/core/storage-js)** | File storage client | | **[@supabase/functions-js](./packages/core/functions-js)** | Edge Functions client | +> **๐Ÿ’ก Note for Package Users:** If you install and use these packages, **nothing has changed**. Continue installing packages normally: +> +> ```bash +> npm install @supabase/supabase-js +> npm install @supabase/auth-js +> ``` +> +> The monorepo structure **only affects contributors**. This is how we develop and maintain the code, not how you use it. + ## ๐Ÿš€ Quick Start ### Installation diff --git a/WARP.md b/WARP.md index 32239c190..d20f92eac 100644 --- a/WARP.md +++ b/WARP.md @@ -27,7 +27,8 @@ This monorepo replaces the following individual repositories: ### Important Notes -- **Default Branches**: Original repos use different default branches (master vs main). Check each library's original repo for reference. +- **Current Default Branch**: `master` (confirmed current default branch) +- **Original Branch Differences**: Original repos used different default branches (master vs main). Check each library's original repo for reference. - **Package Names**: All packages maintain their original npm names (@supabase/[package-name]) - **Zero Breaking Changes**: This migration maintains full backward compatibility for consumers - **Shared Code**: Common patterns (HTTP client, error handling) should be extracted to shared packages when identified @@ -95,11 +96,11 @@ nx affected --target=build nx run-many --target=test --all # Run tests for a specific library -nx test auth-js +nx test auth-js # May also use: nx test:auth auth-js nx test postgrest-js nx test functions-js nx test realtime-js -nx test storage-js +nx test storage-js # May also use: nx test:storage storage-js nx test supabase-js # Run only affected tests (recommended during development) @@ -114,14 +115,14 @@ nx test auth-js --coverage **Docker Requirements for Integration Tests:** -| Package | Docker Required | Notes | -| ------------ | --------------- | ------------------------------- | -| auth-js | โœ… Yes | Requires GoTrue + PostgreSQL | -| functions-js | โœ… Yes | Uses testcontainers for Deno | -| postgrest-js | โœ… Yes | Requires PostgREST + PostgreSQL | -| storage-js | โœ… Yes | Requires Storage API + Kong | -| realtime-js | โŒ No | Uses mock WebSockets | -| supabase-js | โŒ No | Unit tests only | +| Package | Docker Required | Notes | Special Commands | +| ------------ | --------------- | ------------------------------- | ---------------- | +| auth-js | โœ… Yes | Requires GoTrue + PostgreSQL | May use `nx test:auth auth-js` | +| functions-js | โœ… Yes | Uses testcontainers for Deno | Standard `nx test functions-js` | +| postgrest-js | โœ… Yes | Requires PostgREST + PostgreSQL | Standard `nx test postgrest-js` | +| storage-js | โœ… Yes | Requires Storage API + Kong | May use `nx test:storage storage-js` | +| realtime-js | โŒ No | Uses mock WebSockets | Standard `nx test realtime-js` | +| supabase-js | โŒ No | Unit tests only | Standard `nx test supabase-js` | ### Code Quality @@ -554,8 +555,10 @@ packages/core/[library]/ - **Run affected commands** to save time (`nx affected --target=test`) - **Use interactive commit tool** (`npm run commit`) - **Format code** before committing (`nx format`) -- **Read package READMEs** for library-specific details +- **Read package READMEs** for library-specific details and special test commands - **Check documentation** in `docs/` for comprehensive guides +- **Check for Docker requirements** before running integration tests +- **Use conventional commit format** with proper scope ### Don'ts โŒ @@ -564,6 +567,7 @@ packages/core/[library]/ - **Don't hardcode internal versions** (use `*` protocol) - **Don't test everything** when only some packages changed (use `nx affected`) - **Don't make breaking changes** without discussion and proper commit format +- **Don't assume all packages use standard test commands** (check for special targets) ## Troubleshooting diff --git a/docs/MIGRATION.md b/docs/MIGRATION.md index a9dcae787..e8b243461 100644 --- a/docs/MIGRATION.md +++ b/docs/MIGRATION.md @@ -1,23 +1,27 @@ # Migration Guide: Transitioning to the Supabase JS Monorepo -> ๐Ÿš€ **Welcome to the Supabase JS monorepo!** This repository has been completely restructured. Whether you contributed to `supabase-js`, `auth-js`, `postgrest-js`, or any other Supabase JS library, this guide will help you understand what changed and how to work with the new structure. +> **This repository has been restructured.** If you contributed to `supabase-js`, `auth-js`, `postgrest-js`, or any other Supabase JS library, this guide explains what changed and how to work with the new structure. + +> **๐Ÿ“ฆ Note for Package Users:** If you install and use these packages via npm, **nothing changed**. This guide is for contributors who develop and maintain these libraries. ## ๐ŸŽฏ Who This Guide Is For -This guide is for: +**This guide is for contributors**, including: + +- Contributors to the old `supabase-js` repository (even supabase-js moved) +- Contributors to separate libraries (`auth-js`, `postgrest-js`, `realtime-js`, `storage-js`, `functions-js`) +- Anyone with open PRs in any of the old repositories +- New contributors who want to understand the architecture -- **Contributors to the old `supabase-js` repository** - Yes, even supabase-js moved! -- **Contributors to separate libraries** (`auth-js`, `postgrest-js`, `realtime-js`, `storage-js`, `functions-js`) -- **Anyone with open PRs** in any of the old repositories -- **New contributors** who want to understand the architecture +**Not a contributor?** You can skip this guide. Packages are still installed and used the same way. -## What Changed: The Big Picture +## โš ๏ธ What Changed: The Big Picture ### The Repository URL Stayed the Same, But Everything Inside Changed -**Important:** The repository is still at `github.com/supabase/supabase-js`, but: +The repository is still at `github.com/supabase/supabase-js`. -**OLD Structure** (what you remember): +**OLD Structure:** ```tree github.com/supabase/supabase-js/ @@ -55,7 +59,31 @@ github.com/supabase/supabase-js/ โ† Same URL, different structure! ### Key Point: EVERYTHING Moved -**All six libraries**, including `supabase-js` itself, now live under `packages/core/`. This is not a case where some libraries moved "into" supabase-js - rather, **all libraries were reorganized into a shared monorepo structure**. +All six libraries, including `supabase-js` itself, now live under `packages/core/`. All libraries were reorganized into a shared monorepo structure. + +### ๐Ÿ“ฆ Important: This Only Affects Contributors + +**If you use these packages, nothing changed.** + +The monorepo restructure is a **development workflow change** for maintainers and contributors. If you install these packages via npm, your experience is unchanged: + +```bash +# Still works the same +npm install @supabase/supabase-js +npm install @supabase/auth-js +npm install @supabase/storage-js +``` + +What stayed the same: + +- Packages are still published independently to npm +- You can still install only what you need +- Your existing code does not need any changes +- Package names remain the same (`@supabase/package-name`) + +The only difference is that all packages now share the same version number for compatibility across the ecosystem. + +This guide is for contributors who need to understand where code moved and how to develop and test these packages. ## ๐Ÿ“‹ Table of Contents @@ -70,7 +98,7 @@ github.com/supabase/supabase-js/ โ† Same URL, different structure! ## Why We Migrated -The `supabase-js` repository has been converted into a Nx monorepo and the other js client libraries have been absorbed into it to solve several critical challenges: +We converted the `supabase-js` repository into a monorepo and absorbed the other js client libraries to solve several challenges: ### Problems with Separate Repos @@ -88,8 +116,8 @@ The `supabase-js` repository has been converted into a Nx monorepo and the other - **Unified CI/CD**: Single pipeline with intelligent affected detection - **Simplified Testing**: Easy integration testing across all libraries - **Consistent Tooling**: One build system, one test runner, one format -- **Atomic Changes**: Make coordinated changes across multiple packages in one PR -- **Better DX**: Nx provides powerful caching, affected commands, and dependency visualization +- **Atomic Changes**: Coordinated changes across multiple packages in one PR +- **Better DX**: Nx provides caching, affected commands, and dependency visualization ## What Changed @@ -198,24 +226,26 @@ git checkout -b feature/your-feature-name ### For Active Pull Requests -We're working with contributors who have open PRs to handle the migration case-by-case. If you have an open PR: - -- **Reach out to maintainers** in your existing PR -- We'll help you either merge it quickly or assist with porting to the monorepo +If you have an open PR, reach out to maintainers in your existing PR. We will help you merge it quickly or assist with porting to the monorepo. ### For Projects Depending on Supabase Libraries -No changes needed for end users! The published npm packages remain the same: +**Zero changes for package users.** If you use these packages in your project, everything works as before. The monorepo is an internal development change. + +Packages are still published independently. ```json { "dependencies": { "@supabase/supabase-js": "^2.0.0", - "@supabase/auth-js": "^2.0.0" + "@supabase/auth-js": "^2.0.0", + "@supabase/storage-js": "^2.0.0" } } ``` +Your application code, imports, and usage patterns remain unchanged. The monorepo structure only affects how contributors develop and maintain these libraries. + ## Common Scenarios ### Scenario 1: "I was working on a bug fix in postgrest-js" @@ -229,8 +259,8 @@ npm run commit # Use interactive commit tool ### Scenario 2: "I need to update auth-js and test it with supabase-js" ```bash -# This was complex before - required npm link or multiple PRs -# Now it's simple: +# Before: required npm link or multiple PRs +# Now: simple # Make changes to auth-js edit packages/core/auth-js/src/GoTrueClient.ts @@ -268,19 +298,6 @@ npm run commit # feat(supabase): add cross-package feature for X functionality ``` -### Scenario 4: "I need to run integration tests" - -```bash -# Old way: Complex Docker setup per repo - -# New way: Integrated Docker management -npx nx test auth-js # Automatically sets up GoTrue -npx nx test storage-js # Automatically sets up Storage server - -# Run all integration tests -npx nx run-many --target=test:integration --all -``` - ## Command Reference ### Quick Command Conversion Table @@ -342,33 +359,33 @@ npx nx run-many --target=docs --all ### Q: I contributed to the old supabase-js repo. Where did my code go? -**A:** The old `supabase-js` repository code is now in `packages/core/supabase-js/`. The repository URL (`github.com/supabase/supabase-js`) stayed the same, but the internal structure changed completely. What used to be in the root (`src/`, `test/`, etc.) is now nested under `packages/core/supabase-js/`. +**A:** Your code is now in `packages/core/supabase-js/`. The repository URL (`github.com/supabase/supabase-js`) stayed the same, but the internal structure changed. What used to be in the root (`src/`, `test/`, etc.) is now nested under `packages/core/supabase-js/`. -Example mappings: +Example: - **Old:** `src/SupabaseClient.ts` - **New:** `packages/core/supabase-js/src/SupabaseClient.ts` -This was necessary to accommodate all the other libraries in a unified structure. +This structure accommodates all the libraries in one repository. ### Q: Why does it say supabase-js "absorbed" other libraries if supabase-js also moved? -**A:** That's admittedly confusing wording! What actually happened: +**A:** What happened: - The `supabase-js` **repository URL** stayed the same (`github.com/supabase/supabase-js`) -- But **all libraries** (including supabase-js itself) moved into a `packages/core/` structure +- All libraries (including supabase-js itself) moved into a `packages/core/` structure - Other library repositories (`auth-js`, `postgrest-js`, etc.) were archived -- So the repository "absorbed" them in the sense that it now contains all libraries, but supabase-js code itself also relocated +- The repository now contains all libraries, but supabase-js code also relocated -Think of it as: the **repository** absorbed other libraries, but the **supabase-js package code** also moved. +The **repository** absorbed other libraries. The **supabase-js package code** also moved. ### Q: Why fixed versioning instead of independent versions? -**A:** Fixed versioning ensures all Supabase JS libraries are always compatible with each other. Users don't need to worry about compatibility matrices or which version of auth-js works with which version of supabase-js. +**A:** Fixed versioning ensures all Supabase JS libraries are compatible with each other. You do not need to worry about compatibility matrices or which version of auth-js works with which version of supabase-js. ### Q: Can I still work on just one library? -**A:** Absolutely! The monorepo structure doesn't mean you have to work on everything. You can focus on a single library: +**A:** Yes. The monorepo structure does not mean you have to work on everything. You can focus on a single library: ```bash npx nx build auth-js --watch @@ -381,7 +398,7 @@ npx nx test auth-js --watch ### Q: Will old issues and PRs be migrated? -**A:** Open issues are being triaged and migrated as appropriate. For open PRs, we'll work with contributors individually. Check the old repo for a migration notice. +**A:** Open issues are being triaged and migrated as appropriate. For open PRs, we will work with contributors individually. Check the old repo for a migration notice. ### Q: How do I know which files to edit? @@ -390,15 +407,15 @@ npx nx test auth-js --watch - **Old auth-js repo:** `src/GoTrueClient.ts` โ†’ **New:** `packages/core/auth-js/src/GoTrueClient.ts` - **Old supabase-js repo:** `src/SupabaseClient.ts` โ†’ **New:** `packages/core/supabase-js/src/SupabaseClient.ts` -The internal structure of each library is unchanged, just the top-level location changed. +The internal structure of each library is unchanged. Only the top-level location changed. ### Q: Do I need to learn Nx? -**A:** Not really! Basic commands are enough for most contributions. Nx handles the complexity behind the scenes. The main commands you need are `nx build`, `nx test`, and `nx affected`. +**A:** No. Basic commands are enough for most contributions. Nx handles the complexity behind the scenes. The main commands you need are `nx build`, `nx test`, and `nx affected`. ### Q: What about my Git history? -**A:** The Git history from all individual repos has been preserved during the migration. You can still see the history of individual files using: +**A:** The Git history from all individual repos has been preserved during the migration. You can still see the history of individual files: ```bash git log --follow packages/core/auth-js/src/GoTrueClient.ts @@ -406,16 +423,21 @@ git log --follow packages/core/auth-js/src/GoTrueClient.ts ### Q: Can I still install packages individually? -**A:** Yes! End users still install packages individually from npm: +**A:** Yes. **Nothing changed for package users.** Each package is still published independently to npm. The monorepo structure is only for contributor development. + +You can install any package individually: ```bash npm install @supabase/auth-js npm install @supabase/supabase-js +npm install @supabase/storage-js ``` +The monorepo is an internal development tool. It makes it easier for contributors to work across packages. It does not affect package distribution or how you use them. + ### Q: What if I find a bug in the migration? -**A:** Please [open an issue](https://github.com/supabase/supabase-js/issues) and tag it with `migration`. We're actively monitoring these during the transition period. +**A:** [Open an issue](https://github.com/supabase/supabase-js/issues) and tag it with `migration`. We are actively monitoring these during the transition period. ## Getting Help @@ -427,8 +449,8 @@ npm install @supabase/supabase-js ### Resources -- **[CONTRIBUTING.md](./CONTRIBUTING.md)** - Detailed contribution guidelines -- **[README.md](./README.md)** - Repository overview and quick start +- **[CONTRIBUTING.md](../CONTRIBUTING.md)** - Detailed contribution guidelines +- **[README.md](../README.md)** - Repository overview and quick start ### Important Links @@ -444,8 +466,6 @@ npm install @supabase/supabase-js ## Welcome to the Monorepo -This migration represents a significant improvement in our development workflow. While change can be challenging, we believe this new structure will make contributing to Supabase JS libraries more enjoyable and productive. - Thank you for your patience during this transition, and thank you for contributing to Supabase! ๐Ÿ’š -> **Note**: This document will be updated as we learn from the migration process. +> **Note**: We will update this document as we learn from the migration process. From 28aa5ab2c09472f9b075aaa58b32e8a3ab6e5dcf Mon Sep 17 00:00:00 2001 From: Katerina Skroumpelou Date: Thu, 2 Oct 2025 13:21:43 +0300 Subject: [PATCH 4/4] chore(misc): update claude.md Co-authored-by: Stojan Dimitrovski --- CLAUDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index 7ade2eb21..2b42ed756 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -140,7 +140,7 @@ nx test supabase-js --coverage # Test with coverage | Package | Docker Required | Infrastructure | Special Commands | | ------------ | --------------- | ------------------------------- | ---------------- | -| auth-js | โœ… Yes | GoTrue + PostgreSQL | May use `nx test:auth auth-js` | +| auth-js | โœ… Yes | Auth Server + Postgres | May use `nx test:auth auth-js` | | functions-js | โœ… Yes | Deno relay (testcontainers) | Standard `nx test functions-js` | | postgrest-js | โœ… Yes | PostgREST + PostgreSQL | Standard `nx test postgrest-js` | | storage-js | โœ… Yes | Storage API + PostgreSQL + Kong | May use `nx test:storage storage-js` |