spree_extension 1.0.2 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0b9ca26be3caa2eeb5e4cca4ab3636961cf6a75b12d00ca4fe0de0d6ebc28613
-  data.tar.gz: ef6e6d1fd78d5cb75073c8f74fa01e1ce6d495dbbb790bf0e67c80a59db4cae6
+  metadata.gz: 9bef5f7e05cc526f9d92c913907758c4b2103ada2ec9371057aa07ac7b22d3df
+  data.tar.gz: 8d3b4021d2bf8d9a4523b3e35c334fc918613a23b8e1228056ff7e534711157e
 SHA512:
-  metadata.gz: 4fb05a17393aa6d2248bb662cb1803964c5b748d5f78c45f260e2c0ea839013693ca247da47a57a90fe8b73d686fdbebcdd93c9db20c0884a2a8571370aba862
-  data.tar.gz: 5a1ff4024e17c3d7f50df28f147aa3d12fd79863ee6ddc4a1f96353e24498ac406ab26944ba216a6eb84871166d0f38f376fe10fbf43d9c892d26e0180591864
+  metadata.gz: fac446b3fa9c4e0cfec8728f005360ba43faa48c077e07b7f4494ac987158224e72d31cf08f21caf5b370c15d077e19f564fa2e19fa601cd470c93972ed6e27e
+  data.tar.gz: 1fcac2564531a2d227a3229dfac120bd1ee4f9facde719c6460aa7e08e717063d3694eb4d6bdcaaface5d8d78fa39843b8ef5e8732934bf7e44dbbbb59f95cca

data/README.md

@@ -4,6 +4,15 @@
 
 CLI tool for generating and managing Spree Commerce extensions.
 
+## Compatibility
+
+| spree_extension | Spree |
+|---|---|
+| 2.x | 6.0+ |
+| 1.x | 5.x |
+
+To scaffold an extension for Spree 5, install the 1.x version: `gem install spree_extension -v '~> 1.0'`.
+
 ## Installation
 
 ```bash
@@ -18,7 +27,13 @@ gem install spree_extension
 spree-extension create my_extension
 ```
 
