@spree/docs 0.1.89 → 0.1.91
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 +16 -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 +14 -2
- package/dist/developer/customization/decorators.md +14 -2
- package/dist/developer/customization/emails.md +7 -1
- package/dist/developer/customization/model-preferences.md +16 -4
- package/dist/developer/deployment/caching.md +7 -2
- package/dist/developer/deployment/environment_variables.md +8 -2
- package/dist/developer/multi-store/quickstart.md +7 -1
- package/dist/developer/multi-tenant/core-concepts.md +7 -1
- package/dist/developer/multi-tenant/installation.md +27 -5
- package/dist/developer/multi-vendor/installation.md +19 -3
- package/dist/developer/sdk/admin/authentication.md +3 -2
- package/dist/developer/sdk/admin/querying-and-errors.md +3 -2
- package/dist/developer/sdk/admin/quickstart.md +2 -2
- package/dist/developer/sdk/admin/resources.md +3 -2
- package/dist/developer/sdk/quickstart.md +3 -2
- package/dist/developer/tutorial/api.md +2 -1
- package/dist/developer/upgrades/5.4-to-5.5.md +39 -15
- package/dist/integrations/analytics/google-analytics.md +8 -2
- package/dist/integrations/analytics/google-tag-manager.md +8 -2
- package/dist/integrations/marketing/klaviyo.md +8 -2
- package/dist/integrations/payments/adyen.md +8 -2
- package/dist/integrations/payments/paypal.md +8 -2
- package/dist/integrations/payments/razorpay.md +9 -3
- package/dist/integrations/payments/stripe.md +8 -2
- package/dist/integrations/search/meilisearch.md +23 -5
- 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
|
|
@@ -147,16 +147,28 @@ If you have admin-related code in non-standard locations, add additional `@sourc
|
|
|
147
147
|
|
|
148
148
|
During development, run the Tailwind CSS watcher to automatically rebuild styles when you make changes:
|
|
149
149
|
|
|
150
|
-
|
|
151
|
-
|
|
150
|
+
|
|
151
|
+
```bash Spree CLI (Docker)
|
|
152
|
+
spree rake spree:admin:tailwindcss:watch
|
|
152
153
|
```
|
|
153
154
|
|
|
154
|
-
|
|
155
|
+
```bash Without Spree CLI
|
|
156
|
+
bundle exec rake spree:admin:tailwindcss:watch
|
|
157
|
+
```
|
|
155
158
|
|
|
156
|
-
|
|
159
|
+
|
|
160
|
+
Or run the full development process, which includes the watcher when it's defined in `Procfile.dev`:
|
|
161
|
+
|
|
162
|
+
|
|
163
|
+
```bash Spree CLI (Docker)
|
|
164
|
+
spree dev
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
```bash Without Spree CLI
|
|
157
168
|
bin/dev
|
|
158
169
|
```
|
|
159
170
|
|
|
171
|
+
|
|
160
172
|
The watcher monitors:
|
|
161
173
|
- Your host app's CSS files in `app/assets/tailwind/`
|
|
162
174
|
- 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).
|
|
@@ -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
|
|
@@ -12,10 +12,16 @@ Spree uses [postmark templates](https://github.com/wildbit/postmark-templates),
|
|
|
12
12
|
|
|
13
13
|
Spree offers an emails preview generator for development purposes. To generate them, use the command:
|
|
14
14
|
|
|
15
|
-
|
|
15
|
+
|
|
16
|
+
```bash Spree CLI (Docker)
|
|
17
|
+
spree generate spree:emails:install
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
```bash Without Spree CLI
|
|
16
21
|
bin/rails g spree:emails:install
|
|
17
22
|
```
|
|
18
23
|
|
|
24
|
+
|
|
19
25
|
After that, start the rails server locally and go to: `localhost:3000/rails/mailers`
|
|
20
26
|
|
|
21
27
|
(it requires a seeded development database in order to work properly)
|
|
@@ -15,16 +15,28 @@ To define a model preference, you need to add them to your model class.
|
|
|
15
15
|
|
|
16
16
|
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
17
|
|
|
18
|
-
|
|
19
|
-
|
|
18
|
+
|
|
19
|
+
```bash Spree CLI (Docker)
|
|
20
|
+
spree generate migration AddPreferencesToSpreeUsers preferences:text
|
|
20
21
|
```
|
|
21
22
|
|
|
23
|
+
```bash Without Spree CLI
|
|
24
|
+
bin/rails g migration AddPreferencesToSpreeUsers preferences:text
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
|
|
22
28
|
Run the migration.
|
|
23
29
|
|
|
24
|
-
|
|
25
|
-
|
|
30
|
+
|
|
31
|
+
```bash Spree CLI (Docker)
|
|
32
|
+
spree migrate
|
|
26
33
|
```
|
|
27
34
|
|
|
35
|
+
```bash Without Spree CLI
|
|
36
|
+
bin/rails db:migrate
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
|
|
28
40
|
```ruby
|
|
29
41
|
class Spree::User < ApplicationRecord
|
|
30
42
|
# ... you existing code ...
|
|
@@ -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 |
|
|
@@ -5,10 +5,16 @@ sidebarTitle: Quickstart
|
|
|
5
5
|
|
|
6
6
|
To enable multiple stores, you will need to add the `spree_multi_store` gem to your project via:
|
|
7
7
|
|
|
8
|
-
|
|
8
|
+
|
|
9
|
+
```bash Spree CLI (Docker)
|
|
10
|
+
spree bundle add spree_multi_store
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
```bash Without Spree CLI
|
|
9
14
|
bundle add spree_multi_store
|
|
10
15
|
```
|
|
11
16
|
|
|
17
|
+
|
|
12
18
|
> **INFO:** Spree Multi-Store is licensed under the [AGPL v3 License](https://opensource.org/licenses/AGPL-3.0).
|
|
13
19
|
>
|
|
14
20
|
> If you would like to use it in a commercial application, please [contact us](https://spreecommerce.org/get-started/) to obtain a commercial license.
|
|
@@ -17,10 +17,16 @@ All models that are tenanted inherit from `SpreeMultiTenant::Base` class. `spree
|
|
|
17
17
|
|
|
18
18
|
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
19
|
|
|
20
|
-
|
|
20
|
+
|
|
21
|
+
```bash Spree CLI (Docker)
|
|
22
|
+
spree generate model Spree::NewModel tenant:references name:string --parent SpreeMultiTenant::Base
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
```bash Without Spree CLI
|
|
21
26
|
bin/rails g model Spree::NewModel tenant:references name:string --parent SpreeMultiTenant::Base
|
|
22
27
|
```
|
|
23
28
|
|
|
29
|
+
|
|
24
30
|
> **INFO:** You don't need to add `belongs_to :tenant` to the model, it's handled by gem.
|
|
25
31
|
|
|
26
32
|
## Tenant selector
|
|
@@ -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.
|
|
@@ -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.
|
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
---
|
|
2
|
-
title: "
|
|
3
|
-
|
|
2
|
+
title: "Admin SDK authentication with API keys and JWT cookies"
|
|
3
|
+
sidebarTitle: "Authentication"
|
|
4
|
+
description: "Authenticate @spree/admin-sdk with a secret API key for server-to-server, scope-based access or JWT cookie auth for role-based browser admin apps."
|
|
4
5
|
---
|
|
5
6
|
|
|
6
7
|
The Admin API supports two authentication methods. Both reach the same endpoints — they differ in **where the credential lives** and **how authorization is decided**:
|
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
---
|
|
2
|
-
title: "
|
|
3
|
-
|
|
2
|
+
title: "Filtering, pagination, and error handling in the Admin SDK"
|
|
3
|
+
sidebarTitle: "Querying & Errors"
|
|
4
|
+
description: "Filter, sort, paginate, and expand Admin API collections with flat Ransack parameters and handle structured SpreeError responses from @spree/admin-sdk."
|
|
4
5
|
---
|
|
5
6
|
|
|
6
7
|
## Filtering
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
|
-
title: "Admin SDK"
|
|
2
|
+
title: "Admin SDK quickstart for @spree/admin-sdk"
|
|
3
3
|
sidebarTitle: Quickstart
|
|
4
|
-
description: "
|
|
4
|
+
description: "Install and configure @spree/admin-sdk, the official TypeScript client for the Spree Admin API v3, to manage products, orders, customers, and stock."
|
|
5
5
|
---
|
|
6
6
|
|
|
7
7
|
[`@spree/admin-sdk`](https://www.npmjs.com/package/@spree/admin-sdk) is the official TypeScript SDK for the [Admin API v3](../../../api-reference/admin-api/introduction.md) — the back-office counterpart to [`@spree/sdk`](../quickstart.md). Use it to build integrations, automations, internal tools, and custom admin UIs: manage products, orders, customers, stock, promotions, webhooks, and more.
|
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
---
|
|
2
|
-
title: "
|
|
3
|
-
|
|
2
|
+
title: "Admin SDK resources and CRUD client methods"
|
|
3
|
+
sidebarTitle: "Resources"
|
|
4
|
+
description: "Reference for every @spree/admin-sdk resource — products, orders, customers, inventory, pricing, promotions, store configuration, and platform clients."
|
|
4
5
|
---
|
|
5
6
|
|
|
6
7
|
Every Admin API resource is exposed as a property on the client (`client.orders`, `client.products`, …). Collection resources follow a consistent CRUD shape — `list`, `get`, `create`, `update`, `delete` — plus resource-specific actions. Nested resources take the **parent ID as the first argument**:
|
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
---
|
|
2
|
-
title:
|
|
3
|
-
|
|
2
|
+
title: Spree TypeScript SDK quickstart for the Store API
|
|
3
|
+
sidebarTitle: Quickstart
|
|
4
|
+
description: Install @spree/sdk, configure the Store API client, and make your first calls to products, carts, checkout, and customer account endpoints from TypeScript.
|
|
4
5
|
---
|
|
5
6
|
|
|
6
7
|
`@spree/sdk` is the customer-facing SDK — products, carts, checkout, and account flows against the Store API. For back-office integrations (managing products, orders, customers, stock), use the [Admin SDK](admin/quickstart.md).
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
---
|
|
2
|
-
title:
|
|
2
|
+
title: Expose a custom model through the Store and Admin APIs
|
|
3
|
+
sidebarTitle: API
|
|
3
4
|
description: Expose your custom Brand model through the Spree Store and Admin REST APIs with serializers, controllers, routes, and the spree:api_resource generator.
|
|
4
5
|
---
|
|
5
6
|
|
|
@@ -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
|
|
|
@@ -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
|
|
@@ -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
|
|
@@ -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
|
|
@@ -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
|
|
@@ -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
|
|
@@ -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
|
|
@@ -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
|
|
@@ -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
|