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/.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..2b42ed756 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 @@ -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 | 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` | +| 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** @@ -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 @@ -316,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 @@ -487,10 +485,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 +641,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 @@ -741,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/CONTRIBUTING.md b/CONTRIBUTING.md index 0bd060946..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 @@ -56,7 +60,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 +190,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 +287,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..877c4b098 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,38 @@ -# Supabase JS Client Libraries +
+

+ + + + + Supabase Logo + + + +

Supabase JS Client Libraries

+ +

+ Guides + · + Reference Docs +

+

-_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) -> **📣 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. +
+ +> **For contributors: 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/` | +> | Other libraries | `packages/core/*/` | +> +> Read the **[Migration Guide](./docs/MIGRATION.md)** to learn more. ## 📦 Libraries @@ -17,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 b353491cb..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 @@ -256,14 +257,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 +344,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 +490,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` @@ -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 dbb220c81..e8b243461 100644 --- a/docs/MIGRATION.md +++ b/docs/MIGRATION.md @@ -1,6 +1,89 @@ -# 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. +> **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 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 + +**Not a contributor?** You can skip this guide. Packages are still installed and used the same way. + +## ⚠️ What Changed: The Big Picture + +### The Repository URL Stayed the Same, But Everything Inside Changed + +The repository is still at `github.com/supabase/supabase-js`. + +**OLD Structure:** + +```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/`. 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 @@ -15,7 +98,7 @@ ## 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 @@ -33,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 @@ -143,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" @@ -174,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 @@ -213,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 @@ -263,8 +335,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 @@ -285,13 +357,35 @@ npx nx run-many --target=docs --all ## FAQ +### Q: I contributed to the old supabase-js repo. Where did my code go? + +**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: + +- **Old:** `src/SupabaseClient.ts` +- **New:** `packages/core/supabase-js/src/SupabaseClient.ts` + +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:** What happened: + +- The `supabase-js` **repository URL** stayed the same (`github.com/supabase/supabase-js`) +- All libraries (including supabase-js itself) moved into a `packages/core/` structure +- Other library repositories (`auth-js`, `postgrest-js`, etc.) were archived +- The repository now contains all libraries, but supabase-js code also relocated + +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 @@ -304,19 +398,24 @@ 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? -**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. 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 @@ -324,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 @@ -345,25 +449,23 @@ 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 -- **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 + - + - + - + - + - --- ## 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. 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' } )