@spree/docs 0.1.90 → 0.1.92
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/developer/admin/admin.md +11 -1
- package/dist/developer/admin/custom-css.md +17 -4
- package/dist/developer/core-concepts/pricing.md +14 -2
- package/dist/developer/core-concepts/translations.md +7 -1
- package/dist/developer/customization/authentication.md +15 -3
- package/dist/developer/customization/decorators.md +14 -2
- package/dist/developer/customization/emails.md +8 -1
- package/dist/developer/customization/model-preferences.md +17 -4
- package/dist/developer/deployment/caching.md +8 -3
- package/dist/developer/deployment/environment_variables.md +8 -2
- package/dist/developer/multi-store/quickstart.md +9 -2
- package/dist/developer/multi-tenant/core-concepts.md +8 -1
- package/dist/developer/multi-tenant/installation.md +28 -6
- package/dist/developer/multi-vendor/installation.md +20 -4
- package/dist/developer/upgrades/5.4-to-5.5.md +39 -15
- package/dist/integrations/analytics/google-analytics.md +9 -3
- package/dist/integrations/analytics/google-tag-manager.md +9 -3
- package/dist/integrations/marketing/klaviyo.md +9 -3
- package/dist/integrations/payments/adyen.md +9 -3
- package/dist/integrations/payments/paypal.md +9 -3
- package/dist/integrations/payments/razorpay.md +10 -4
- package/dist/integrations/payments/stripe.md +9 -3
- package/dist/integrations/search/meilisearch.md +24 -6
- package/dist/integrations/tax/avalara.md +8 -2
- package/package.json +1 -1
|
@@ -159,7 +159,16 @@ The Admin Dashboard uses [Tailwind CSS v4](https://tailwindcss.com/) for styling
|
|
|
159
159
|
|
|
160
160
|
### Generator Commands
|
|
161
161
|
|
|
162
|
-
|
|
162
|
+
|
|
163
|
+
```bash Spree CLI (Docker)
|
|
164
|
+
# Generate a complete admin section (controller, views, routes)
|
|
165
|
+
spree generate spree:admin:scaffold Spree::Brand
|
|
166
|
+
|
|
167
|
+
# Generate just a controller
|
|
168
|
+
spree generate controller Spree::Admin::Brands --skip-routes
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
```bash Without Spree CLI
|
|
163
172
|
# Generate a complete admin section (controller, views, routes)
|
|
164
173
|
bin/rails g spree:admin:scaffold Spree::Brand
|
|
165
174
|
|
|
@@ -167,6 +176,7 @@ bin/rails g spree:admin:scaffold Spree::Brand
|
|
|
167
176
|
bin/rails g controller Spree::Admin::Brands --skip-routes
|
|
168
177
|
```
|
|
169
178
|
|
|
179
|
+
|
|
170
180
|
## Authentication & Authorization
|
|
171
181
|
|
|
172
182
|
### Authentication
|
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: Admin Dashboard Custom CSS
|
|
3
3
|
sidebarTitle: Custom CSS
|
|
4
|
+
description: Customize the Spree Admin Dashboard with your own CSS by overriding Tailwind variables, adding custom styles, and extending admin views and helpers.
|
|
4
5
|
---
|
|
5
6
|
|
|
6
7
|
Spree Admin Dashboard uses [Tailwind CSS v4](https://tailwindcss.com/) for styling. The stylesheet system is designed to be easily customizable while maintaining consistency with the Spree design system.
|
|
@@ -147,16 +148,28 @@ If you have admin-related code in non-standard locations, add additional `@sourc
|
|
|
147
148
|
|
|
148
149
|
During development, run the Tailwind CSS watcher to automatically rebuild styles when you make changes:
|
|
149
150
|
|
|
150
|
-
|
|
151
|
-
|
|
151
|
+
|
|
152
|
+
```bash Spree CLI (Docker)
|
|
153
|
+
spree rake spree:admin:tailwindcss:watch
|
|
152
154
|
```
|
|
153
155
|
|
|
154
|
-
|
|
156
|
+
```bash Without Spree CLI
|
|
157
|
+
bundle exec rake spree:admin:tailwindcss:watch
|
|
158
|
+
```
|
|
155
159
|
|
|
156
|
-
|
|
160
|
+
|
|
161
|
+
Or run the full development process, which includes the watcher when it's defined in `Procfile.dev`:
|
|
162
|
+
|
|
163
|
+
|
|
164
|
+
```bash Spree CLI (Docker)
|
|
165
|
+
spree dev
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
```bash Without Spree CLI
|
|
157
169
|
bin/dev
|
|
158
170
|
```
|
|
159
171
|
|
|
172
|
+
|
|
160
173
|
The watcher monitors:
|
|
161
174
|
- Your host app's CSS files in `app/assets/tailwind/`
|
|
162
175
|
- The Spree Admin engine's CSS files
|
|
@@ -220,18 +220,30 @@ end
|
|
|
220
220
|
|
|
221
221
|
Price history retention defaults to 30 days and can be configured globally. A Rake task is provided for cleanup:
|
|
222
222
|
|
|
223
|
-
|
|
223
|
+
|
|
224
|
+
```bash Spree CLI (Docker)
|
|
225
|
+
spree rake spree:price_history:prune
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
```bash Without Spree CLI
|
|
224
229
|
bundle exec rake spree:price_history:prune
|
|
225
230
|
```
|
|
226
231
|
|
|
232
|
+
|
|
227
233
|
### Seeding Existing Prices
|
|
228
234
|
|
|
229
235
|
After enabling price history on an existing store, seed the current prices as a baseline:
|
|
230
236
|
|
|
231
|
-
|
|
237
|
+
|
|
238
|
+
```bash Spree CLI (Docker)
|
|
239
|
+
spree rake spree:price_history:seed
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
```bash Without Spree CLI
|
|
232
243
|
bundle exec rake spree:price_history:seed
|
|
233
244
|
```
|
|
234
245
|
|
|
246
|
+
|
|
235
247
|
## Related Documentation
|
|
236
248
|
|
|
237
249
|
- [Products](products.md) — Products, Variants, and base prices
|
|
@@ -104,10 +104,16 @@ Spree stores UI translation strings in a separate project: [Spree I18n](https://
|
|
|
104
104
|
|
|
105
105
|
To install UI translations:
|
|
106
106
|
|
|
107
|
-
|
|
107
|
+
|
|
108
|
+
```bash Spree CLI (Docker)
|
|
109
|
+
spree bundle add spree_i18n
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
```bash Without Spree CLI
|
|
108
113
|
bundle add spree_i18n
|
|
109
114
|
```
|
|
110
115
|
|
|
116
|
+
|
|
111
117
|
Once installed, all translation files are available automatically — no need to copy any files.
|
|
112
118
|
|
|
113
119
|
> **INFO:** The full list of supported locales is available in the [Spree I18n GitHub repository](https://github.com/spree-contrib/spree_i18n/tree/main/config/locales).
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: Authentication
|
|
3
|
-
description:
|
|
3
|
+
description: Integrate Spree with a custom authentication setup, including Devise, an existing user model, OmniAuth providers, and JWT or OAuth API tokens.
|
|
4
4
|
version: v5
|
|
5
5
|
---
|
|
6
6
|
|
|
@@ -20,10 +20,16 @@ Spree.user_class = 'User'
|
|
|
20
20
|
|
|
21
21
|
Now, run the generator to set up Spree integration with Devise:
|
|
22
22
|
|
|
23
|
-
|
|
23
|
+
|
|
24
|
+
```bash Spree CLI (Docker)
|
|
25
|
+
spree generate spree:authentication:devise
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
```bash Without Spree CLI
|
|
24
29
|
bin/rails g spree:authentication:devise
|
|
25
30
|
```
|
|
26
31
|
|
|
32
|
+
|
|
27
33
|
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.
|
|
28
34
|
|
|
29
35
|
Secondly, this generator will add necessary modules to your `User` model.
|
|
@@ -64,10 +70,16 @@ Spree.user_class = 'User'
|
|
|
64
70
|
|
|
65
71
|
Now, run the generator to set up Spree integration with your custom authentication system:
|
|
66
72
|
|
|
67
|
-
|
|
73
|
+
|
|
74
|
+
```bash Spree CLI (Docker)
|
|
75
|
+
spree generate spree:authentication:custom
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
```bash Without Spree CLI
|
|
68
79
|
bin/rails g spree:authentication:custom
|
|
69
80
|
```
|
|
70
81
|
|
|
82
|
+
|
|
71
83
|
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.
|
|
72
84
|
|
|
73
85
|
Secondly, this generator will add necessary modules to your `User` model.
|
|
@@ -86,10 +86,16 @@ Spree provides generators to create decorator files with the correct structure:
|
|
|
86
86
|
|
|
87
87
|
### Model Decorator Generator
|
|
88
88
|
|
|
89
|
-
|
|
89
|
+
|
|
90
|
+
```bash Spree CLI (Docker)
|
|
91
|
+
spree generate spree:model_decorator Spree::Product
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
```bash Without Spree CLI
|
|
90
95
|
bin/rails g spree:model_decorator Spree::Product
|
|
91
96
|
```
|
|
92
97
|
|
|
98
|
+
|
|
93
99
|
This creates `app/models/spree/product_decorator.rb`:
|
|
94
100
|
|
|
95
101
|
```ruby
|
|
@@ -106,10 +112,16 @@ end
|
|
|
106
112
|
|
|
107
113
|
### Controller Decorator Generator
|
|
108
114
|
|
|
109
|
-
|
|
115
|
+
|
|
116
|
+
```bash Spree CLI (Docker)
|
|
117
|
+
spree generate spree:controller_decorator Spree::Admin::ProductsController
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
```bash Without Spree CLI
|
|
110
121
|
bin/rails g spree:controller_decorator Spree::Admin::ProductsController
|
|
111
122
|
```
|
|
112
123
|
|
|
124
|
+
|
|
113
125
|
This creates `app/controllers/spree/admin/products_controller_decorator.rb`:
|
|
114
126
|
|
|
115
127
|
```ruby
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: Emails
|
|
3
|
+
description: Customize Spree transactional emails using the spree_emails gem and Postmark templates, including how to preview mailers locally during development.
|
|
3
4
|
---
|
|
4
5
|
|
|
5
6
|
> **NOTE:** Emails are now part of `spree_emails` gem. If you use `spree_starter` you already have it installed.
|
|
@@ -12,10 +13,16 @@ Spree uses [postmark templates](https://github.com/wildbit/postmark-templates),
|
|
|
12
13
|
|
|
13
14
|
Spree offers an emails preview generator for development purposes. To generate them, use the command:
|
|
14
15
|
|
|
15
|
-
|
|
16
|
+
|
|
17
|
+
```bash Spree CLI (Docker)
|
|
18
|
+
spree generate spree:emails:install
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
```bash Without Spree CLI
|
|
16
22
|
bin/rails g spree:emails:install
|
|
17
23
|
```
|
|
18
24
|
|
|
25
|
+
|
|
19
26
|
After that, start the rails server locally and go to: `localhost:3000/rails/mailers`
|
|
20
27
|
|
|
21
28
|
(it requires a seeded development database in order to work properly)
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: Model Preferences
|
|
3
|
+
description: Add typed configuration options to Spree models using model preferences, including supported types, default values, and reading or writing stored values.
|
|
3
4
|
---
|
|
4
5
|
|
|
5
6
|
Model preferences allow you to easily extend Spree models with configuration options. Thanks to this you can store useful information on Spree models, eg.
|
|
@@ -15,16 +16,28 @@ To define a model preference, you need to add them to your model class.
|
|
|
15
16
|
|
|
16
17
|
Make sure to generate a migration to add the `preferences` column to the table. This column will store the preferences in a serialized format.
|
|
17
18
|
|
|
18
|
-
|
|
19
|
-
|
|
19
|
+
|
|
20
|
+
```bash Spree CLI (Docker)
|
|
21
|
+
spree generate migration AddPreferencesToSpreeUsers preferences:text
|
|
20
22
|
```
|
|
21
23
|
|
|
24
|
+
```bash Without Spree CLI
|
|
25
|
+
bin/rails g migration AddPreferencesToSpreeUsers preferences:text
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
|
|
22
29
|
Run the migration.
|
|
23
30
|
|
|
24
|
-
|
|
25
|
-
|
|
31
|
+
|
|
32
|
+
```bash Spree CLI (Docker)
|
|
33
|
+
spree migrate
|
|
26
34
|
```
|
|
27
35
|
|
|
36
|
+
```bash Without Spree CLI
|
|
37
|
+
bin/rails db:migrate
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
|
|
28
41
|
```ruby
|
|
29
42
|
class Spree::User < ApplicationRecord
|
|
30
43
|
# ... you existing code ...
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: Caching
|
|
3
|
-
description: Configure caching for your Spree application
|
|
3
|
+
description: Configure Redis-backed caching for your Spree application to speed up database queries and template renders, with tips for cache keys and invalidation.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
Caching improves performance by storing the results of expensive database queries and template renders in memory.
|
|
@@ -19,9 +19,14 @@ When `REDIS_URL` is set, Spree automatically uses it for caching. When not set,
|
|
|
19
19
|
|
|
20
20
|
To enable caching in the development environment:
|
|
21
21
|
|
|
22
|
-
|
|
23
|
-
|
|
22
|
+
|
|
23
|
+
```bash Spree CLI (Docker)
|
|
24
|
+
spree rails dev:cache
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
```bash Without Spree CLI
|
|
24
28
|
bin/rails dev:cache
|
|
25
29
|
```
|
|
26
30
|
|
|
31
|
+
|
|
27
32
|
You will need to restart your web server after this.
|
|
@@ -84,10 +84,16 @@ After setting these, enable the provider and reindex:
|
|
|
84
84
|
Spree.search_provider = 'Spree::SearchProvider::Meilisearch'
|
|
85
85
|
```
|
|
86
86
|
|
|
87
|
-
|
|
88
|
-
|
|
87
|
+
|
|
88
|
+
```bash Spree CLI (Docker)
|
|
89
|
+
spree rake spree:search:reindex
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
```bash Without Spree CLI
|
|
93
|
+
bundle exec rake spree:search:reindex
|
|
89
94
|
```
|
|
90
95
|
|
|
96
|
+
|
|
91
97
|
## Error Tracking (Sentry)
|
|
92
98
|
|
|
93
99
|
| Variable | Default | Description |
|
|
@@ -1,14 +1,21 @@
|
|
|
1
1
|
---
|
|
2
|
-
title: Multi-Store Spree Commerce
|
|
2
|
+
title: Multi-Store Spree Commerce Quickstart
|
|
3
3
|
sidebarTitle: Quickstart
|
|
4
|
+
description: Enable multiple storefronts on a single Spree app with the spree_multi_store gem, including per-store products, payment methods, taxonomies, and promotions.
|
|
4
5
|
---
|
|
5
6
|
|
|
6
7
|
To enable multiple stores, you will need to add the `spree_multi_store` gem to your project via:
|
|
7
8
|
|
|
8
|
-
|
|
9
|
+
|
|
10
|
+
```bash Spree CLI (Docker)
|
|
11
|
+
spree bundle add spree_multi_store
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
```bash Without Spree CLI
|
|
9
15
|
bundle add spree_multi_store
|
|
10
16
|
```
|
|
11
17
|
|
|
18
|
+
|
|
12
19
|
> **INFO:** Spree Multi-Store is licensed under the [AGPL v3 License](https://opensource.org/licenses/AGPL-3.0).
|
|
13
20
|
>
|
|
14
21
|
> If you would like to use it in a commercial application, please [contact us](https://spreecommerce.org/get-started/) to obtain a commercial license.
|
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: Multi-Tenant Core Concepts
|
|
3
3
|
sidebarTitle: Core Concepts
|
|
4
|
+
description: Understand the Spree multi-tenant architecture, including the Tenant class, row-level tenant isolation, tenanted models, and automatic seeding for new tenants.
|
|
4
5
|
---
|
|
5
6
|
|
|
6
7
|
## Tenant class
|
|
@@ -17,10 +18,16 @@ All models that are tenanted inherit from `SpreeMultiTenant::Base` class. `spree
|
|
|
17
18
|
|
|
18
19
|
When creating a new model that you want to be tenanted remember to inherit from `SpreeMultiTenant::Base` and not from `Spree::Base` and add `tenant_id` column to the table, eg.
|
|
19
20
|
|
|
20
|
-
|
|
21
|
+
|
|
22
|
+
```bash Spree CLI (Docker)
|
|
23
|
+
spree generate model Spree::NewModel tenant:references name:string --parent SpreeMultiTenant::Base
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
```bash Without Spree CLI
|
|
21
27
|
bin/rails g model Spree::NewModel tenant:references name:string --parent SpreeMultiTenant::Base
|
|
22
28
|
```
|
|
23
29
|
|
|
30
|
+
|
|
24
31
|
> **INFO:** You don't need to add `belongs_to :tenant` to the model, it's handled by gem.
|
|
25
32
|
|
|
26
33
|
## Tenant selector
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: Spree Multi Tenant Installation
|
|
3
3
|
sidebarTitle: Installation
|
|
4
|
-
description:
|
|
4
|
+
description: Install and configure Spree Multi-Tenant to run a SaaS ecommerce platform, including prerequisites, gem setup, license keys, and tenant provisioning.
|
|
5
5
|
---
|
|
6
6
|
|
|
7
7
|
> **WARNING:** This installation instructions assume you have a clean Spree Starter installation and you've purchased the [Spree Enterprise Edition license](https://spreecommerce.org/pricing).
|
|
@@ -37,10 +37,16 @@ Admin user classes will be shared across tenants allowing them to manage multipl
|
|
|
37
37
|
|
|
38
38
|
Let's create a new model with Devise (unless you already have one):
|
|
39
39
|
|
|
40
|
-
|
|
41
|
-
|
|
40
|
+
|
|
41
|
+
```bash Spree CLI (Docker)
|
|
42
|
+
spree rails g devise Spree::AdminUser
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
```bash Without Spree CLI
|
|
46
|
+
bin/rails g devise Spree::AdminUser
|
|
42
47
|
```
|
|
43
48
|
|
|
49
|
+
|
|
44
50
|
Replace the generated Devise code with the following:
|
|
45
51
|
|
|
46
52
|
```ruby
|
|
@@ -83,14 +89,30 @@ Spree.admin_user_class = "Spree::AdminUser"
|
|
|
83
89
|
|
|
84
90
|
2. Install gems:
|
|
85
91
|
|
|
86
|
-
|
|
92
|
+
|
|
93
|
+
|
|
94
|
+
```bash Spree CLI (Docker)
|
|
95
|
+
spree bundle install
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
```bash Without Spree CLI
|
|
87
99
|
bundle install
|
|
88
100
|
```
|
|
89
101
|
|
|
102
|
+
|
|
103
|
+
|
|
90
104
|
3. Run generators:
|
|
91
105
|
|
|
92
|
-
|
|
93
|
-
|
|
106
|
+
|
|
107
|
+
|
|
108
|
+
```bash Spree CLI (Docker)
|
|
109
|
+
spree generate spree_enterprise:install && spree generate spree_multi_tenant:install
|
|
94
110
|
```
|
|
95
111
|
|
|
112
|
+
```bash Without Spree CLI
|
|
113
|
+
bin/rails g spree_enterprise:install && bin/rails g spree_multi_tenant:install
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
|
|
117
|
+
|
|
96
118
|
> **INFO:** This will copy and run migrations for `spree_enterprise` and `spree_multi_tenant` gems.
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: Spree Multi Vendor Installation
|
|
3
3
|
sidebarTitle: Installation
|
|
4
|
-
description:
|
|
4
|
+
description: Install and configure Spree Multi-Vendor to launch a marketplace with multiple vendors, including prerequisites, gem setup, license keys, and vendor onboarding.
|
|
5
5
|
---
|
|
6
6
|
|
|
7
7
|
> **WARNING:** This installation instructions assume you have purchased the [Spree Enterprise Edition license](https://spreecommerce.org/pricing).
|
|
@@ -32,14 +32,30 @@ description: Learn how to set up a multi-vendor marketplace with Spree
|
|
|
32
32
|
|
|
33
33
|
2. Install gems:
|
|
34
34
|
|
|
35
|
-
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
```bash Spree CLI (Docker)
|
|
38
|
+
spree bundle install
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
```bash Without Spree CLI
|
|
36
42
|
bundle install
|
|
37
43
|
```
|
|
38
44
|
|
|
45
|
+
|
|
46
|
+
|
|
39
47
|
3. Run generators:
|
|
40
48
|
|
|
41
|
-
|
|
42
|
-
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
```bash Spree CLI (Docker)
|
|
52
|
+
spree generate spree_enterprise:install && spree generate spree_multi_vendor:install
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
```bash Without Spree CLI
|
|
56
|
+
bin/rails g spree_enterprise:install && bin/rails g spree_multi_vendor:install
|
|
43
57
|
```
|
|
44
58
|
|
|
59
|
+
|
|
60
|
+
|
|
45
61
|
> **INFO:** This will copy and run migrations for `spree_enterprise` and `spree_multi_vendor` gems.
|
|
@@ -17,15 +17,15 @@ The upgrade is usually completed in five steps:
|
|
|
17
17
|
For applications created via `create-spree-app` command we greatly recommend using the Spree CLI to perform the upgrade. It provides a guided experience with prompts and handles the first three steps for you. If you prefer to run the commands manually or not using docker for local development, you can follow the "Without Spree CLI" path.
|
|
18
18
|
|
|
19
19
|
|
|
20
|
-
```bash Spree CLI
|
|
20
|
+
```bash Spree CLI (Docker)
|
|
21
21
|
spree upgrade
|
|
22
22
|
```
|
|
23
23
|
|
|
24
24
|
```bash Without Spree CLI
|
|
25
25
|
# cd backend if you're in the monorepo root
|
|
26
26
|
bundle update
|
|
27
|
-
|
|
28
|
-
|
|
27
|
+
bundle exec rake spree:install:migrations && bin/rails db:migrate
|
|
28
|
+
bundle exec rake spree:upgrade
|
|
29
29
|
```
|
|
30
30
|
|
|
31
31
|
|
|
@@ -39,30 +39,42 @@ npm install -g @spree/cli
|
|
|
39
39
|
npx @spree/cli upgrade
|
|
40
40
|
```
|
|
41
41
|
|
|
42
|
-
The **Without Spree CLI** path is the bare equivalent. Use this on production: `bundle update` and `db:migrate` are part of your existing deploy pipeline (Heroku release phase, K8s init container, Capistrano hook, Render auto-migrate). Once the 5.5 release is up, run `
|
|
42
|
+
The **Without Spree CLI** path is the bare equivalent. Use this on production: `bundle update` and `db:migrate` are part of your existing deploy pipeline (Heroku release phase, K8s init container, Capistrano hook, Render auto-migrate). Once the 5.5 release is up, run `bundle exec rake spree:upgrade` from a one-off dyno / job container / `kubectl exec` to perform the data backfills.
|
|
43
43
|
|
|
44
|
-
Skipping versions and re-running are both safe — `
|
|
44
|
+
Skipping versions and re-running are both safe — `bundle exec rake spree:upgrade` figures out what still needs to happen and does nothing on data that's already migrated.
|
|
45
45
|
|
|
46
46
|
## What the upgrade does
|
|
47
47
|
|
|
48
|
-
This is reference material — what `
|
|
48
|
+
This is reference material — what `bundle exec rake spree:upgrade` (and equivalently `spree upgrade`) actually executes on your data. Skip if you trust the tool; read on if something failed or you're curious.
|
|
49
49
|
|
|
50
50
|
### Migrate legacy variant-pinned media
|
|
51
51
|
|
|
52
52
|
In 5.5 the [product is the default owner of media](../core-concepts/media.md#product-level-gallery). Existing variant-pinned images keep rendering, but new admin uploads attach to the product. To consolidate both into a single gallery, the upgrade runs:
|
|
53
53
|
|
|
54
|
-
|
|
55
|
-
|
|
54
|
+
|
|
55
|
+
```bash Spree CLI (Docker)
|
|
56
|
+
spree rake spree:media:migrate_master_images_to_product_media
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
```bash Without Spree CLI
|
|
60
|
+
bundle exec rake spree:media:migrate_master_images_to_product_media
|
|
56
61
|
```
|
|
57
62
|
|
|
63
|
+
|
|
58
64
|
The task enqueues one `Spree::Media::MigrateProductAssetsJob` per product onto the `images` queue — make sure your job runner is processing that queue. Each job is idempotent, so re-running the task is safe; it skips products that no longer have variant-pinned assets.
|
|
59
65
|
|
|
60
66
|
For larger catalogs, tune the batching with `BATCH_SIZE`:
|
|
61
67
|
|
|
62
|
-
|
|
63
|
-
|
|
68
|
+
|
|
69
|
+
```bash Spree CLI (Docker)
|
|
70
|
+
spree rake spree:media:migrate_master_images_to_product_media BATCH_SIZE=1000
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
```bash Without Spree CLI
|
|
74
|
+
bundle exec rake spree:media:migrate_master_images_to_product_media BATCH_SIZE=1000
|
|
64
75
|
```
|
|
65
76
|
|
|
77
|
+
|
|
66
78
|
> **WARNING:** Run the task locally and on production. It does not block storefront rendering — new uploads attach to the product immediately — but until the enqueued jobs finish, old assets remain pinned to variants.
|
|
67
79
|
|
|
68
80
|
### Run the Channels upgrade
|
|
@@ -71,10 +83,16 @@ Spree 5.5 introduces [Sales Channels](../core-concepts/channels.md) — a per-st
|
|
|
71
83
|
|
|
72
84
|
The migrations add a `default` boolean on `spree_channels`, a `store_id` column on `spree_products`, and create the new `spree_product_publications` table — **but they do not seed default channels, attach existing products to a store, or backfill order channels**. That work is done by an idempotent rake task:
|
|
73
85
|
|
|
74
|
-
|
|
75
|
-
|
|
86
|
+
|
|
87
|
+
```bash Spree CLI (Docker)
|
|
88
|
+
spree rake spree:channels:upgrade
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
```bash Without Spree CLI
|
|
92
|
+
bundle exec rake spree:channels:upgrade
|
|
76
93
|
```
|
|
77
94
|
|
|
95
|
+
|
|
78
96
|
The task runs four sub-tasks in order:
|
|
79
97
|
|
|
80
98
|
1. `spree:channels:create_defaults` — creates the default "Online Store" channel for every existing store (via `Store#ensure_default_channel`).
|
|
@@ -90,10 +108,16 @@ The task is fully idempotent — safe to re-run if it fails partway, and a no-op
|
|
|
90
108
|
|
|
91
109
|
The last step rebuilds the search index against the configured [search provider](../core-concepts/search-filtering.md):
|
|
92
110
|
|
|
93
|
-
|
|
94
|
-
|
|
111
|
+
|
|
112
|
+
```bash Spree CLI (Docker)
|
|
113
|
+
spree rake spree:search:reindex
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
```bash Without Spree CLI
|
|
117
|
+
bundle exec rake spree:search:reindex
|
|
95
118
|
```
|
|
96
119
|
|
|
120
|
+
|
|
97
121
|
This is a no-op on the default Database provider (there is no external index to maintain). For Meilisearch — or any other external search provider — it is required, and it must run **after** the Channels upgrade: products only become visible to `Product.for_store` once they have a `store_id`, so reindexing before the channels step would index zero products. The manifest orders the steps accordingly.
|
|
98
122
|
|
|
99
123
|
#### Multi-store catalogs
|
|
@@ -132,7 +156,7 @@ The SDK bump pairs with one storefront code change in this release: the [payment
|
|
|
132
156
|
|
|
133
157
|
## Required post-upgrade configuration
|
|
134
158
|
|
|
135
|
-
`
|
|
159
|
+
`bundle exec rake spree:upgrade` doesn't touch your job-runner config — every app uses a different scheduler, so this one is on you.
|
|
136
160
|
|
|
137
161
|
### Schedule the Stock Reservations expiry job
|
|
138
162
|
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: "Connect Google Analytics 4 to Spree Commerce"
|
|
3
3
|
sidebarTitle: Google Analytics 4
|
|
4
|
-
description: "
|
|
4
|
+
description: "Set up Spree's native Google Analytics 4 integration to track ecommerce events, user behavior, and sales performance across your store with no custom code."
|
|
5
5
|
---
|
|
6
6
|
|
|
7
7
|
Spree Commerce comes with a native Google Analytics 4 integration that allows you to track user behavior, sales performance, and marketing effectiveness across your store.
|
|
@@ -14,10 +14,16 @@ With minimal setup required, you can gain valuable insights into how visitors in
|
|
|
14
14
|
|
|
15
15
|
Before you can enable Google Analytics 4, it must be installed. To do so, you need to run the following command:
|
|
16
16
|
|
|
17
|
-
|
|
18
|
-
|
|
17
|
+
|
|
18
|
+
```bash Spree CLI (Docker)
|
|
19
|
+
spree bundle add spree_google_analytics && spree generate spree_google_analytics:install
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
```bash Without Spree CLI
|
|
23
|
+
bundle add spree_google_analytics && bin/rails g spree_google_analytics:install
|
|
19
24
|
```
|
|
20
25
|
|
|
26
|
+
|
|
21
27
|
After that, make sure to restart your server if it was running.
|
|
22
28
|
|
|
23
29
|
## Connect Google Analytics
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: "Connect Google Tag Manager to Spree Commerce"
|
|
3
3
|
sidebarTitle: Google Tag Manager
|
|
4
|
-
description: "
|
|
4
|
+
description: "Connect Spree's native Google Tag Manager integration to push ecommerce dataLayer events for GA4, Google Ads, Meta Pixel, and other marketing tags."
|
|
5
5
|
---
|
|
6
6
|
|
|
7
7
|
Google Tag Manager is a flexible tag management tool that lets you deploy and manage analytics, SEO, and marketing scripts across your store without editing code. You can connect services like Google Analytics 4, Google Ads, Meta Pixel, Microsoft Clarity, LinkedIn Insights, and Hotjar from one central workspace.
|
|
@@ -24,10 +24,16 @@ Spree will automatically push ecommerce events to the dataLayer, but it’s up t
|
|
|
24
24
|
|
|
25
25
|
Before you can enable Google Tag Manager, it must be installed. To do so, you need to run the following command:
|
|
26
26
|
|
|
27
|
-
|
|
28
|
-
|
|
27
|
+
|
|
28
|
+
```bash Spree CLI (Docker)
|
|
29
|
+
spree bundle add spree_google_analytics && spree generate spree_google_analytics:install
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
```bash Without Spree CLI
|
|
33
|
+
bundle add spree_google_analytics && bin/rails g spree_google_analytics:install
|
|
29
34
|
```
|
|
30
35
|
|
|
36
|
+
|
|
31
37
|
After that, make sure to restart your server if it was running.
|
|
32
38
|
|
|
33
39
|
## Connect Google Tag Manager
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: "Connect Klaviyo email marketing platform to Spree Commerce"
|
|
3
3
|
sidebarTitle: Klaviyo
|
|
4
|
-
description: "
|
|
4
|
+
description: "Connect Spree to Klaviyo to sync customer profiles, track ecommerce events, and power email and SMS marketing automations, segmentation, and newsletter signups."
|
|
5
5
|
---
|
|
6
6
|
|
|
7
7
|
Klaviyo is a powerful marketing automation platform used for email and SMS campaigns. By connecting your store to Klaviyo, you can automatically track user interactions, build audience profiles, and grow your newsletter subscriber base - all without manual setup.
|
|
@@ -14,10 +14,16 @@ With Spree’s native integration, you can start collecting meaningful data for
|
|
|
14
14
|
|
|
15
15
|
To install the Klaviyo integration, you need to run the following command:
|
|
16
16
|
|
|
17
|
-
|
|
18
|
-
|
|
17
|
+
|
|
18
|
+
```bash Spree CLI (Docker)
|
|
19
|
+
spree bundle add spree_klaviyo && spree generate spree_klaviyo:install
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
```bash Without Spree CLI
|
|
23
|
+
bundle add spree_klaviyo && bin/rails g spree_klaviyo:install
|
|
19
24
|
```
|
|
20
25
|
|
|
26
|
+
|
|
21
27
|
After that, you need to make sure to restart the server.
|
|
22
28
|
|
|
23
29
|
## Connect Klaviyo
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: "Connect Adyen payments to Spree Commerce"
|
|
3
3
|
sidebarTitle: "Adyen"
|
|
4
|
-
description: "
|
|
4
|
+
description: "Set up Spree's native Adyen integration to accept global payments across multiple methods, with built-in fraud protection and a seamless checkout experience."
|
|
5
5
|
---
|
|
6
6
|
|
|
7
7
|
Adyen is a global payment platform that enables businesses to accept payments across multiple channels and markets. It supports a wide range of payment methods, provides advanced fraud protection, and offers seamless checkout experiences for customers worldwide.
|
|
@@ -10,10 +10,16 @@ Adyen is a global payment platform that enables businesses to accept payments ac
|
|
|
10
10
|
|
|
11
11
|
Before you can enable Adyen, it must be installed. To do so, you need to run the following command:
|
|
12
12
|
|
|
13
|
-
|
|
14
|
-
|
|
13
|
+
|
|
14
|
+
```bash Spree CLI (Docker)
|
|
15
|
+
spree bundle add spree_adyen --github spree/spree_adyen && spree generate spree_adyen:install
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
```bash Without Spree CLI
|
|
19
|
+
bundle add spree_adyen --github spree/spree_adyen && bin/rails g spree_adyen:install
|
|
15
20
|
```
|
|
16
21
|
|
|
22
|
+
|
|
17
23
|
After that, you need to make sure to restart the server.
|
|
18
24
|
|
|
19
25
|
## Connect Adyen
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: "Connect PayPal payments to Spree Commerce"
|
|
3
3
|
sidebarTitle: "PayPal"
|
|
4
|
-
description: "
|
|
4
|
+
description: "Enable Spree's native PayPal integration to accept PayPal, Pay Later (BNPL), Venmo, and guest checkout payments without forcing shoppers to create an account."
|
|
5
5
|
---
|
|
6
6
|
|
|
7
7
|
PayPal is a global online payment system that allows your customers to pay using their PayPal balance, linked credit or debit cards, or bank accounts. Spree's native PayPal integration also supports PayPal Pay Later (BNPL), Venmo (US only), and guest checkout — giving shoppers flexibility at the payment step without forcing them to create a PayPal account.
|
|
@@ -10,10 +10,16 @@ PayPal is a global online payment system that allows your customers to pay using
|
|
|
10
10
|
|
|
11
11
|
Before you can enable PayPal, it must be installed. To do so, you need to run the following command:
|
|
12
12
|
|
|
13
|
-
|
|
14
|
-
|
|
13
|
+
|
|
14
|
+
```bash Spree CLI (Docker)
|
|
15
|
+
spree bundle add spree_paypal_checkout && spree generate spree_paypal_checkout:install
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
```bash Without Spree CLI
|
|
19
|
+
bundle add spree_paypal_checkout && bin/rails g spree_paypal_checkout:install
|
|
15
20
|
```
|
|
16
21
|
|
|
22
|
+
|
|
17
23
|
After that, you need to make sure to restart the server.
|
|
18
24
|
|
|
19
25
|
## Connect PayPal
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: "Connect Razorpay payments to Spree Commerce"
|
|
3
3
|
sidebarTitle: Razorpay
|
|
4
|
-
description: "
|
|
4
|
+
description: "Configure the Razorpay payment gateway in Spree to accept cards, UPI, net banking, and wallets, plus international transactions across multiple currencies."
|
|
5
5
|
---
|
|
6
6
|
|
|
7
7
|
Razorpay is a secure payment gateway that enables businesses to accept online payments via cards, UPI, net banking, and wallets. It also supports international transactions across multiple currencies.
|
|
@@ -12,12 +12,18 @@ Razorpay is a secure payment gateway that enables businesses to accept online pa
|
|
|
12
12
|
|
|
13
13
|
## Installation
|
|
14
14
|
|
|
15
|
-
Before you can enable Razorpay, it must be installed. To do so, you need to
|
|
15
|
+
Before you can enable Razorpay, it must be installed. To do so, you need to run the following command:
|
|
16
16
|
|
|
17
|
-
|
|
18
|
-
|
|
17
|
+
|
|
18
|
+
```bash Spree CLI (Docker)
|
|
19
|
+
spree bundle add spree_razorpay_checkout && spree generate spree_razorpay_checkout:install
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
```bash Without Spree CLI
|
|
23
|
+
bundle add spree_razorpay_checkout && bin/rails g spree_razorpay_checkout:install
|
|
19
24
|
```
|
|
20
25
|
|
|
26
|
+
|
|
21
27
|
After that, you need to make sure to restart the server.
|
|
22
28
|
|
|
23
29
|
## Connect Razorpay
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: "Connect Stripe payments to Spree Commerce"
|
|
3
3
|
sidebarTitle: Stripe
|
|
4
|
-
description: "
|
|
4
|
+
description: "Set up Spree's native Stripe integration to accept cards and alternative payment methods, automate payouts, and power marketplace split payments on Enterprise."
|
|
5
5
|
---
|
|
6
6
|
|
|
7
7
|
Stripe is a widely used payment processor that enables secure and seamless transactions for online businesses. It supports multiple payment methods, automates payouts, and ensures a smooth checkout experience for customers.
|
|
@@ -12,10 +12,16 @@ Stripe is a widely used payment processor that enables secure and seamless trans
|
|
|
12
12
|
|
|
13
13
|
Before you can enable Stripe, it must be installed. To do so, you need to run the following command:
|
|
14
14
|
|
|
15
|
-
|
|
16
|
-
|
|
15
|
+
|
|
16
|
+
```bash Spree CLI (Docker)
|
|
17
|
+
spree bundle add spree_stripe && spree generate spree_stripe:install
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
```bash Without Spree CLI
|
|
21
|
+
bundle add spree_stripe && bin/rails g spree_stripe:install
|
|
17
22
|
```
|
|
18
23
|
|
|
24
|
+
|
|
19
25
|
After that, you need to make sure to restart the server.
|
|
20
26
|
|
|
21
27
|
## Connect Stripe
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: Meilisearch
|
|
3
|
-
description: "Set up Meilisearch for fast, typo-tolerant product search with faceted filtering"
|
|
3
|
+
description: "Set up Meilisearch in Spree for fast, typo-tolerant product search with faceted filtering, relevance ranking, and sub-50ms responses across large catalogs."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
## Overview
|
|
@@ -51,10 +51,16 @@ docker run -d --name meilisearch \
|
|
|
51
51
|
gem 'meilisearch', '>= 0.28'
|
|
52
52
|
```
|
|
53
53
|
|
|
54
|
-
|
|
54
|
+
|
|
55
|
+
```bash Spree CLI (Docker)
|
|
56
|
+
spree bundle install
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
```bash Without Spree CLI
|
|
55
60
|
bundle install
|
|
56
61
|
```
|
|
57
62
|
|
|
63
|
+
|
|
58
64
|
### 3. Configure environment variables
|
|
59
65
|
|
|
60
66
|
```bash
|
|
@@ -76,10 +82,16 @@ Spree.search_provider = 'Spree::SearchProvider::Meilisearch'
|
|
|
76
82
|
|
|
77
83
|
### 5. Index your products
|
|
78
84
|
|
|
79
|
-
|
|
80
|
-
|
|
85
|
+
|
|
86
|
+
```bash Spree CLI (Docker)
|
|
87
|
+
spree rake spree:search:reindex
|
|
81
88
|
```
|
|
82
89
|
|
|
90
|
+
```bash Without Spree CLI
|
|
91
|
+
bundle exec rake spree:search:reindex
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
|
|
83
95
|
That's it. Your Store API now uses Meilisearch for all product search, filtering, and faceted navigation.
|
|
84
96
|
|
|
85
97
|
## How It Works
|
|
@@ -138,10 +150,16 @@ Each store gets its own Meilisearch index: `{store_code}_products`. For a store
|
|
|
138
150
|
|
|
139
151
|
### Reindex all products
|
|
140
152
|
|
|
141
|
-
|
|
142
|
-
|
|
153
|
+
|
|
154
|
+
```bash Spree CLI (Docker)
|
|
155
|
+
spree rake spree:search:reindex
|
|
143
156
|
```
|
|
144
157
|
|
|
158
|
+
```bash Without Spree CLI
|
|
159
|
+
bundle exec rake spree:search:reindex
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
|
|
145
163
|
### Index a single product
|
|
146
164
|
|
|
147
165
|
```ruby
|
|
@@ -12,10 +12,16 @@ Avalara AvaTax is an automated tax compliance platform that calculates accurate
|
|
|
12
12
|
|
|
13
13
|
Before you can enable Avalara AvaTax, it must be installed. To do so, run the following command:
|
|
14
14
|
|
|
15
|
-
|
|
16
|
-
|
|
15
|
+
|
|
16
|
+
```bash Spree CLI (Docker)
|
|
17
|
+
spree bundle add spree_avatax_official && spree generate spree_avatax_official:install
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
```bash Without Spree CLI
|
|
21
|
+
bundle add spree_avatax_official && bin/rails g spree_avatax_official:install
|
|
17
22
|
```
|
|
18
23
|
|
|
24
|
+
|
|
19
25
|
After that, make sure to restart the server.
|
|
20
26
|
|
|
21
27
|
## Connect Avalara
|