feat: adds multi-tenant plugin (#10447)

### Multi Tenant Plugin
This PR adds a `@payloadcms/plugin-multi-tenant` package. The goal is to
consolidate a source of truth for multi-tenancy. Currently we are
maintaining different implementations for clients, users in discord and
our examples repo. When updates or new paradigms arise we need to
communicate this with everyone and update code examples which is hard to
maintain.

### What does it do?
- adds a tenant selector to the sidebar, above the nav links
- adds a hidden tenant field to every collection that you specify
- adds an array field to your users collection, allowing you to assign
users to tenants
- by default combines the access control (to enabled collections) that
you define, with access control based on the tenants assigned to user on
the request
- by default adds a baseListFilter that filters the documents shown in
the list view with the selected tenant in the admin panel

### What does it not do?
- it does not implement multi-tenancy for your frontend. You will need
to query data for specific tenants to build your website/application
- it does not add a tenants collection, you **NEED** to add a tenants
collection, where you can define what types of fields you would like on
it

### The plugin config

Most of the options listed below are _optional_, but it is easier to
just lay out all of the configuration options.

**TS Type**
```ts
type MultiTenantPluginConfig<ConfigTypes = unknown> = {
  /**
   * After a tenant is deleted, the plugin will attempt to clean up related documents
   * - removing documents with the tenant ID
   * - removing the tenant from users
   *
   * @default true
   */
  cleanupAfterTenantDelete?: boolean
  /**
   * Automatically
   */
  collections: {
    [key in CollectionSlug]?: {
      /**
       * Set to `true` if you want the collection to behave as a global
       *
       * @default false
       */
      isGlobal?: boolean
      /**
       * Set to `false` if you want to manually apply the baseListFilter
       *
       * @default true
       */
      useBaseListFilter?: boolean
      /**
       * Set to `false` if you want to handle collection access manually without the multi-tenant constraints applied
       *
       * @default true
       */
      useTenantAccess?: boolean
    }
  }
  /**
   * Enables debug mode
   * - Makes the tenant field visible in the admin UI within applicable collections
   *
   * @default false
   */
  debug?: boolean
  /**
   * Enables the multi-tenant plugin
   *
   * @default true
   */
  enabled?: boolean
  /**
   * Field configuration for the field added to all tenant enabled collections
   */
  tenantField?: {
    access?: RelationshipField['access']
    /**
     * The name of the field added to all tenant enabled collections
     *
     * @default 'tenant'
     */
    name?: string
  }
  /**
   * Field configuration for the field added to the users collection
   *
   * If `includeDefaultField` is `false`, you must include the field on your users collection manually
   * This is useful if you want to customize the field or place the field in a specific location
   */
  tenantsArrayField?:
    | {
        /**
         * Access configuration for the array field
         */
        arrayFieldAccess?: ArrayField['access']
        /**
         * When `includeDefaultField` is `true`, the field will be added to the users collection automatically
         */
        includeDefaultField?: true
        /**
         * Additional fields to include on the tenants array field
         */
        rowFields?: Field[]
        /**
         * Access configuration for the tenant field
         */
        tenantFieldAccess?: RelationshipField['access']
      }
    | {
        arrayFieldAccess?: never
        /**
         * When `includeDefaultField` is `false`, you must include the field on your users collection manually
         */
        includeDefaultField?: false
        rowFields?: never
        tenantFieldAccess?: never
      }
  /**
   * The slug for the tenant collection
   *
   * @default 'tenants'
   */
  tenantsSlug?: string
  /**
   * Function that determines if a user has access to _all_ tenants
   *
   * Useful for super-admin type users
   */
  userHasAccessToAllTenants?: (
    user: ConfigTypes extends { user: User } ? ConfigTypes['user'] : User,
  ) => boolean
}
```

**Example usage**
```ts
import type { Config } from './payload-types'
import { buildConfig } from 'payload'

export default buildConfig({
  plugins: [
    multiTenantPlugin<Config>({
      collections: {
        pages: {},
      },
      userHasAccessToAllTenants: (user) => isSuperAdmin(user),
    }),
  ],
})
```


### How to configure Collections as Globals for multi-tenant

When using multi-tenant, globals need to actually be configured as
collections so the content can be specific per tenant.
To do that, you can mark a collection with `isGlobal` and it will behave
like a global and users will not see the list view.

```ts
multiTenantPlugin({
  collections: {
    navigation: {
      isGlobal: true,
    },
  },
})
```

Author: JarrodMFlesch

docs/plugins/multi-tenant.mdx

@@ -0,0 +1,254 @@
+---
+title: Multi-Tenant Plugin
+label: Multi-Tenant
+order: 40
+desc: Scaffolds multi-tenancy for your Payload application
+keywords: plugins, multi-tenant, multi-tenancy, plugin, payload, cms, seo, indexing, search, search engine
+---
+
+[![npm](https://img.shields.io/npm/v/@payloadcms/plugin-multi-tenants)](https://www.npmjs.com/package/@payloadcms/plugin-multi-tenants)
+
+This plugin sets up multi-tenancy for your application from within your [Admin Panel](../admin/overview). It does so by adding a `tenant` field to all specified collections. Your front-end application can then query data by tenant. You must add the Tenants collection so you control what fields are available for each tenant.
+
+
+<Banner type="info">
+  This plugin is completely open-source and the [source code can be found
+  here](https://github.com/payloadcms/payload/tree/main/packages/plugin-multi-tenant). If you need
+  help, check out our [Community Help](https://payloadcms.com/community-help). If you think you've
+  found a bug, please [open a new
+  issue](https://github.com/payloadcms/payload/issues/new?assignees=&labels=plugin%3A%multi-tenant&template=bug_report.md&title=plugin-multi-tenant%3A)
+  with as much detail as possible.
+</Banner>
+
+## Core features
+
+- Adds a `tenant` field to each specified collection
+- Adds a tenant selector to the admin panel, allowing you to switch between tenants
+- Filters list view results by selected tenant
+
+## Installation
+
+Install the plugin using any JavaScript package manager like [pnpm](https://pnpm.io), [npm](https://npmjs.com), or [Yarn](https://yarnpkg.com):
+
+```bash
+  pnpm add @payloadcms/plugin-multi-tenant@beta
+```
+
+### Options
+
+The plugin accepts an object with the following properties:
+
+```ts
+type MultiTenantPluginConfig<ConfigTypes = unknown> = {
+  /**
+   * After a tenant is deleted, the plugin will attempt to clean up related documents
+   * - removing documents with the tenant ID
+   * - removing the tenant from users
+   *
+   * @default true
+   */
+  cleanupAfterTenantDelete?: boolean
+  /**
+   * Automatically
+   */
+  collections: {
+    [key in CollectionSlug]?: {
+      /**
+       * Set to `true` if you want the collection to behave as a global
+       *
+       * @default false
+       */
+      isGlobal?: boolean
+      /**
+       * Set to `false` if you want to manually apply the baseListFilter
+       *
+       * @default true
+       */
+      useBaseListFilter?: boolean
+      /**
+       * Set to `false` if you want to handle collection access manually without the multi-tenant constraints applied
+       *
+       * @default true
+       */
+      useTenantAccess?: boolean
+    }
+  }
+  /**
+   * Enables debug mode
+   * - Makes the tenant field visible in the admin UI within applicable collections
+   *
+   * @default false
+   */
+  debug?: boolean
+  /**
+   * Enables the multi-tenant plugin
+   *
+   * @default true
+   */
+  enabled?: boolean
+  /**
+   * Field configuration for the field added to all tenant enabled collections
+   */
+  tenantField?: {
+    access?: RelationshipField['access']
+    /**
+     * The name of the field added to all tenant enabled collections
+     *
+     * @default 'tenant'
+     */
+    name?: string
+  }
+  /**
+   * Field configuration for the field added to the users collection
+   *
+   * If `includeDefaultField` is `false`, you must include the field on your users collection manually
+   * This is useful if you want to customize the field or place the field in a specific location
+   */
+  tenantsArrayField?:
+    | {
+        /**
+         * Access configuration for the array field
+         */
+        arrayFieldAccess?: ArrayField['access']
+        /**
+         * When `includeDefaultField` is `true`, the field will be added to the users collection automatically
+         */
+        includeDefaultField?: true
+        /**
+         * Additional fields to include on the tenants array field
+         */
+        rowFields?: Field[]
+        /**
+         * Access configuration for the tenant field
+         */
+        tenantFieldAccess?: RelationshipField['access']
+      }
+    | {
+        arrayFieldAccess?: never
+        /**
+         * When `includeDefaultField` is `false`, you must include the field on your users collection manually
+         */
+        includeDefaultField?: false
+        rowFields?: never
+        tenantFieldAccess?: never
+      }
+  /**
+   * The slug for the tenant collection
+   *
+   * @default 'tenants'
+   */
+  tenantsSlug?: string
+  /**
+   * Function that determines if a user has access to _all_ tenants
+   *
+   * Useful for super-admin type users
+   */
+  userHasAccessToAllTenants?: (
+    user: ConfigTypes extends { user } ? ConfigTypes['user'] : User,
+  ) => boolean
+}
+```
+
+## Basic Usage
+
+In the `plugins` array of your [Payload Config](https://payloadcms.com/docs/configuration/overview), call the plugin with [options](#options):
+
+```ts
+import { buildConfig } from 'payload'
+import { multiTenantPlugin } from '@payloadcms/plugin-multi-tenant'
+import type { Config } from './payload-types'
+
+const config = buildConfig({
+  collections: [
+    {
+      slug: 'tenants',
+      admin: {
+        useAsTitle: 'name'
+      }
+      fields: [
+        // remember, you own these fields
+        // these are merely suggestions/examples
+        {
+        name: 'name',
+        type: 'text',
+        required: true,
+        },
+        {
+          name: 'slug',
+          type: 'text',
+          required: true,
+        },
+        {
+          name: 'domain',
+          type: 'text',
+          required: true,
+        }
+      ],
+    },
+  ],
+  plugins: [
+    multiTenantPlugin<Config>({
+      collections: {
+        pages: {},
+        navigation: {
+          isGlobal: true,
+        }
+      },
+    }),
+  ],
+})
+
+export default config
+```
+
+## Front end usage
+
+The plugin scaffolds out everything you will need to separate data by tenant. You can use the `tenant` field to filter data from enabled collections in your front-end application.
+
+
+In your frontend you can query and constrain data by tenant with the following:
+
+```tsx
+const pagesBySlug = await payload.find({
+  collection: 'pages',
+  depth: 1,
+  draft: false,
+  limit: 1000,
+  overrideAccess: false,
+  where: {
+    // your constraint would depend on the
+    // fields you added to the tenants collection
+    // here we are assuming a slug field exists
+    // on the tenant collection, like in the example above
+    'tenant.slug': {
+      equals: 'gold',
+    },
+  },
+})
+```
+
+### NextJS rewrites
+
+Using NextJS rewrites and this route structure `/[tenantDomain]/[slug]`, we can rewrite routes specifically for domains requested:
+
+```ts
+async rewrites() {
+  return [
+    {
+      source: '/((?!admin|api)):path*',
+      destination: '/:tenantDomain/:path*',
+      has: [
+        {
+          type: 'host',
+          value: '(?<tenantDomain>.*)',
+        },
+      ],
+    },
+  ];
+}
+```
+
+
+## Examples
+
+The [Examples Directory](https://github.com/payloadcms/payload/tree/main/examples) also contains an official [Multi-Tenant](https://github.com/payloadcms/payload/tree/main/examples/multi-tenant) example.

examples/multi-tenant/README.md

@@ -40,9 +40,13 @@ See the [Collections](https://payloadcms.com/docs/configuration/collections) doc
 
   **Domain-based Tenant Setting**:
 
-  This example also supports domain-based tenant selection, where tenants can be associated with specific domains. If a tenant is associated with a domain (e.g., `abc.localhost.com:3000`), when a user logs in from that domain, they will be automatically scoped to the matching tenant. This is accomplished through an optional `afterLogin` hook that sets a `payload-tenant` cookie based on the domain.
+  This example also supports domain-based tenant selection, where tenants can be associated with a specific domain. If a tenant is associated with a domain (e.g., `gold.localhost.com:3000`), when a user logs in from that domain, they will be automatically scoped to the matching tenant. This is accomplished through an optional `afterLogin` hook that sets a `payload-tenant` cookie based on the domain.
 
-  By default, this functionality is commented out in the code but can be enabled easily. See the `setCookieBasedOnDomain` hook in the `Users` collection for more details.
+  The seed script seeds 3 tenants, for the domain portion of the example to function properly you will need to add the following entries to your systems `/etc/hosts` file:
+
+  - gold.localhost.com:3000
+  - silver.localhost.com:3000
+  - bronze.localhost.com:3000
 
 - #### Pages
 

examples/multi-tenant/next.config.mjs

@@ -3,6 +3,20 @@ import { withPayload } from '@payloadcms/next/withPayload'
 /** @type {import('next').NextConfig} */
 const nextConfig = {
   // Your Next.js config here
+  async rewrites() {
+    return [
+      {
+        source: '/((?!admin|api))tenant-domains/:path*',
+        destination: '/tenant-domains/:tenant/:path*',
+        has: [
+          {
+            type: 'host',
+            value: '(?<tenant>.*)',
+          },
+        ],
+      },
+    ]
+  },
 }
 
 export default withPayload(nextConfig)

examples/multi-tenant/package.json

@@ -18,6 +18,7 @@
   "dependencies": {
     "@payloadcms/db-mongodb": "latest",
     "@payloadcms/next": "latest",
+    "@payloadcms/plugin-multi-tenant": "file:payloadcms-plugin-multi-tenant-3.15.1.tgz",
     "@payloadcms/richtext-lexical": "latest",
     "@payloadcms/ui": "latest",
     "cross-env": "^7.0.3",