Discourage SolidusStarterFrontend from being run as an engine

README.md

@@ -42,16 +42,8 @@ If Solidus was already installed with _solidus_frontend_ you will have to
 replace all the references of the string `Spree::Frontend::Config` in your 
 project with `SolidusStarterFrontend::Config`.
 
-You have the following 2 install methods available.
+To install:
 
-### (1) Copy our components files in your project
-With this method, our views, assets, and controllers will be copied over your 
-project and you can change easily anything that we created; this gives you a lot
-of freedom of customization. On the other hand, you won't be able to auto-update
-the storefront code with the next versions released since it will not be present
-in your Gemfile.
-
-Installation steps:
 ```shell
 $ cd your/project/
 $ gem install solidus_starter_frontend
@@ -60,18 +52,6 @@ $ solidus_starter_frontend
 
 The last command will copy all the necessary files.
 
-### (2) Add our component as gem in your project
-With this method, you simply add our gem to your application and it behaves like
-a Rails engine. In this case, our files remain in the gem and you will need to
-override the views that you want to customize or if you need different logics to
-monkey-patch the classes that we previously defined.
-
-Installation steps:
-- add to your _Gemfile_: `gem 'solidus_starter_frontend'`
-
-**IMPORTANT**: put this line before `gem 'solidus_auth_devise'` (if you are 
-using this gem) because our component has conditional references to it.
-
 ## Development
 For information about contributing to this project please refer to this
 [document](docs/development.md).

Rakefile

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require 'solidus_dev_support/rake_tasks'
+
+ENV['SOLIDUS_STARTER_FRONTEND_ALLOW_AS_ENGINE'] = 'true'
 SolidusDevSupport::RakeTasks.install
 
 task default: 'extension:specs'

docs/development.md

@@ -25,7 +25,17 @@ Simply add this require statement to your spec_helper:
 require 'solidus_starter_frontend/factories'
 ```
 
-### Running the sandbox
+### Running the extension in development
+
+In order to run the extension, you can either 1) run the sandbox script to
+generate the sandbox app or 2) add the extension as a gem in a Rails app.
+
+#### Running the sandbox
+
+The sandbox script uses the `solidus_starter_frontend:install` generator to
+install the frontend. This is useful when you want to ensure that the generator
+is working.
+
 To run this extension in a sandboxed Solidus application, you can run 
 `bin/sandbox`. The path for the sandbox app is `./sandbox` and `bin/rails` will 
 forward any Rails commands to `sandbox/bin/rails`.
@@ -42,6 +52,82 @@ Use Ctrl-C to stop
 
 Default username and password for admin are: `[email protected]` and `test123`.
 
+#### Running the extension as an engine in a Rails app
+
+You can also run the extension as a engine in a Rails app. This is useful when
+you want to automatically see changes in the app without having to rerun the
+`solidus_starter_frontend:install` generator.
+
+To run the extension in a Rails app,
+
+##### 1) Create a Rails app
+
+```sh
+rails new store
+```
+
+##### 2) Add and install Solidus with `solidus_starter_frontend` in the Rails app
+
+Add the following gems. Since we're developing `solidus_starter_frontend`, we're
+assuming that you have `solidus_starter_frontend` locally and that you want to
+point to the latest versions of the Solidus components and extensions.
+
+```rb
+solidus_repo = ENV.fetch('SOLIDUS_REPO', 'solidusio/solidus')
+solidus_branch = ENV.fetch('SOLIDUS_BRANCH', 'master')
+gem 'solidus_core', github: solidus_repo, branch: solidus_branch
+gem 'solidus_api', github: solidus_repo, branch: solidus_branch
+gem 'solidus_backend', github: solidus_repo, branch: solidus_branch
+gem 'solidus_sample', github: solidus_repo, branch: solidus_branch
+
+gem 'solidus_starter_frontend', path: 'path/to/solidus_starter_frontend'
+
+solidus_auth_devise_repo = ENV.fetch('SOLIDUS_AUTH_DEVISE_REPO', 'solidusio/solidus_auth_devise')
+solidus_auth_devise_branch = ENV.fetch('SOLIDUS_AUTH_DEVISE_BRANCH', 'master')
+gem 'solidus_auth_devise', github: solidus_auth_devise_repo, branch: solidus_auth_devise_branch
+```
+
+Note that `solidus_starter_frontend` has conditional references to
+`solidus_auth_devise`, so it's important to place `solidus_starter_frontend`
+before `solidus_auth_devise`.
+
+##### 3) Enable `SOLIDUS_STARTER_FRONTEND_ALLOW_AS_ENGINE` environment variable
+
+We're strongly encouraging people to use `solidus_starter_frontend` as a
+generator. Thus, if you want to run it as an engine, you'll need to set an
+environment variable explicitly stating so.
+
+One way to do this is to set the environment variable within an initializer:
+
+```sh
+# config/initializers/solidus_starter_frontend.rb
+ENV['SOLIDUS_STARTER_FRONTEND_ALLOW_AS_ENGINE'] = 'true'
+```
+
+##### 3) Install Solidus
+
+```sh
+bundle exec rails generate solidus:install \
+  --auto-accept \
+  --user_class=Spree::User \
+  --enforce_available_locales=true \
+  --with-authentication=false \
+  --payment-method=none
+
+bundle exec rails generate solidus:auth:install --auto-run-migrations
+```
+
+##### 4) Install the frontend assets
+
+You will need to run `bundle exec rails g solidus_starter_frontend:install` to add the
+frontend assets to the existing vendored Solidus manifest files.
+
+##### 5) Run the server
+
+```sh
+rails server
+```
+
 ### Updating the changelog
 Before and after releases the changelog should be updated to reflect the 
 up-to-date status of the project:

lib/solidus_starter_frontend/engine.rb

@@ -15,6 +15,8 @@ class Engine < Rails::Engine
     end
 
     config.to_prepare do
+      raise 'Error: SolidusStarterFrontend is not allowed to run as an engine' unless ENV['SOLIDUS_STARTER_FRONTEND_ALLOW_AS_ENGINE']
+
       if defined?(Spree::Auth::Engine)
         [
           Spree::UserConfirmationsController,

spec/spec_helper.rb

@@ -2,6 +2,7 @@
 
 # Configure Rails Environment
 ENV['RAILS_ENV'] = 'test'
+ENV['SOLIDUS_STARTER_FRONTEND_ALLOW_AS_ENGINE'] = 'true'
 
 # Run Coverage report
 require 'solidus_dev_support/rspec/coverage'