Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Revert developer docs changes; keep docs/plans
Łukasz Adamczyk9830f33af4a9
diff --git a/docs/developer/admin/admin.mdx b/docs/developer/admin/admin.mdxindex f088d686fb..0dfec62954 100644--- a/docs/developer/admin/admin.mdx+++ b/docs/developer/admin/admin.mdx@@ -201,7 +201,7 @@ bin/rails g controller Spree::Admin::Brands --skip-routesAdmin users must be authenticated to access the dashboard. Spree supports:-- Built-in `has_secure_password` authentication (the gem-owned `Spree::AdminUser` model)+- Built-in Devise authentication- Custom authentication adapters- SSO integrationdiff --git a/docs/developer/admin/authentication.mdx b/docs/developer/admin/authentication.mdxindex e558d7d619..da3f518cb1 100644--- a/docs/developer/admin/authentication.mdx+++ b/docs/developer/admin/authentication.mdx@@ -1,32 +1,59 @@---title: Admin Panel AuthenticationsidebarTitle: Authentication-description: How to customize authentication for the Spree admin+description: How to customize the Spree admin panel authentication----Spree uses a separate model for admin/staff accounts (`Spree::AdminUser`) from storefront customers (`Spree::Customer`) — the default since Spree 5.2. Both are gem-owned and backed by [`has_secure_password`](https://api.rubyonrails.org/classes/ActiveModel/SecurePassword/ClassMethods.html); the admin dashboard authenticates against the Admin API with JWT access + refresh tokens, so no setup is required for the default.+Spree allows you to use a different model for the admin panel than the storefront (that's the default since Spree 5.2).+Here you can find how to customize the admin panel authentication to use a different model.-You only need the steps below if you want the admin to authenticate against your **own** admin model.+Let's assume you have an existing `AdminUser` model in your application and you're using Devise for authentication.-## Using your own admin model--Point `Spree.admin_user_class` at your model in `config/initializers/spree.rb`:+In `config/initializers/spree.rb` file, add the following line:```ruby-Spree.admin_user_class = 'MyApp::AdminUser'+Spree.admin_user_class = 'AdminUser'```-On that model, include the admin concern (roles, permissions, store access) and add `has_secure_password`:+This will tell Spree to use your `AdminUser` model for the admin panel. You will also need to add the following line in that model file:```ruby-# app/models/my_app/admin_user.rb-class MyApp::AdminUser < ApplicationRecord- has_secure_password validations: false+include Spree::UserMethods+```- include Spree::AdminUserMethods+In your `config/initializers/routes.rb` file, you will need to define devise routes for the 2nd model:++```ruby+Spree::Core::Engine.routes.prepend_routes do+ # Admin authentication+ devise_for(+ Spree.admin_user_class.model_name.singular_route_key,+ class_name: Spree.admin_user_class.to_s,+ controllers: {+ sessions: 'spree/admin/user_sessions',+ passwords: 'spree/admin/user_passwords'+ },+ skip: :registrations,+ path: :admin_user,+ router_name: :spree+ )end```-If the model keeps an existing password column (for example `encrypted_password`), bridge it as described in [Authentication](/developer/customization/authentication#keeping-an-existing-password-column).+And now in your `lib/spree/authentication_helpers.rb` file, please replace the following lines:++```diff+ def spree_admin_login_path(opts = {})+- spree_login_path(opts)++ new_admin_user_session_path(opts)+ end++ def spree_admin_logout_path(opts = {})+- spree_logout_path(opts)++ destroy_admin_user_session_path(opts)+ end+```++Now when attempting to access the admin panel, you will be redirected to the dedicated admin panel login page.-The admin dashboard signs in through the Admin API auth endpoints (`POST /api/v3/admin/auth/login`, plus `refresh` and `logout`); custom providers plug in via `Spree.admin_authentication_strategies` (see [Custom authentication providers](/developer/customization/authentication#custom-authentication-providers)).+\ No newline at end of filediff --git a/docs/developer/admin/extending-ui.mdx b/docs/developer/admin/extending-ui.mdxindex 303a33e90f..a2a8923049 100644--- a/docs/developer/admin/extending-ui.mdx+++ b/docs/developer/admin/extending-ui.mdx@@ -431,7 +431,7 @@ Here's a list of all places you can inject your custom code:#### Variables- <ParamField path="user" type="Spree.customer_class">+ <ParamField path="user" type="Spree.user_class">The customer displayed on the page.</ParamField>diff --git a/docs/developer/admin/tables.mdx b/docs/developer/admin/tables.mdxindex 5af38da200..92b3252035 100644--- a/docs/developer/admin/tables.mdx+++ b/docs/developer/admin/tables.mdx@@ -501,7 +501,7 @@ Spree registers tables for all built-in resources:| `:products` | `Spree::Product` || `:orders` | `Spree::Order` || `:checkouts` | `Spree::Order` (draft) |-| `:users` | `Spree.customer_class` |+| `:users` | `Spree.user_class` || `:promotions` | `Spree::Promotion` || `:customer_returns` | `Spree::CustomerReturn` || `:option_types` | `Spree::OptionType` |diff --git a/docs/developer/advanced/adding_spree_to_rails_app.mdx b/docs/developer/advanced/adding_spree_to_rails_app.mdxindex 198578994a..50a9d17b17 100644--- a/docs/developer/advanced/adding_spree_to_rails_app.mdx+++ b/docs/developer/advanced/adding_spree_to_rails_app.mdx@@ -38,20 +38,19 @@ Spree uses a modular installation approach. First install the core, then add opt### Install core Spree-This installs core models, API, CLI, and the gem-owned authentication models (`Spree::Customer` and `Spree::AdminUser`):+This installs core models, API, CLI, and authentication:```bash-bin/rails g spree:install+bin/rails g spree:install --user_class=Spree::User --authentication=devise```-To authenticate against your own user model instead of the defaults, pass `--user_class` (see [Authentication](/developer/customization/authentication)).-**Core installation options:**| Option | Description ||--------|-------------|-| `user_class` | The customer model class (default: `Spree::Customer`) |-| `admin_user_class` | The admin model class (default: `Spree::AdminUser`) |+| `user_class` | The class for your users, eg. `Spree::User` or `User` |+| `admin_user_class` | The class for admin users (defaults to `user_class`) |+| `authentication` | Authentication gem: `devise` or `custom` || `migrate` | Whether to run migrations (default: true) || `seed` | Whether to run the seed file (default: true) || `sample` | Whether to add sample data (default: false) |@@ -62,6 +61,7 @@ To authenticate against your own user model instead of the defaults, pass `--use```bashbin/rails g spree:admin:install+bin/rails g spree:admin:devise # if using Devise authentication```### Add sample data (optional)diff --git a/docs/developer/core-concepts/events.mdx b/docs/developer/core-concepts/events.mdxindex a02d777ead..cb06b4b4d3 100644--- a/docs/developer/core-concepts/events.mdx+++ b/docs/developer/core-concepts/events.mdx@@ -256,7 +256,7 @@ Models with lifecycle events enabled include: `Order`, `Payment`, `Price`, `Ship| `user.updated` | User was updated || `user.deleted` | User was deleted |-When `Spree.admin_user_class` differs from `Spree.customer_class`, admin users publish the equivalent `admin.*` events (see the Admin Events table below).+When `Spree.admin_user_class` differs from `Spree.user_class`, admin users publish the equivalent `admin.*` events (see the Admin Events table below).### Admin Eventsdiff --git a/docs/developer/core-concepts/imports-exports.mdx b/docs/developer/core-concepts/imports-exports.mdxindex e0f8775ffa..2c9d83454f 100644--- a/docs/developer/core-concepts/imports-exports.mdx+++ b/docs/developer/core-concepts/imports-exports.mdx@@ -472,7 +472,7 @@ module Spreedef find_or_create_useremail = attributes['email'].strip.downcase- Spree.customer_class.find_or_create_by!(email: email)+ Spree.user_class.find_or_create_by!(email: email)enddef find_plandiff --git a/docs/developer/core-concepts/users.mdx b/docs/developer/core-concepts/users.mdxindex 20c4bd1825..05a6ec8d24 100644--- a/docs/developer/core-concepts/users.mdx+++ b/docs/developer/core-concepts/users.mdx@@ -1,6 +1,6 @@---title: Users-description: How Spree models customer and admin users — account data, roles, abilities, and access permissions across stores.+description: How Spree models customer and admin users — Devise authentication, account data, roles, abilities, and access permissions across stores.---## Overview@@ -12,11 +12,11 @@ Spree has two separate user types:| User type | Class | Default ||-----------|-------|---------|-| Customers | `Spree.customer_class` | `Spree::Customer` |+| Customers | `Spree.user_class` | `Spree::User` || Admins | `Spree.admin_user_class` | `Spree::AdminUser` |<Info>-You can use your own user classes. See the [Customize Authentication guide](/developer/customization/authentication) for details. `Spree.user_class` still works as a deprecated alias for `Spree.customer_class` and will be removed in Spree 6.1.+You can use your own user classes. See the [Customize Authentication guide](/developer/customization/authentication) for details.</Info>## Customersdiff --git a/docs/developer/customization/authentication.mdx b/docs/developer/customization/authentication.mdxindex b60f79eebd..ae7bb11d99 100644--- a/docs/developer/customization/authentication.mdx+++ b/docs/developer/customization/authentication.mdx@@ -1,54 +1,103 @@---title: Authentication-description: How Spree authenticates customers and admins, and how to plug in your own user model or authentication provider.+description: Integrate Spree with a custom authentication setup, including Devise, an existing user model, OmniAuth providers, and JWT or OAuth API tokens.version: v5----Spree ships with built-in, gem-owned authentication models — `Spree::Customer` (storefront customers) and `Spree::AdminUser` (staff) — backed by Rails' [`has_secure_password`](https://api.rubyonrails.org/classes/ActiveModel/SecurePassword/ClassMethods.html). If you installed Spree following the [Quickstart guide](/developer/quickstart), authentication is already set up and you can skip this page.+If you installed Spree following the [Quickstart guide](/developer/quickstart), you can completely skip this step - you are all set and integrated with the [Devise](https://github.com/plataformatec/devise) gem.-You only need the steps below if you want Spree to authenticate against your **own** user model — for example a shared/SSO user table, or an existing application you're adding Spree to.+However if you're adding Spree to an existing application that has its own authentication system, you will need to follow these steps.-## Using your own user model+## Using Devise-Point `Spree.customer_class` (and optionally `Spree.admin_user_class`) at your model in `config/initializers/spree.rb`:+If you're currently using [Devise](https://github.com/plataformatec/devise) for authentication, you can follow the steps below to integrate Spree with your existing authentication system.++Firstly set your `User` class as `Spree.user_class` in your `config/initializers/spree.rb` file:```ruby-Spree.customer_class = 'MyApp::User'+Spree.user_class = 'User'+```++Now, run the generator to set up Spree integration with Devise:++<CodeGroup>++```bash Spree CLI (Docker)+spree generate spree:authentication:devise+```++```bash Without Spree CLI+bin/rails g spree:authentication:devise```-> `Spree.user_class` still works as a deprecated alias for `Spree.customer_class` and will be removed in Spree 6.1.+</CodeGroup>-On that model, include the Spree customer concern — a single include that brings in addresses, payment sources, orders, wishlists, and store credit — and add `has_secure_password`:+This will create a new file in `lib/spree/authentication_helpers.rb` that serves as a bridge between Spree and your existing authentication system routes. You can then use this file to customize the routes to your liking. It should automatically pick up standard Devise routes.++Secondly, this generator will add necessary modules to your `User` model.```ruby-# app/models/my_app/user.rb-class MyApp::User < ApplicationRecord- has_secure_password validations: false+# app/models/user.rb+class User < ApplicationRecord+ # ... your existing code ...- include Spree::CustomerMethods+ include Spree::UserAddress+ include Spree::UserMethods+ include Spree::UserPaymentSourceend```-`Spree::CustomerMethods` absorbs the former `Spree::UserAddress` and `Spree::UserPaymentSource` concerns, so this single include is all that's required.+This will ensure that your `User` model can be used as a Spree user.++This generator will also add 2 new lines to your Spree initializer file:++```ruby+Devise.parent_controller = "Spree::BaseController"+Devise.parent_mailer = "Spree::BaseMailer"+```++This ensures that Devise will use Spree storefront layout for login/signup/etc and use Spree mailer layout for sending emails so they'll match your Storefront branding.-### Keeping an existing password column+If you have more complex setup, you can remove these lines and customize the routes and mailer in your own initializer file.-If your model already stores its password digest in a column other than `password_digest` — for example the `encrypted_password` column from a Devise-based app — bridge it so `has_secure_password` can read it. Either alias the column:+## Using Custom Authentication++If you're using a custom authentication system, you can follow the steps below to integrate Spree with your existing authentication system.++Firstly set your `User` class as `Spree.user_class` in your `config/initializers/spree.rb` file:```ruby-class MyApp::User < ApplicationRecord- has_secure_password validations: false- include Spree::CustomerMethods+Spree.user_class = 'User'+```- alias_attribute :password_digest, :encrypted_password-end+Now, run the generator to set up Spree integration with your custom authentication system:++<CodeGroup>++```bash Spree CLI (Docker)+spree generate spree:authentication:custom```-or rename the column to `password_digest` in a migration. A plain bcrypt digest (such as Devise's `encrypted_password` with no pepper configured) is read directly by `has_secure_password`, so existing passwords keep working with no reset.+```bash Without Spree CLI+bin/rails g spree:authentication:custom+```-## Custom authentication providers+</CodeGroup>-Spree authenticates through pluggable strategies — `Spree.store_authentication_strategies` and `Spree.admin_authentication_strategies` — which default to email + password. To plug in an external provider (Auth0, Clerk, SSO, and so on), implement a `Spree::Authentication::Strategies::BaseStrategy` subclass and register it. See [Custom API authentication](/developer/how-to/custom-api-authentication) for a worked example.+This will create a new file in `lib/spree/authentication_helpers.rb` that serves as a bridge between Spree and your existing authentication system routes. You will need to customize this file to fit your needs.++Secondly, this generator will add necessary modules to your `User` model.++```ruby+# app/models/user.rb+class User < ApplicationRecord+ # ... your existing code ...++ include Spree::UserAddress+ include Spree::UserMethods+ include Spree::UserPaymentSource+end+```## Admin Panel authenticationdiff --git a/docs/developer/customization/permissions.mdx b/docs/developer/customization/permissions.mdxindex e08cef551a..0b85f53590 100644--- a/docs/developer/customization/permissions.mdx+++ b/docs/developer/customization/permissions.mdx@@ -159,7 +159,7 @@ Spree::Role.find_or_create_by(name: 'warehouse_staff')Assign a role to a user:```ruby-user = Spree.customer_class.find_by(email: '[email protected]')+user = Spree.user_class.find_by(email: '[email protected]')role = Spree::Role.find_by(name: 'customer_service')user.spree_roles << role```@@ -221,7 +221,7 @@ class CustomAbility < Spree::Abilitydef initialize(user, options = {})alias_cancan_delete_action- @user = user || Spree.customer_class.new+ @user = user || Spree.user_class.new@store = options[:store] || Spree::Current.storeif @user.respond_to?(:has_spree_role?) && @user.has_spree_role?('admin')@@ -239,7 +239,7 @@ class CustomAbility < Spree::Abilitydef apply_customer_service_permissions(user)can :manage, Spree::Order- can [:read, :admin], Spree.customer_class+ can [:read, :admin], Spree.user_classendend```diff --git a/docs/developer/customization/quickstart.mdx b/docs/developer/customization/quickstart.mdxindex 05e4646f41..d23da7806a 100644--- a/docs/developer/customization/quickstart.mdx+++ b/docs/developer/customization/quickstart.mdx@@ -149,7 +149,7 @@ Spree is a flexible platform allowing you to customize every part of it to suit<Accordion title="Authentication">**Best for:** Using your own user model or authentication system.- Spree ships gem-owned `has_secure_password` models by default, and lets you point it at your own user model or authentication provider instead.+ Spree allows you to use your own authentication system instead of the default Devise-based one.You can find more information in the [Authentication](authentication) section.</Accordion>diff --git a/docs/developer/how-to/custom-api-authentication.mdx b/docs/developer/how-to/custom-api-authentication.mdxindex 9de0c7aa54..3f7c188bf4 100644--- a/docs/developer/how-to/custom-api-authentication.mdx+++ b/docs/developer/how-to/custom-api-authentication.mdx@@ -25,7 +25,7 @@ The mechanism is identical for both surfaces. A strategy you write works on eith| | Store API (customers) | Admin API (staff) ||---|---|---|| Registry | `Spree.store_authentication_strategies` | `Spree.admin_authentication_strategies` |-| User class | `Spree.customer_class` | `Spree.admin_user_class` |+| User class | `Spree.user_class` | `Spree.admin_user_class` || Login endpoint | `POST /api/v3/store/auth/login` | `POST /api/v3/admin/auth/login` || Refresh endpoint | `POST /api/v3/store/auth/refresh` | `POST /api/v3/admin/auth/refresh` || JWT audience | `aud: store_api` | `aud: admin_api` |@@ -136,7 +136,7 @@ end|---|---|| `success(user)` | Wrap a user in a successful `ServiceModule::Result` || `failure(message)` | Wrap an error message in a failed result |-| `find_user_by_email(email)` | Lookup against `Spree.customer_class` |+| `find_user_by_email(email)` | Lookup against `Spree.user_class` || `find_or_create_user_from_oauth(provider:, uid:, info:, tokens: {})` | Calls `Spree::UserIdentity.find_or_create_from_oauth` with the right `user_class` || `params`, `request_env`, `user_class` | Reader access to the controller-supplied inputs |@@ -181,7 +181,7 @@ Both registries are a `Spree::Authentication::StrategyRegistry` with the same AP| `[key]` | Look up a registered class. || `key?(key)`, `keys`, `values`, `each`, `to_h` | Standard introspection. |-The strategy is instantiated with the surface's user class automatically — `Spree.customer_class` from the store registry, `Spree.admin_user_class` from the admin registry — and your `authenticate` reads it via the `user_class` helper, so the same class provisions customers on one side and staff on the other.+The strategy is instantiated with the surface's user class automatically — `Spree.user_class` from the store registry, `Spree.admin_user_class` from the admin registry — and your `authenticate` reads it via the `user_class` helper, so the same class provisions customers on one side and staff on the other.<Tip>Restrict a surface to SSO by removing the built-in email/password strategy after adding yours: `Spree.admin_authentication_strategies.remove(:email)` locks staff to your provider; the store side stays on email/password.@@ -370,14 +370,14 @@ RSpec.describe MyApp::Auth::ExternalJwtStrategy doendit 'provisions a Spree user on first login' do- expect { result }.to change(Spree.customer_class, :count).by(1)+ expect { result }.to change(Spree.user_class, :count).by(1)expect(result).to be_successexpect(result.value.email).to eq('[email protected]')endit 'reuses the user on subsequent logins' dodescribed_class.new(params: { token: token }, request_env: {}).authenticate- expect { result }.not_to change(Spree.customer_class, :count)+ expect { result }.not_to change(Spree.user_class, :count)endit 'fails on an expired token' do@@ -395,4 +395,4 @@ end- `Spree::Api::V3::Store::AuthController` — `spree/api/app/controllers/spree/api/v3/store/auth_controller.rb`- `Spree::Api::V3::Admin::AuthController` — `spree/api/app/controllers/spree/api/v3/admin/auth_controller.rb`- `Spree::Api::V3::JwtAuthentication` — `spree/api/app/controllers/concerns/spree/api/v3/jwt_authentication.rb`-- See also: [Staff & Roles](/developer/core-concepts/staff-roles) for the admin login flow, [Customers](/developer/core-concepts/customers) for storefront auth, and [Authentication](/developer/customization/authentication) for `Spree.customer_class` integration.+- See also: [Staff & Roles](/developer/core-concepts/staff-roles) for the admin login flow, [Customers](/developer/core-concepts/customers) for storefront auth, and [Authentication](/developer/customization/authentication) for `Spree.user_class` integration.diff --git a/docs/developer/storefront/rails/helper-methods.mdx b/docs/developer/storefront/rails/helper-methods.mdxindex 5ca3117fcd..ef02567a83 100644--- a/docs/developer/storefront/rails/helper-methods.mdx+++ b/docs/developer/storefront/rails/helper-methods.mdx@@ -50,11 +50,11 @@ Returns the current order object. If no order is found, it will return `nil`.### `try_spree_current_user`-<ResponseField name="try_spree_current_user" type="Spree.customer_class" description="The current user object.">+<ResponseField name="try_spree_current_user" type="Spree.user_class" description="The current user object."><SpreeUser /></ResponseField>-Returns the current user object (class depends on the `Spree.customer_class` configuration). If the user is not signed in, it will return `nil`.+Returns the current user object (class depends on the `Spree.user_class` configuration). If the user is not signed in, it will return `nil`.<Tip>If you want to check if the user is signed in, you can use the following: