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
Updated tutorials and added Add Spree to an existing app tutorial (#10691)
Damian Legawiec33287208dc67
diff --git a/README.md b/README.mdindex b5f1179213..b22bea9636 100755--- a/README.md+++ b/README.md@@ -54,87 +54,11 @@ Admin panel credentials for your own Heroku demo:1. [Install Docker](https://docs.docker.com/get-docker/)2. Download [Spree Starter](https://github.com/spree/spree_starter/archive/main.zip)3. Unzip it-4. Run `bin/setup` in `spree_starter` directory+4. Run `bin/setup` in `spree_starter-main` directory### Option B - add Spree to an existing application-1. Add Spree gems to your `Gemfile`-- ##### Rails 6.0 and 6.1-- ```ruby- gem 'spree', '~> 4.2.0.rc3'- gem 'spree_auth_devise', '~> 4.3'- gem 'spree_gateway', '~> 3.9'- ```-- ##### Rails 5.2-- ```ruby- gem 'spree', '~> 3.7.0'- gem 'spree_auth_devise', '~> 3.5'- gem 'spree_gateway', '~> 3.4'- ```-- To see what rails version are you using run this command:-- ```bash- rails -v- ```-- Older rails versions are also supported: [Rails 5.1](https://guides.spreecommerce.org/release_notes/3_5_0.html), [Rails 5.0](https://guides.spreecommerce.org/release_notes/3_2_0.html), [Rails 4.2](https://guides.spreecommerce.org/release_notes/3_1_0.html)--2. Install gems-- ```bash- bundle install- ```-- **Note**: if you run into `Bundler could not find compatible versions for gem "sprockets":` error message, please run-- ```bash- bundle update- ```--3. Use the install generators to set up Spree-- ```shell- bundle exec rails g spree:install --user_class=Spree::User- bundle exec rails g spree:auth:install- bundle exec rails g spree_gateway:install- ```--#### Installation options--By default, the installation generator (`rails g spree:install`) will run-migrations as well as adding seed and sample data and will copy storefront data-for easy customization (if `spree_frontend` available). This can be disabled using--```shell-rails g spree:install --migrate=false --sample=false --seed=false --copy_storefront=false-```--You can always perform any of these steps later by using these commands.--```shell-bundle exec rake railties:install:migrations-bundle exec rails db:migrate-bundle exec rails db:seed-bundle exec rake spree_sample:load-bundle exec rails g spree:frontend:copy_storefront-```--#### Headless installation--To use Spree in [API-only mode](https://guides.spreecommerce.org/api/overview/) you need to replace `spree` with `spree_api` in your project Gemfile. This will skip Storefront and Admin Panel. If you would want to include the Admin Panel please add `spree_backend` to your Gemfile.--## Browse Storefront--Go to http://localhost:3000--## Browse Admin Panel--Go to http://localhost:3000/admin+1. [Please follow Add Spree to an existing Ruby on Rails application tutorial](https://guides.spreecommerce.org/developer/tutorials/getting_started_tutorial.html)## Extensionsdiff --git a/guides/src/content/developer/tutorials/deface_overrides_tutorial.md b/guides/src/content/developer/tutorials/deface_overrides_tutorial.mdindex 673d245aca..27f6357f02 100644--- a/guides/src/content/developer/tutorials/deface_overrides_tutorial.md+++ b/guides/src/content/developer/tutorials/deface_overrides_tutorial.md@@ -1,7 +1,6 @@---title: Deface Overridessection: tutorial-hidden: true---<alert kind="warning">diff --git a/guides/src/content/developer/tutorials/developing_spree.md b/guides/src/content/developer/tutorials/developing_spree.mdindex 331fdcdf95..c22caf50bf 100644--- a/guides/src/content/developer/tutorials/developing_spree.md+++ b/guides/src/content/developer/tutorials/developing_spree.md@@ -1,6 +1,7 @@---title: Developing Spreesection: tutorial+order: 2---## Overview@@ -29,7 +30,7 @@ If `bundle install` fails that means you're missing some required system librariFirstly, please [install homebew](https://brew.sh/). With homebrew installed you will need to install some packages needed to run Spree and Rails applications in general:```bash-brew install openssl mysql postgresql sqlite+brew install openssl mysql postgresql sqlite imagemagick```## Sandboxdiff --git a/guides/src/content/developer/tutorials/existing_app_tutorial.md b/guides/src/content/developer/tutorials/existing_app_tutorial.mdnew file mode 100644index 0000000000..b31aaf6dcf--- /dev/null+++ b/guides/src/content/developer/tutorials/existing_app_tutorial.md@@ -0,0 +1,149 @@+---+title: Add Spree to an existing Ruby on Rails application+section: tutorial+order: 1+---++## Prerequisites++Before starting this tutorial, please check which Rails version are you using by running:++```bash+bundle exec rails -v+```++in your project root directory.++## Installation++1. Add Spree gems to your `Gemfile`++ **Rails 6.0 and 6.1**++ ```ruby+ gem 'spree', '~> 4.2.0.rc3'+ gem 'spree_auth_devise', '~> 4.3'+ gem 'spree_gateway', '~> 3.9'+ ```++ **Rails 5.2**++ ```ruby+ gem 'spree', '~> 3.7.0'+ gem 'spree_auth_devise', '~> 3.5'+ gem 'spree_gateway', '~> 3.4'+ ```++ **Rails 5.1**++ ```ruby+ gem 'spree', '~> 3.5.0'+ gem 'spree_auth_devise', '~> 3.3'+ gem 'spree_gateway', '~> 3.3'+ ```++ **Rails 5.0**++ ```ruby+ gem 'spree', '~> 3.2.0'+ gem 'spree_auth_devise', '~> 3.2.0'+ gem 'spree_gateway', '~> 3.2.0'+ ```++2. Install gems++ ```bash+ bundle install+ ```++ **Note**: if you run into `Bundler could not find compatible versions for gem "sprockets":` error message, please run++ ```bash+ bundle update+ ```++3. Use the install generators to set up Spree++ ```shell+ bundle exec rails g spree:install --user_class=Spree::User+ bundle exec rails g spree:auth:install+ bundle exec rails g spree_gateway:install+ ```++### Installation options++By default, the installation generator (`rails g spree:install`) will run+migrations as well as adding seed and sample data and will copy storefront data+for easy customization (if `spree_frontend` available). This can be disabled using++```shell+rails g spree:install --migrate=false --sample=false --seed=false --copy_storefront=false+```++You can always perform any of these steps later by using these commands.++```shell+bundle exec rake railties:install:migrations+bundle exec rails db:migrate+bundle exec rails db:seed+bundle exec rake spree_sample:load+bundle exec rails g spree:frontend:copy_storefront+```++### Headless installation (API-mode)++To use Spree in [API-only mode](https://guides.spreecommerce.org/api/overview/) you need to replace `spree` with `spree_api` in your project Gemfile. This will skip Storefront and Admin Panel. If you would want to include the Admin Panel please add `spree_backend` to your Gemfile.++### Mounting the Spree engine++When `rails g spree:install` is run inside an application, it will install Spree, mounting the `Spree::Core::Engine` component by inserting this line automatically+into `config/routes.rb`:++```ruby+mount Spree::Core::Engine, at: '/'+```++By default, all Spree routes will be available at the root of your domain. For example, if your domain is `http://localhost:3000`, Spree’s `/products` URL will be available at `http://localhost:3000/products`.++You can customize this simply by changing the `:at` specification in `config/routes.rb` to be something else. For example, if you would like Spree to be mounted at `/shop`, you can write this:++```ruby+mount Spree::Core::Engine, at: `/shop`+```++The different parts of Spree (API, Admin) will be mounted there as well, eg. `http://localhost:3000/shop/admin`.++### Use your existing authentication++[Spree Auth Devise](https://github.com/spree/spree_auth_devise) is the default authnetication that comes with Spree but you can swap it for your own, please [follow this guide](/developer/customization/authentication.html)++## Hello, Spree Commerce++You now have a functional Spree application after running only a few commands!++To see your application in action, open a browser window and navigate to [http://localhost:3000](http://localhost:3000). You should see the Spree default home page:++++To stop the web server, hit Ctrl-C in the terminal window where it's running. In development mode, Spree does not generally require you to stop the server; changes you make in files will be automatically picked up by the server.++### Logging Into the Admin Panel++The next thing you'll probably want to do is to log into the admin interface.+Use your browser window to navigate to+[http://localhost:3000/admin](http://localhost:3000/admin). You can login with+the username `[email protected]` and password `spree123`.++Upon successful authentication, you should see the admin screen:++++Feel free to explore some of the Admin Panel features that Spree has to offer and to verify that your installation is working properly.++## Next steps++If you've followed the steps described in this tutorial, you should now have a fully functional Spree application up and running.++We recommend you should continue to [Customization section](/developer/customization/storefront.html) to learn how to modify and extend your Spree application.++To learn more about Spree internals please refer [Core section](/developer/core/orders.html).diff --git a/guides/src/content/developer/tutorials/extend_product_attributes.md b/guides/src/content/developer/tutorials/extend_product_attributes.mdindex ea17006e7f..9547701aa6 100644--- a/guides/src/content/developer/tutorials/extend_product_attributes.md+++ b/guides/src/content/developer/tutorials/extend_product_attributes.md@@ -1,7 +1,6 @@---title: 'Extend Product Attributes'section: tutorial-order: 0---## Overviewdiff --git a/guides/src/content/developer/tutorials/extensions_tutorial.md b/guides/src/content/developer/tutorials/extensions_tutorial.mdindex 41f464f394..64ec53c4ad 100644--- a/guides/src/content/developer/tutorials/extensions_tutorial.md+++ b/guides/src/content/developer/tutorials/extensions_tutorial.md@@ -7,6 +7,12 @@ section: tutorialLet's build a simple [extension](/developer/customization/extensions.html). Suppose we want the ability to mark certain products as being on sale. We'd like to be able to set a sale price on a product and show products that are on sale on a separate products page. This is a great example of how an extension can be used to build on the solid Spree foundation.+Before we start, let's make sure we have spree command installed by running:++```ruby+gem install spree+```+So let's start by generating the extension. Run the following command from a directory of your choice outside of our Spree application:```bashdiff --git a/guides/src/content/developer/tutorials/getting_started_tutorial.md b/guides/src/content/developer/tutorials/getting_started_tutorial.mdindex 6ba120e760..533b1029f5 100644--- a/guides/src/content/developer/tutorials/getting_started_tutorial.md+++ b/guides/src/content/developer/tutorials/getting_started_tutorial.md@@ -8,13 +8,16 @@ order: 0Before starting this tutorial, make sure you have [Docker](https://docs.docker.com/get-docker/) installed on your system. This is fairly straightforward, but differs depending on which operating system you use.+If you would like to add Spree to your existing Ruby on Rails application, please [follow this guide instead](/developer/tutorials/existing_app_tutorial.html).+## Installation-1. Download [Spree Starter](https://github.com/spree/spree_starter/archive/master.zip)+1. Download [Spree Starter](https://github.com/spree/spree_starter/archive/main.zip)2. Unzip it-3. Run `bin/setup` in `spree_starter` directory+3. Rename `spree_starter-main` directory as you please+4. Run `bin/setup` in said directory-## Hello, Spree!+## Hello, Spree CommerceYou now have a functional Spree application after running only a few commands!@@ -37,10 +40,12 @@ Upon successful authentication, you should see the admin screen:Feel free to explore some of the Admin Panel features that Spree has to offer and to verify that your installation is working properly.-## Wrapping Up+## Next stepsIf you've followed the steps described in this tutorial, you should now have a fully functional Spree application up and running.-We recommend you should continue to [Customization section](/developer/customization/storefront.html) to learn how to modify and extend your Spree application.+For starting/stopping/restarting application please refer to [Spree Starter README](https://github.com/spree/spree_starter#running-the-project).++We recommend you should also continue to [Customization section](/developer/customization/storefront.html) to learn how to modify and extend your Spree application.To learn more about Spree internals please refer [Core section](/developer/core/orders.html).diff --git a/guides/src/content/developer/tutorials/migration.md b/guides/src/content/developer/tutorials/migration.mdindex d7c0307fd8..90df8a35ad 100644--- a/guides/src/content/developer/tutorials/migration.md+++ b/guides/src/content/developer/tutorials/migration.md@@ -1,6 +1,7 @@---title: Migrating to Spreesection: advanced+hidden: true---## Overviewdiff --git a/guides/src/content/developer/tutorials/seo.md b/guides/src/content/developer/tutorials/seo.mdindex 0d97ef3f20..42dbcf320d 100644--- a/guides/src/content/developer/tutorials/seo.md+++ b/guides/src/content/developer/tutorials/seo.md@@ -1,7 +1,7 @@---title: 'Improve SEO'section: advanced-order: 0+order: 3---## Overviewdiff --git a/guides/src/content/developer/tutorials/testing.md b/guides/src/content/developer/tutorials/testing.mdindex 2555ae66d8..48d63e8e57 100644--- a/guides/src/content/developer/tutorials/testing.md+++ b/guides/src/content/developer/tutorials/testing.md@@ -90,55 +90,3 @@ end```This lets your Spree app behave as if this user is logged in.---#### Testing as Someone Not Logged In--For Spree 2.2 and prior, Spree keeps track of the order for a logged out user using a session variable. Here's an example that may work for you in Spree 2.2 and earlier:--```ruby-let (:order) { FactoryBot.create(:order) }-before(:each) do- page.set_rack_session(order_id: order.id)- page.set_rack_session(access_token: order.token)-end-```--In Spree 2.3, a signed cookie is used to keep track of the guest user's cart. In the example below, we make two stubs onto objects in Spree to fake-out the guest token (in this text example, we simply set it to 'xyz'). In the example, presume that the order factory will have a lineitem in it for an associated product called "Some Product":--```ruby-describe "cart to registration page", type: :feature do- let(:order) { FactoryBot.create(:order, guest_token: "xyz") }- # user should be nil for logged out user--- describe "as someone not logged in" do- before(:each) do- order- SecureRandom.stub!(:urlsafe_base64)- .with(any_args)- .and_return("xyz")-- Spree::OrdersController.any_instance- .stub(:cookies)- .and_return(mock(:cookies, signed: {guest_token: "xyz"}))- end-- it "should let me load the shopping cart page" do- visit '/cart'- page.status_code.should eq(200)- expect(page).to have_content 'Some Product'- end-end-```--$$$-TODO: We still are looking for a way to set a signed cookie on a RackTest driver. If you get that working, you can remove the stub on the Spree::OrdersController in the code example above.--Thomas Walpole thinks code like this might work, but we have yet to get this working correctly:--```ruby-kg = ActiveSupport::KeyGenerator.new(Rails.application.secrets.secret_key_base, iterations:1000)-guest_token_cookie_value_to_set = ActiveSupport::MessageVerifier.new(kg.generate_key("signed cookie"), digest: 'SHA1', serializer: ActiveSupport::MessageEncryptor::NullSerializer).generate("\"#{guest_token}\"")-```-$$$diff --git a/guides/src/content/developer/tutorials/upgrading_extensions.md b/guides/src/content/developer/tutorials/upgrading_extensions.mdindex 9e622d55f9..a569d6cf11 100644--- a/guides/src/content/developer/tutorials/upgrading_extensions.md+++ b/guides/src/content/developer/tutorials/upgrading_extensions.md@@ -1,5 +1,5 @@----title: Updating Extensions to Rails 6 and Spree 4.1+title: Updating Extensions to Rails 6 and Spree 4section: advanced---diff --git a/guides/src/content/release_notes/4_2_0.md b/guides/src/content/release_notes/4_2_0.mdindex bd1b3c0404..27db5ffb2e 100644--- a/guides/src/content/release_notes/4_2_0.md+++ b/guides/src/content/release_notes/4_2_0.md@@ -77,29 +77,10 @@ We've invested a lot of time to make the default Storefront accessible for every## Installation-### Add Spree gems to Gemfile--```ruby-gem 'spree', '~> 4.2.0.rc3'-gem 'spree_auth_devise', '~> 4.3'-gem 'spree_gateway', '~> 3.9'-```--### Run `bundle install`--**Note**: if you run into `Bundler could not find compatible versions for gem "sprockets":` error message, please run--```bash-bundle update-```--### Use the install generators to set up Spree--```shell-rails g spree:install --user_class=Spree::User-rails g spree:auth:install-rails g spree_gateway:install-```+1. [Install Docker](https://docs.docker.com/get-docker/)+2. Download [Spree Starter](https://github.com/spree/spree_starter/archive/main.zip)+3. Unzip it+4. Run `bin/setup` in `spree_starter-main` directory## Upgrade