feat: publish SSR under deprecated auth-helpers package names (#127)

## What kind of change does this PR introduce?

Feature - Package consolidation and multi-package publishing

## What is the current behavior?

Currently, `@supabase/ssr` is only published under its own package name.
Meanwhile, the deprecated `@supabase/auth-helpers-*` packages continue
to receive thousands of weekly downloads, probably due to LLMs
recommending them in code suggestions despite being deprecated for a
long time.

The deprecated packages:
- `@supabase/auth-helpers-nextjs` (159k weekly downloads)
- `@supabase/auth-helpers-react`
- `@supabase/auth-helpers-remix`
- `@supabase/auth-helpers-sveltekit`

## What is the new behavior?

This PR enables `@supabase/ssr` to be published under multiple package
names simultaneously:

1. **Multi-package publishing**: The release workflow now publishes the
same codebase under 5 different npm package names:
   - `@supabase/ssr` (primary package)
   - `@supabase/auth-helpers-nextjs`
   - `@supabase/auth-helpers-react`
   - `@supabase/auth-helpers-remix`
   - `@supabase/auth-helpers-sveltekit`

2. **Console warnings**: When imported as a deprecated auth-helpers
package, users see a prominent warning.

3. **Updated documentation**: README clearly explains the package
consolidation and lists all deprecated packages.

## Additional context

Users of the old auth-helpers packages will experience breaking changes
when updating, as the APIs are not backward compatible. This is
intentional - as discussed internally, we want to "break it loudly" to
force users to notice and migrate.

**Why this approach?**
- LLMs continue to recommend deprecated packages despite deprecation
warnings
- Traditional deprecation methods have proven ineffective
- Publishing SSR under the old names ensures users get the maintained,
working code
- Console warnings guide users to the correct package

Related: supabase/auth-helpers#811

Author: mandarini

.github/workflows/release.yml

@@ -120,6 +120,33 @@ jobs:
 
           npm publish --provenance --tag "$DIST_TAG"
 
+          # Also publish under deprecated auth-helpers names for backward compatibility
+          # This helps users still using the old packages (especially due to LLM recommendations)
+          echo "Publishing under legacy auth-helpers names..."
+
+          # Publish as @supabase/auth-helpers-nextjs
+          echo "Publishing as @supabase/auth-helpers-nextjs..."
+          sed -i 's|"name": "@supabase/ssr"|"name": "@supabase/auth-helpers-nextjs"|g' package.json
+          npm publish --provenance --tag "$DIST_TAG"
+
+          # Publish as @supabase/auth-helpers-react
+          echo "Publishing as @supabase/auth-helpers-react..."
+          sed -i 's|"name": "@supabase/auth-helpers-nextjs"|"name": "@supabase/auth-helpers-react"|g' package.json
+          npm publish --provenance --tag "$DIST_TAG"
+
+          # Publish as @supabase/auth-helpers-remix
+          echo "Publishing as @supabase/auth-helpers-remix..."
+          sed -i 's|"name": "@supabase/auth-helpers-react"|"name": "@supabase/auth-helpers-remix"|g' package.json
+          npm publish --provenance --tag "$DIST_TAG"
+
+          # Publish as @supabase/auth-helpers-sveltekit
+          echo "Publishing as @supabase/auth-helpers-sveltekit..."
+          sed -i 's|"name": "@supabase/auth-helpers-remix"|"name": "@supabase/auth-helpers-sveltekit"|g' package.json
+          npm publish --provenance --tag "$DIST_TAG"
+
+          # Restore original package name for consistency
+          sed -i 's|"name": "@supabase/auth-helpers-sveltekit"|"name": "@supabase/ssr"|g' package.json
+
       - name: Create GitHub release and branches
         if: ${{ steps.release.outputs.release_created == 'true' || steps.release.outputs.prs_created == 'true' }}
         run: |

README.md

@@ -1,8 +1,28 @@
 # Supabase clients for use in SSR frameworks
 
-This package is useful for using the [Supabase JavaScript library](https://supabase.com/docs/reference/javascript/introduction) in
-server-side rendering frameworks.
+> **Package Consolidation Notice**: This package replaces the deprecated `@supabase/auth-helpers-*` packages. All framework-specific auth-helpers packages have been consolidated into `@supabase/ssr` for better maintenance and consistency.
 
-It provides a framework-agnostic way of creating a Supabase client.
+## Overview
+
+This package provides a framework-agnostic way to use the [Supabase JavaScript library](https://supabase.com/docs/reference/javascript/introduction) in server-side rendering (SSR) frameworks.
+
+## Installation
+
+```bash
+npm i @supabase/ssr
+```
+
+## Deprecated Packages
+
+The following packages have been deprecated and consolidated into `@supabase/ssr`:
+
+- `@supabase/auth-helpers-nextjs` → Use `@supabase/ssr`
+- `@supabase/auth-helpers-react` → Use `@supabase/ssr`
+- `@supabase/auth-helpers-remix` → Use `@supabase/ssr`
+- `@supabase/auth-helpers-sveltekit` → Use `@supabase/ssr`
+
+If you're currently using any of these packages, please update your dependencies to use `@supabase/ssr` directly.
+
+## Documentation
 
 Please refer to the [official server-side rendering guides](https://supabase.com/docs/guides/auth/server-side) for the latest best practices on using this package in your SSR framework of choice.

package-lock.json

@@ -34,6 +34,7 @@
   "devDependencies": {
     "@eslint/js": "^9.3.0",
     "@supabase/supabase-js": "^2.43.4",
+    "@types/node": "^24.3.0",
     "@vitest/coverage-v8": "^1.6.0",
     "eslint": "^8.57.0",
     "prettier": "^3.2.5",

package.json

@@ -1,3 +1,36 @@
+// Check if this package is being used as one of the deprecated auth-helpers packages
+if (typeof process !== "undefined" && process.env?.npm_package_name) {
+  const packageName = process.env.npm_package_name;
+  const deprecatedPackages = [
+    "@supabase/auth-helpers-nextjs",
+    "@supabase/auth-helpers-react",
+    "@supabase/auth-helpers-remix",
+    "@supabase/auth-helpers-sveltekit",
+  ];
+
+  if (deprecatedPackages.includes(packageName)) {
+    console.warn(`
+╔════════════════════════════════════════════════════════════════════════════╗
+║ ⚠️  IMPORTANT: Package Consolidation Notice                                ║
+║                                                                            ║
+║ The ${packageName.padEnd(35)} package name is deprecated.  ║
+║                                                                            ║
+║ You are now using @supabase/ssr - a unified solution for all frameworks.  ║
+║                                                                            ║
+║ The auth-helpers packages have been consolidated into @supabase/ssr       ║
+║ to provide better maintenance and consistent APIs across frameworks.      ║
+║                                                                            ║
+║ Please update your package.json to use @supabase/ssr directly:            ║
+║   npm uninstall ${packageName.padEnd(42)} ║
+║   npm install @supabase/ssr                                               ║
+║                                                                            ║
+║ For more information, visit:                                              ║
+║ https://supabase.com/docs/guides/auth/server-side                         ║
+╚════════════════════════════════════════════════════════════════════════════╝
+    `);
+  }
+}
+
 export * from "./createBrowserClient";
 export * from "./createServerClient";
 export * from "./types";