-This creates a `spree_my_extension` directory with a complete extension scaffold including engine setup, tests, CI configuration, and more.
+This creates a `spree_my_extension` directory with a complete extension scaffold: a Rails engine depending on `spree_core` and `spree_api`, directories for models, Store and Admin API controllers and serializers, services and event subscribers, an initializer for permission scopes and workflow hooks, a test setup based on [spree_dev_tools](https://github.com/spree/spree_dev_tools), and CI configuration.
+
+An extension is backend code only. Admin screens for your extension are built as a [dashboard plugin](https://spreecommerce.org/docs/developer/dashboard/plugins/overview), scaffolded with:
+
+```bash
+npx @spree/cli plugin new my-extension
+```
 
 ### Check version
 
@@ -37,7 +52,7 @@ bundle exec rspec
 
 ## Documentation
 
-For more information on developing Spree extensions, see the [Spree Developer Documentation](https://docs.spreecommerce.org/developer).
+For a walkthrough of building an extension, see [Creating a Spree extension](https://spreecommerce.org/docs/developer/contributing/creating-an-extension).
 
 ## License
 

data/lib/spree_extension/extension.rb

@@ -19,18 +19,15 @@ module SpreeExtension
       directory 'bin',      "#{file_name}/bin"
       directory 'spec',     "#{file_name}/spec"
 
-      empty_directory "#{file_name}/app/models/#{file_name}"
-      empty_directory "#{file_name}/app/views/spree"
-      empty_directory "#{file_name}/app/controllers/spree/admin"
-      empty_directory "#{file_name}/app/controllers/#{file_name}"
-      empty_directory "#{file_name}/app/services/#{file_name}"
-      empty_directory "#{file_name}/app/serializers/spree/api/v3"
+      empty_directory "#{file_name}/app/models/spree"
+      empty_directory "#{file_name}/app/controllers/spree/api/v3/store"
+      empty_directory "#{file_name}/app/controllers/spree/api/v3/admin"
       empty_directory "#{file_name}/app/serializers/spree/api/v3/admin"
-      empty_directory "#{file_name}/vendor/javascript"
-      empty_directory "#{file_name}/vendor/stylesheets"
+      empty_directory "#{file_name}/app/services/#{file_name}"
+      empty_directory "#{file_name}/app/subscribers/#{file_name}"
+      empty_directory "#{file_name}/db/migrate"
 
       chmod "#{file_name}/bin/rails", 0o755
-      chmod "#{file_name}/bin/importmap", 0o755
 
       template 'extension.gemspec', "#{file_name}/#{file_name}.gemspec"
       template 'Gemfile', "#{file_name}/Gemfile"
@@ -41,7 +38,6 @@ module SpreeExtension
       template 'config/routes.rb', "#{file_name}/config/routes.rb"
       template 'config/locales/en.yml', "#{file_name}/config/locales/en.yml"
       template 'config/initializers/spree.rb', "#{file_name}/config/initializers/spree.rb"
-      template 'config/importmap.rb', "#{file_name}/config/importmap.rb"
 
       template 'rspec', "#{file_name}/.rspec"
       template '.github/workflows/tests.yml', "#{file_name}/.github/workflows/tests.yml"
@@ -57,7 +53,9 @@ module SpreeExtension
         Congrats, Your Spree #{human_name} extension has been generated 🚀
 
         Next steps:
-        * Read Spree Developer Documentation at: https://docs.spreecommerce.org/developer
+        * cd #{file_name} && bundle install && bundle exec rake test_app
+        * Read the extension guide: https://spreecommerce.org/docs/developer/contributing/creating-an-extension
+        * Admin screens are built as a dashboard plugin: npx @spree/cli plugin new #{file_name.delete_prefix('spree_').tr('_', '-')}
 
         #{'*' * 80}
       }

data/lib/spree_extension/templates/extension/Gemfile

@@ -1,25 +1,27 @@
 source 'https://rubygems.org'
 
-gem 'rails-controller-testing'
-
 spree_opts = if ENV['SPREE_PATH']
-                { 'path': ENV['SPREE_PATH'] }
+               { 'path': ENV['SPREE_PATH'] }
              else
-                { 'github': 'spree/spree', 'branch': 'main', 'glob': 'spree/**/*.gemspec' }
+               { 'github': 'spree/spree', 'branch': 'main', 'glob': 'spree/**/*.gemspec' }
              end
+# spree provides the spree:install generator used by `rake test_app`
 gem 'spree', spree_opts
-gem 'spree_admin', spree_opts
+gem 'spree_core', spree_opts
+gem 'spree_api', spree_opts
+
+gem 'spree_dev_tools', '>= 1.0.0.beta2'
 
-gem 'spree_dev_tools', '>= 0.6.0.rc1'
+# json 3.0 made JSON.parse options keyword-only, which Active Support 8.1 does
+# not support yet. Remove the pin once Rails ships a compatible release.
+gem 'json', '< 3'
 
 if ENV['DB'] == 'mysql'
   gem 'mysql2'
 elsif ENV['DB'] == 'postgres'
   gem 'pg'
 else
-  gem 'sqlite3'
+  gem 'sqlite3', '>= 2.0'
 end
 
-gem 'propshaft'
-
 gemspec

data/lib/spree_extension/templates/extension/README.md

@@ -2,26 +2,41 @@
 
 This is a <%= human_name %> extension for [Spree Commerce](https://spreecommerce.org), an open source e-commerce platform built with Ruby on Rails.
 
+Requires Spree 6.0 or later.
+
 ## Installation
 
 1. Add this extension to your Gemfile with this line:
 
-    ```ruby
+    ```bash
     bundle add <%= file_name %>
     ```
 
-2. Run the install generator
+2. Run the install generator to copy and run the extension's migrations
 
-    ```ruby
-    bundle exec rails g <%= file_name %>:install
+    ```bash
+    bin/rails g <%= file_name %>:install
     ```
 
 3. Restart your server
 
-  If your server was running, restart it so that it can find the assets properly.
-
 ## Developing
 
+An extension is backend code only: models, migrations, Store and Admin API endpoints, permissions, workflow hooks and event subscribers.
+
+| Part of the feature | Where it lives |
+|---|---|
+| Models, migrations, business logic | `app/models`, `app/services`, `db/migrate` |
+| API endpoints | `app/controllers/spree/api/v3/{store,admin}`, `app/serializers/spree/api/v3`, `config/routes.rb` |
+| Decorators (last resort) | `app/models/spree/*_decorator.rb` |
+| Event subscribers | `app/subscribers/<%= file_name %>` |
+| Permission scopes, workflow hooks, subscriber registration, registries | `config/initializers/spree.rb` |
+| Decorator loading, `additional_permitted_attributes` | `lib/<%= file_name %>/engine.rb` |
+| Admin screens | A [dashboard plugin](https://spreecommerce.org/docs/developer/dashboard/plugins/overview) — scaffold one with `npx @spree/cli plugin new <%= file_name.delete_prefix('spree_').tr('_', '-') %>` |
+| Storefront pages | Your storefront application, through `@spree/sdk` |
+
+See [Creating a Spree extension](https://spreecommerce.org/docs/developer/contributing/creating-an-extension) for a walkthrough.
+
 1. Create a dummy app
 
     ```bash
@@ -29,6 +44,8 @@ This is a <%= human_name %> extension for [Spree Commerce](https://spreecommerce
     bundle exec rake test_app
     ```
 
+    Run this again whenever you add a migration.
+
 2. Add your new code
 3. Run tests
 
@@ -36,6 +53,12 @@ This is a <%= human_name %> extension for [Spree Commerce](https://spreecommerce
     bundle exec rspec
     ```
 
+To develop against a local checkout of Spree, point `SPREE_PATH` at the `spree` directory of the monorepo:
+
+```bash
+SPREE_PATH=../spree/spree bundle update
+```
+
 When testing your applications integration with this extension you may use it's factories.
 Simply add this require statement to your spec_helper:
 

data/lib/spree_extension/templates/extension/Rakefile

@@ -17,7 +17,5 @@ end
 desc 'Generates a dummy app for testing'
 task :test_app do
   ENV['LIB_NAME'] = '<%=file_name%>'
-  Rake::Task['extension:test_app'].execute(
-    install_admin: true
-  )
+  Rake::Task['extension:test_app'].execute
 end

data/lib/spree_extension/templates/extension/config/initializers/spree.rb.tt

@@ -1,23 +1,27 @@
-# Uncomment lines below to add your own custom business logic
-# such as promotions, shipping methods, etc.
-Rails.application.config.after_initialize do
-  # Spree.shipping_methods << Spree::ShippingMethods::SuperExpensiveNotVeryFastShipping
-  # Spree.payment_methods << Spree::PaymentMethods::VerySafeAndReliablePaymentMethod
-
-  # Spree.calculators.tax_rates << Spree::TaxRates::FinanceTeamForcedMeToCodeThis
-
-  # Spree.stock_splitters << Spree::Stock::Splitters::SecretLogicSplitter
+# Register your extension with Spree here. This file is loaded by the host
+# application at boot, like any other initializer.
+#
+# Permission scopes: adds read_<name> and write_<name> permissions for staff
+# roles and secret API keys. Use `scoped_resource :<name>` in your Admin API
+# controllers to require them.
+# Spree.permissions.register_scope(:my_resources, group: :catalog, resources: -> {
+#   [Spree::MyResource]
+# })
+#
+# Workflow hooks: run your code at a named point inside a Spree workflow.
+# Hook names are validated at boot, so a typo fails at startup.
+# Spree.hooks.register('products.activate.validate', '<%= class_name %>::MyValidator')
 
-  # Spree.adjusters << Spree::Adjustable::Adjuster::TaxTheRich
-
-  # Custom promotions
-  # Spree.calculators.promotion_actions_create_adjustments << Spree::Calculators::PromotionActions::CreateAdjustments::AddDiscountForFriends
-  # Spree.calculators.promotion_actions_create_item_adjustments << Spree::Calculators::PromotionActions::CreateItemAdjustments::FinanceTeamForcedMeToCodeThis
-  # Spree.promotions.rules << Spree::Promotions::Rules::OnlyForVIPCustomers
-  # Spree.promotions.actions << Spree::Promotions::Actions::GiftWithPurchase
-
-  # Spree.taxon_rules << Spree::TaxonRules::ProductsWithColor
+Rails.application.config.after_initialize do
+  # Event subscribers (app/subscribers) — `bin/rails g spree:subscriber` adds
+  # registrations here.
+  # Spree.subscribers << <%= class_name %>::MySubscriber
 
-  # Spree.exports << Spree::Exports::Payments
-  # Spree.reports << Spree::Reports::MassivelyOvercomplexReportForCfo
+  # Registries: custom payment methods, calculators, promotion rules, etc.
+  # Spree.payment_methods << Spree::PaymentMethods::VerySafeAndReliablePaymentMethod
+  # Spree.calculators.shipping_methods << Spree::Calculator::Shipping::SuperExpensiveNotVeryFastShipping
+  # Spree.promotions.rules << Spree::Promotion::Rules::OnlyForVIPCustomers
+  # Spree.promotions.actions << Spree::Promotion::Actions::GiftWithPurchase
+  # Spree.stock_splitters << Spree::Stock::Splitter::SecretLogicSplitter
+  # Rails.application.config.spree.collection_rules << MyExtension::CollectionRules::ProductsWithColor
 end

data/lib/spree_extension/templates/extension/config/locales/en.yml.tt

@@ -1,7 +1,5 @@
-# Sample localization file for English. Add more files in this directory for other locales.
-# See https://github.com/svenfuchs/rails-i18n/tree/master/rails%2Flocale for starting points.
-
+---
 en:
   spree:
     <%= file_name.gsub('spree_', '') %>:
-      hello: "Hello <%= class_name %>"
+      hello: Hello <%= class_name %>

data/lib/spree_extension/templates/extension/config/routes.rb

@@ -1,3 +1,15 @@
 Spree::Core::Engine.add_routes do
-  # Add your extension routes here
+  # Add your extension routes here, e.g.:
+  #
+  # namespace :api, defaults: { format: 'json' } do
+  #   namespace :v3 do
+  #     namespace :store do
+  #       resources :my_resources, only: [:index, :show]
+  #     end
+  #
+  #     namespace :admin do
+  #       resources :my_resources
+  #     end
+  #   end
+  # end
 end

data/lib/spree_extension/templates/extension/extension.gemspec

@@ -16,13 +16,13 @@ Gem::Specification.new do |s|
   s.homepage  = 'https://github.com/<%= file_name %>'
   s.license   = 'MIT'
 
-  s.files        = Dir["{app,config,db,lib,vendor}/**/*", "LICENSE.md", "Rakefile", "README.md"].reject { |f| f.match(/^spec/) && !f.match(/^spec\/fixtures/) }
+  s.files        = Dir["{app,config,db,lib}/**/*", "LICENSE.md", "Rakefile", "README.md"].reject { |f| f.match(/^spec/) && !f.match(/^spec\/fixtures/) }
   s.require_path = 'lib'
   s.requirements << 'none'
 
-  spree_version = '>= 5.4.0.beta'
-  s.add_dependency 'spree', spree_version
-  s.add_dependency 'spree_admin', spree_version
+  spree_version = '>= 6.0.0.beta'
+  s.add_dependency 'spree_core', spree_version
+  s.add_dependency 'spree_api', spree_version
 
   s.add_development_dependency 'spree_dev_tools'
 end

data/lib/spree_extension/templates/extension/lib/%file_name%/engine.rb.tt

@@ -4,6 +4,7 @@ module <%= class_name %>
     isolate_namespace Spree
     engine_name '<%= file_name %>'
 
+    # use rspec for tests
     config.generators do |g|
       g.test_framework :rspec
     end
@@ -12,19 +13,21 @@ module <%= class_name %>
       <%= class_name %>::Config = <%= class_name %>::Configuration.new
     end
 
-    initializer '<%= file_name %>.assets' do |app|
-      if app.config.respond_to?(:assets)
-        app.config.assets.paths << root.join('app/javascript')
-        app.config.assets.precompile += %w[<%= file_name %>_manifest]
+    # Runs on boot and before every code reload in development.
+    config.to_prepare do
+      # Decorators are not loaded automatically. Prefer workflow hooks, events
+      # and additional_permitted_attributes, and use decorators as a last resort.
+      Dir.glob(<%= class_name %>::Engine.root.join('app/**/*_decorator*.rb')) do |decorator|
+        Rails.configuration.cache_classes ? require(decorator) : load(decorator)
       end
-    end
 
-    initializer '<%= file_name %>.importmap', before: 'importmap' do |app|
-      if app.config.respond_to?(:importmap)
-        app.config.importmap.paths << root.join('config/importmap.rb')
-        # https://github.com/rails/importmap-rails?tab=readme-ov-file#sweeping-the-cache-in-development-and-test
-        app.config.importmap.cache_sweepers << root.join('app/javascript')
-      end
+      # Make your own columns writable through the existing Store and Admin API
+      # endpoints. Always append with +=, so attributes added by other
+      # extensions are kept.
+      # Spree::Product.additional_permitted_attributes += [:my_column]
     end
+
+    # Event subscribers, permission scopes, hooks and registry entries are
+    # registered in config/initializers/spree.rb.
   end
 end

data/lib/spree_extension/templates/extension/lib/%file_name%.rb.tt

@@ -1,7 +1,8 @@
-require 'spree'
-require '<%=file_name%>/engine'
-require '<%=file_name%>/version'
-require '<%=file_name%>/configuration'
+require 'spree_core'
+require 'spree_api'
+require '<%= file_name %>/engine'
+require '<%= file_name %>/version'
+require '<%= file_name %>/configuration'
 
 module <%= class_name %>
   mattr_accessor :queue

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: spree_extension
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 2.0.0
 platform: ruby
 authors:
 - Spark Solutions Sp. z o.o.
@@ -50,15 +50,9 @@ files:
 - lib/spree_extension/templates/extension/README.md
 - lib/spree_extension/templates/extension/Rakefile
 - lib/spree_extension/templates/extension/app/.gitkeep
-- lib/spree_extension/templates/extension/app/assets/config/%file_name%_manifest.js.tt
-- lib/spree_extension/templates/extension/app/assets/images/.keep
-- lib/spree_extension/templates/extension/app/javascript/%file_name%/application.js.tt
-- lib/spree_extension/templates/extension/app/javascript/%file_name%/controllers/%file_name%_controller.js.tt
 - lib/spree_extension/templates/extension/app/jobs/%file_name%/base_job.rb.tt
-- lib/spree_extension/templates/extension/bin/importmap
 - lib/spree_extension/templates/extension/bin/rails.tt
 - lib/spree_extension/templates/extension/config/i18n-tasks.yml
-- lib/spree_extension/templates/extension/config/importmap.rb.tt
 - lib/spree_extension/templates/extension/config/initializers/spree.rb.tt
 - lib/spree_extension/templates/extension/config/locales/en.yml.tt
 - lib/spree_extension/templates/extension/config/routes.rb
@@ -96,7 +90,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.2
+rubygems_version: 4.0.3
 specification_version: 4
 summary: Spree Extension Generator
 test_files: []

data/lib/spree_extension/templates/extension/app/assets/config/%file_name%_manifest.js.tt

@@ -1,5 +0,0 @@
-//= link_tree ../images
-//= link <%= file_name %>/application.js
-//= link_tree ../../javascript/<%= file_name %>/controllers .js
-//= link_tree ../../../vendor/javascript .js
-//= link_tree ../../../vendor/stylesheets .css

data/lib/spree_extension/templates/extension/app/javascript/%file_name%/application.js.tt

@@ -1,16 +0,0 @@
-import '@hotwired/turbo-rails'
-import { Application } from '@hotwired/stimulus'
-
-let application
-
-if (typeof window.Stimulus === "undefined") {
-  application = Application.start()
-  application.debug = false
-  window.Stimulus = application
-} else {
-  application = window.Stimulus
-}
-
-import <%= class_name %>Controller from '<%= file_name %>/controllers/<%= file_name %>_controller' 
-
-application.register('<%= file_name %>', <%= class_name %>Controller)

data/lib/spree_extension/templates/extension/app/javascript/%file_name%/controllers/%file_name%_controller.js.tt

@@ -1,7 +0,0 @@
-import { Controller } from '@hotwired/stimulus'
-
-export default class extends Controller {
-  connect() {
-    console.log('Hello, <%= class_name %>!')
-  }
-}

data/lib/spree_extension/templates/extension/bin/importmap

@@ -1,9 +0,0 @@
-#!/usr/bin/env ruby
-
-ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../Gemfile', __dir__)
-require 'bundler/setup' if File.exist?(ENV['BUNDLE_GEMFILE'])
-
-require 'rails'
-
-require 'importmap-rails'
-require 'importmap/commands'

data/lib/spree_extension/templates/extension/config/importmap.rb.tt

@@ -1,6 +0,0 @@
-pin 'application-<%= file_name.tr("_","-") %>', to: '<%= file_name %>/application.js', preload: false
-
-pin_all_from <%= class_name %>::Engine.root.join('app/javascript/<%= file_name %>/controllers'),
-             under: '<%= file_name %>/controllers',
-             to:    '<%= file_name %>/controllers',
-             preload: 'application-<%= file_name.tr("_","-") %>'