fix(plugin-multi-tenant): tenant selector not appearing after login (#15617)

When a custom provider in `admin.components.providers` changes its
wrapper component type on login (e.g. `<Context.Provider>` →
`<Fragment>`), React remounts `TenantSelectionProviderClient`. On
remount, `useState(initialTenantOptions)` gets stale props and
`useRef(userID)` re-initializes so `syncTenants()` never fires, leaving
the tenant selector empty. This only affects projects with a custom
provider that conditionally changes its tree structure based on auth
state - default setups are unaffected since no built-in provider does
this.

The fix adds a `useEffect` that syncs `initialTenantOptions` from the
server component into client state whenever the prop changes, making it
resilient to remounts. Also fixes `test/dev.ts` not forwarding config
overrides to import map generation.

Author: AlessioGr

.github/workflows/e2e.config.ts

@@ -84,6 +84,7 @@ export default createE2EConfig([
   { file: 'plugin-form-builder', shards: 1 },
   { file: 'plugin-import-export', shards: 1 },
   { file: 'plugin-multi-tenant', shards: 2 },
+  { file: 'plugin-multi-tenant#config.conditionalProvider.ts', shards: 1 },
   { file: 'plugin-nested-docs', shards: 1 },
   { file: 'plugin-redirects', shards: 1 },
   { file: 'plugin-seo', shards: 1 },

.github/workflows/main.yml

@@ -588,12 +588,6 @@ jobs:
           # - template: with-vercel-website
           #   database: postgres
 
-    env:
-      POSTGRES_USER: postgres
-      POSTGRES_PASSWORD: postgres
-      POSTGRES_DB: payloadtests
-      MONGODB_VERSION: 6.0
-
     steps:
       - uses: actions/checkout@v5
 
@@ -611,45 +605,20 @@ jobs:
           key: ${{ github.sha }}
           fail-on-cache-miss: true
 
-      - name: Start PostgreSQL
-        uses: CasperWA/postgresql-action@v1.2
-        with:
-          postgresql version: "14" # See https://hub.docker.com/_/postgres for available versions
-          postgresql db: ${{ env.POSTGRES_DB }}
-          postgresql user: ${{ env.POSTGRES_USER }}
-          postgresql password: ${{ env.POSTGRES_PASSWORD }}
-        if: matrix.database == 'postgres'
-
-      - name: Wait for PostgreSQL
-        run: sleep 30
-        if: matrix.database == 'postgres'
-
-      - name: Configure PostgreSQL
-        run: |
-          psql "postgresql://$POSTGRES_USER:$POSTGRES_PASSWORD@localhost:5432/$POSTGRES_DB" -c "CREATE ROLE runner SUPERUSER LOGIN;"
-          psql "postgresql://$POSTGRES_USER:$POSTGRES_PASSWORD@localhost:5432/$POSTGRES_DB" -c "SELECT version();"
-          echo "POSTGRES_URL=postgresql://$POSTGRES_USER:$POSTGRES_PASSWORD@localhost:5432/$POSTGRES_DB" >> $GITHUB_ENV
-        if: matrix.database == 'postgres'
-
-      # Avoid dockerhub rate-limiting
-      - name: Cache Docker images
-        # Use AndreKurait/docker-cache@0.6.0 instead of ScribeMD/docker-cache@0.5.0 to fix the following issue: https://github.com/ScribeMD/docker-cache/issues/837 ("Warning: Failed to restore: Cache service responded with 400")
-        uses: AndreKurait/docker-cache@0.6.0
-        with:
-          key: docker-${{ runner.os }}-mongo-${{ env.MONGODB_VERSION }}
-
-      - name: Start MongoDB
-        uses: supercharge/mongodb-github-action@1.12.0
+      - name: Start database
+        id: db
+        if: matrix.database
+        uses: ./.github/actions/start-database
         with:
-          mongodb-version: 6.0
-        if: matrix.database == 'mongodb'
+          database: ${{ matrix.database }}
 
       - name: Build Template
         run: |
           pnpm run script:pack --dest templates/${{ matrix.template }}
-          pnpm run script:build-template-with-local-pkgs ${{ matrix.template }} $POSTGRES_URL
+          pnpm run script:build-template-with-local-pkgs ${{ matrix.template }} $DB_CONNECTION
         env:
           NODE_OPTIONS: --max-old-space-size=8096
+          DB_CONNECTION: ${{ steps.db.outputs.POSTGRES_URL || steps.db.outputs.MONGODB_URL }}
 
       - name: Store Playwright's Version
         run: |
@@ -678,16 +647,16 @@ jobs:
         env:
           NODE_OPTIONS: --max-old-space-size=8096
           PAYLOAD_DATABASE: ${{ matrix.database }}
-          POSTGRES_URL: ${{ env.POSTGRES_URL }}
-          MONGODB_URL: mongodb://localhost:27017/payloadtests
+          POSTGRES_URL: ${{ steps.db.outputs.POSTGRES_URL }}
+          MONGODB_URL: ${{ steps.db.outputs.MONGODB_URL }}
 
       - name: Runs Template E2E Tests
         run: PLAYWRIGHT_JSON_OUTPUT_NAME=results_${{ matrix.template }}.json pnpm --filter ${{ matrix.template }} test:e2e
         env:
           NODE_OPTIONS: --max-old-space-size=8096
           PAYLOAD_DATABASE: ${{ matrix.database }}
-          POSTGRES_URL: ${{ env.POSTGRES_URL }}
-          MONGODB_URL: mongodb://localhost:27017/payloadtests
+          POSTGRES_URL: ${{ steps.db.outputs.POSTGRES_URL }}
+          MONGODB_URL: ${{ steps.db.outputs.MONGODB_URL }}
           NEXT_TELEMETRY_DISABLED: 1
 
   tests-type-generation:
@@ -783,4 +752,4 @@ jobs:
         if: github.event.pull_request.head.repo.fork == false
         uses: exoego/esbuild-bundle-analyzer@v1
         with:
-          metafiles: "packages/payload/meta_index.json,packages/payload/meta_shared.json,packages/ui/meta_client.json,packages/ui/meta_shared.json,packages/next/meta_index.json,packages/richtext-lexical/meta_client.json"
+          metafiles: 'packages/payload/meta_index.json,packages/payload/meta_shared.json,packages/ui/meta_client.json,packages/ui/meta_shared.json,packages/next/meta_index.json,packages/richtext-lexical/meta_client.json'

.github/workflows/post-release-templates.yml

@@ -48,10 +48,6 @@ jobs:
     permissions:
       contents: write
       pull-requests: write
-    env:
-      POSTGRES_USER: postgres
-      POSTGRES_PASSWORD: postgres
-      POSTGRES_DB: payloadtests
     steps:
       - name: Checkout
         uses: actions/checkout@v5
@@ -60,35 +56,30 @@ jobs:
         uses: ./.github/actions/setup
 
       - name: Start PostgreSQL
-        uses: CasperWA/postgresql-action@v1.2
+        id: postgres
+        uses: ./.github/actions/start-database
         with:
-          postgresql version: '14' # See https://hub.docker.com/_/postgres for available versions
-          postgresql db: ${{ env.POSTGRES_DB }}
-          postgresql user: ${{ env.POSTGRES_USER }}
-          postgresql password: ${{ env.POSTGRES_PASSWORD }}
-
-      - name: Wait for PostgreSQL
-        run: sleep 30
-
-      - name: Configure PostgreSQL
-        run: |
-          psql "postgresql://$POSTGRES_USER:$POSTGRES_PASSWORD@localhost:5432/$POSTGRES_DB" -c "CREATE ROLE runner SUPERUSER LOGIN;"
-          psql "postgresql://$POSTGRES_USER:$POSTGRES_PASSWORD@localhost:5432/$POSTGRES_DB" -c "SELECT version();"
-          echo "POSTGRES_URL=postgresql://$POSTGRES_USER:$POSTGRES_PASSWORD@localhost:5432/$POSTGRES_DB" >> $GITHUB_ENV
-          echo "DATABASE_URL=postgresql://$POSTGRES_USER:$POSTGRES_PASSWORD@localhost:5432/$POSTGRES_DB" >> $GITHUB_ENV
+          database: postgres
 
       - name: Start MongoDB
-        uses: supercharge/mongodb-github-action@1.12.0
+        id: mongodb
+        uses: ./.github/actions/start-database
         with:
-          mongodb-version: 6.0
+          database: mongodb
 
         # The template generation script runs import map generation which needs the built payload bin scripts
       - run: pnpm run build:all
         env:
           DO_NOT_TRACK: 1 # Disable Turbopack telemetry
+          POSTGRES_URL: ${{ steps.postgres.outputs.POSTGRES_URL }}
+          DATABASE_URL: ${{ steps.postgres.outputs.POSTGRES_URL }}
 
       - name: Update template lockfiles and migrations
         run: pnpm script:gen-templates
+        env:
+          POSTGRES_URL: ${{ steps.postgres.outputs.POSTGRES_URL }}
+          DATABASE_URL: ${{ steps.postgres.outputs.POSTGRES_URL }}
+          MONGODB_URL: ${{ steps.mongodb.outputs.MONGODB_URL }}
 
       - name: Commit and push changes
         id: commit

packages/plugin-multi-tenant/src/providers/TenantSelectionProvider/index.client.tsx

@@ -216,6 +216,32 @@ export const TenantSelectionProviderClient = ({
     [syncTenants],
   )
 
+  /**
+   * Sync server-provided tenant options into client state.
+   * When the server component re-renders (e.g., after navigation post-login),
+   * it provides updated initialTenantOptions. Since useState() ignores new
+   * initial values on re-renders, and re-initializes with stale props on
+   * remounts, we sync them explicitly via this effect.
+   */
+  React.useEffect(() => {
+    if (initialTenantOptions.length > 0) {
+      setTenantOptions((prev) => {
+        if (
+          prev.length === initialTenantOptions.length &&
+          prev.every((opt, i) => opt.value === initialTenantOptions[i]?.value)
+        ) {
+          return prev
+        }
+        return initialTenantOptions
+      })
+
+      if (initialTenantOptions.length === 1 && initialTenantOptions[0]) {
+        setSelectedTenantID(initialTenantOptions[0].value)
+        setTenantCookie({ value: String(initialTenantOptions[0].value) })
+      }
+    }
+  }, [initialTenantOptions])
+
   React.useEffect(() => {
     if (userChanged || (initialValue && String(initialValue) !== getTenantCookie())) {
       if (userID) {

test/dev.ts

@@ -70,7 +70,7 @@ await beforeTest()
 
 const { rootDir, adminRoute } = getNextRootDir(testSuiteArg)
 
-await runInit(testSuiteArg, true)
+await runInit(testSuiteArg, true, false, testSuiteConfigOverride)
 
 // This is needed to forward the environment variables to the next process that were created after loadEnv()
 // for example process.env.DATABASE_URL otherwise app.prepare() will clear them

test/plugin-multi-tenant/components/ConditionalWrapperProvider/index.tsx

@@ -0,0 +1,27 @@
+'use client'
+import type React from 'react'
+
+import { useAuth } from '@payloadcms/ui'
+import { createContext } from 'react'
+
+const DummyContext = createContext<null>(null)
+
+/**
+ * This provider changes its rendered tree structure when the user authenticates.
+ * Before login:  <DummyContext.Provider>{children}</DummyContext.Provider>
+ * After login:   <>{children}</>
+ *
+ * This tree structure change causes React to REMOUNT all children,
+ * which is a valid pattern that the multi-tenant plugin must handle.
+ */
+export const ConditionalWrapperProvider: React.FC<{ children: React.ReactNode }> = ({
+  children,
+}) => {
+  const { user } = useAuth()
+
+  if (user) {
+    return <>{children}</>
+  }
+
+  return <DummyContext value={null}>{children}</DummyContext>
+}

test/plugin-multi-tenant/config.base.ts

@@ -0,0 +1,120 @@
+import type { Config } from 'payload'
+
+import { multiTenantPlugin } from '@payloadcms/plugin-multi-tenant'
+import { getTenantFromCookie } from '@payloadcms/plugin-multi-tenant/utilities'
+import { fileURLToPath } from 'node:url'
+import path from 'path'
+const filename = fileURLToPath(import.meta.url)
+const dirname = path.dirname(filename)
+
+import type { Config as ConfigType } from './payload-types.js'
+
+import { AutosaveGlobal } from './collections/AutosaveGlobal.js'
+import { Menu } from './collections/Menu.js'
+import { MenuItems } from './collections/MenuItems.js'
+import { Relationships } from './collections/Relationships.js'
+import { Tenants } from './collections/Tenants.js'
+import { Users } from './collections/Users/index.js'
+import { seed } from './seed/index.js'
+import { autosaveGlobalSlug, menuItemsSlug, menuSlug, notTenantedSlug } from './shared.js'
+
+export const baseConfig: Partial<Config> = {
+  collections: [
+    Tenants,
+    Users,
+    MenuItems,
+    Menu,
+    AutosaveGlobal,
+    Relationships,
+    {
+      slug: notTenantedSlug,
+      admin: {
+        useAsTitle: 'name',
+      },
+      fields: [
+        {
+          name: 'name',
+          type: 'text',
+        },
+      ],
+    },
+  ],
+  admin: {
+    autoLogin: false,
+    importMap: {
+      baseDir: path.resolve(dirname),
+    },
+    components: {
+      beforeLogin: ['/components/BeforeLogin/index.js#BeforeLogin'],
+      graphics: {
+        Logo: '/components/Logo/index.js#Logo',
+        Icon: '/components/Icon/index.js#Icon',
+      },
+    },
+  },
+  onInit: async (payload) => {
+    // IMPORTANT: This should only seed, not clear the database.
+    if (process.env.SEED_IN_CONFIG_ONINIT !== 'false') {
+      await seed(payload)
+    }
+  },
+  plugins: [
+    multiTenantPlugin<ConfigType>({
+      // debug: true,
+      userHasAccessToAllTenants: (user) => Boolean(user.roles?.includes('admin')),
+      useTenantsCollectionAccess: false,
+      tenantField: {
+        access: {},
+      },
+      collections: {
+        [menuItemsSlug]: {
+          useTenantAccess: false,
+        },
+        [menuSlug]: {
+          isGlobal: true,
+        },
+        [autosaveGlobalSlug]: {
+          isGlobal: true,
+        },
+
+        ['relationships']: {},
+      },
+      i18n: {
+        translations: {
+          en: {
+            'field-assignedTenant-label': 'Site',
+            'nav-tenantSelector-label': 'Filter by Site',
+            'assign-tenant-button-label': 'Assign Site',
+          },
+        },
+      },
+    }),
+  ],
+  localization: {
+    defaultLocale: 'en',
+    locales: ['en', 'es', 'fr'],
+    filterAvailableLocales: async ({ locales, req }) => {
+      const tenant = getTenantFromCookie(req.headers, 'text')
+      if (tenant) {
+        const fullTenant = await req.payload.findByID({
+          collection: 'tenants',
+          id: tenant,
+        })
+        if (
+          fullTenant &&
+          Array.isArray(fullTenant.selectedLocales) &&
+          fullTenant.selectedLocales.length > 0
+        ) {
+          if (fullTenant.selectedLocales.includes('allLocales')) {
+            return locales
+          }
+          return locales.filter((locale) => fullTenant.selectedLocales?.includes(locale.code))
+        }
+      }
+      return locales
+    },
+  },
+  typescript: {
+    outputFile: path.resolve(dirname, 'payload-types.ts'),
+  },
+}

test/plugin-multi-tenant/config.conditionalProvider.ts

@@ -0,0 +1,21 @@
+/* eslint-disable no-restricted-exports */
+
+import { buildConfigWithDefaults } from '../buildConfigWithDefaults.js'
+import { baseConfig } from './config.base.js'
+
+/**
+ * Extends the base multi-tenant config with a ConditionalWrapperProvider
+ * that changes its tree structure on auth (Context.Provider → Fragment).
+ * This causes React to remount the TenantSelectionProviderClient subtree,
+ * exercising the RSC prop sync fix.
+ */
+export default buildConfigWithDefaults({
+  ...baseConfig,
+  admin: {
+    ...baseConfig.admin,
+    components: {
+      ...baseConfig.admin?.components,
+      providers: ['/components/ConditionalWrapperProvider/index.js#ConditionalWrapperProvider'],
+    },
+  },
+})