sewing_kit 0.7.1 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a7cc8acdd9a3ae14f572f3b9f403e8152e805931
-  data.tar.gz: f836bb3b228af0f0f98d243fb7665a52bb4568a3
+  metadata.gz: c158fee225e3c96470ca32e8af145fc261e9de9d
+  data.tar.gz: 41b8baaa9f319ce1bc985383f7e2a1fe6168fb3e
 SHA512:
-  metadata.gz: a3ea45f34e1d688d50d4e14e64bed8c7fa8f0d678b5d615c1efd38948be1ab38247c9a0a797740e09621dd1dbe522372838ecf2cbd50ebdb491e1a42370818f2
-  data.tar.gz: 7ed221b39eeeb80d1dcc43d7742983776d0d5d5297050bf756c8ddc8e8d67b79fee39e72c0d8b1e2d55f00412531d66f1c3d7ad643319725cf0636cacd25fb54
+  metadata.gz: c3b3adcaa26e1185fd5515387d0eb2c1c965a79f432b350601569a1a9f634175c3a703fa5ba89d151e7e185177eb8d4afc124f50cf43420391a55fcc1b4d047d
+  data.tar.gz: 35d946b5848e8353213ab8d81f7627524e435e5220d70f04f70065808f78a62dd6a948e9a28d672e683120812ffaa1b48d310cc41ce21f48c1b59a49b69d10bb

data/README.md

@@ -1,9 +1,89 @@
 # sewing_kit
 
-A solid foundation for modern FED stacks in Shopify apps.
+Zero configuration, high performance front end development at organization scale.
 
-## Other repos
+This document focuses on Rails integration.  For details of `sewing-kit`'s configuration and usage, see the [sewing-kit documentation](https://github.com/Shopify/sewing-kit#sewing-kit).
 
-https://github.com/rails/webpacker
-https://github.com/shakacode/react_on_rails
-https://github.com/mipearson/webpack-rails
+## Quick Start
+Create a Rails project using `dev init` then:
+
+### Install Sewing Kits
+```sh
+# Add Ruby/Node dependencies
+bundle add sewing_kit
+yarn add --dev @shopify/sewing-kit
+yarn add --dev react-hot-loader@3.0.0-beta.7
+
+# Optional - add Polaris
+yarn add @shopify/polaris react react-dom
+
+yarn
+dev up
+```
+
+### Add JavaScript
+sewing_kit looks for JavaScript in `app/ui/index.js`.  The code in `index.js` (and any imported JS/CSS) will be built into a `main` bundle.
+
+### Link to JS/CSS with `erb` Helpers
+The `main` bundle is imported into `erb` files using Rails helpers:
+
+```erb
+<%= sewing_kit_link_tag *sewing_kit_asset_paths('main') %>
+<%= sewing_kit_script_tag *sewing_kit_asset_paths('main') %>
+```
+
+**Note:** CSS `<link>` tags appear only in production; in development, CSS is embedded within the `main.js` bundle.
+
+## Minimal Project Layout
+```
+├── Gemfile (must contain "gem 'sewing_kit")
+├── package.json (must specify '@shopify/sewing-kit' as a 'devDependency')
+│
+└── app
+   └── ui
+   │   └─- index.js
+   └── views
+       └─- layouts
+           └─- application.html.erb (must link to JS / CSS using sewing_kit_script_tag / sewing_kit_link_tag
+```
+
+## Rails, Polaris, and React Layout
+A typical Polaris app will use React to render views and components.  The following layout shows best practice locations for:
+- Global SCSS settings
+- App sections (roughly analogous to Rails routes)
+- Components
+- Co-located CSS modules
+- Co-located unit tests
+
+```
+└── app
+    └── ui
+        ├─- index.js (renders React into the DOM)
+        ├── styles (optional)
+        │   └── settings.scss (global vars and @polaris overrides)
+        │
+        └── components (optional)
+            ├── App
+            │   ├── index.js
+            │   ├── App.js
+            │   └── tests
+            │       └── App.test.js
+            │
+            ├-─ MyComponent
+            │   ├-─ index.js
+            │   ├-─ MyComponent.js
+            │   ├── MyComponent.scss (optional; component-scoped CSS styles, mixins, etc)
+            │   └── tests
+            │       └── MyComponent.test.js
+            │
+            └── sections (optional; container views that compose presentation components into UI blocks)
+                └── Home
+                    ├-─ index.js
+                    └── Home.js
+```
+
+## React Boilerplate
+* Create a React app in `app/ui/App.js` ([example](https://github.com/Shopify/rails_sewing_kit_example/blob/master/app/ui/App.js#L11))
+* In an `erb` view, add a placeholder for React content ([example](https://github.com/Shopify/rails_sewing_kit_example/blob/master/app/views/home/index.html.erb#L4))
+* In `index.js`, render a React component into the placeholder element ([example](https://github.com/Shopify/rails_sewing_kit_example/blob/master/app/ui/index.js))
+* Use `sewing_kit_script_tag`/`sewing_kit_link_tag` helpers to link erb/js ([example](https://github.com/Shopify/rails_sewing_kit_example/blob/master/app/views/layouts/application.html.erb#L8))

data/lib/sewing_kit.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 module SewingKit
 end
 

data/lib/sewing_kit/rails.rb

@@ -1 +1,2 @@
+# frozen_string_literal: true
 require "sewing_kit/railtie" if defined? Rails

data/lib/sewing_kit/railtie.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 require 'rails'
 require 'rails/railtie'
 require 'sewing_kit/webpack/compiler'

data/lib/sewing_kit/version.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 module SewingKit
-  VERSION = "0.7.1"
+  VERSION = "0.8.0"
 end

data/lib/sewing_kit/webpack/compiler.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 module SewingKit
   module Webpack
     class Compiler
@@ -7,11 +8,11 @@ module SewingKit
           *command,
           chdir: Rails.root.to_s,
           out: $stdout,
-          err: $stderr,
+          err: $stderr
         )
 
-        if !result
-          puts "sewing-kit compile failed with error code #{$?}"
+        unless result
+          puts "sewing-kit compile failed with error code #{$CHILD_STATUS}"
           exit(1)
         end
         result
@@ -24,11 +25,10 @@ module SewingKit
           'node_modules/.bin/sewing-kit',
           'build',
           '--mode',
-          node_env,
+          node_env
         ].reject(&:empty?)
       end
 
-      private
       def node_env
         ENV['NODE_ENV'] || Rails.env.to_s
       end

data/lib/sewing_kit/webpack/dev.rb

@@ -1,16 +1,16 @@
+# frozen_string_literal: true
 module SewingKit
   module Webpack
-    class NodeSewingKitNotInstalled < StandardError
-      def initialize()
-        super(
-          "sewing-kit is not available.  " +
-          "Please add `@shopify/sewing-kit` to package.json's `devDependencies`, " +
-          "and run  `yarn install`."
-        )
+    class Dev
+      class NodeSewingKitNotInstalled < StandardError
+        def initialize
+          super(
+            "sewing-kit is not installed.  " \
+            "Try `yarn add --dev @shopify/sewing-kit`"
+          )
+        end
       end
-    end
 
-    class Dev
       attr_accessor :pid
 
       def start
@@ -22,7 +22,7 @@ module SewingKit
 
       def spawn
         sewing_kit_bin = 'node_modules/.bin/sewing-kit'
-        raise NodeSewingKitNotInstalled.new unless File.exist?(sewing_kit_bin)
+        raise NodeSewingKitNotInstalled unless File.exist?(sewing_kit_bin)
 
         Kernel.spawn(
           {

data/lib/sewing_kit/webpack/helper.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 require 'base64'
 require 'action_view/helpers'
 require 'sewing_kit/webpack/manifest'
@@ -10,26 +11,24 @@ module SewingKit
       class UnknownJavaScriptAssetError < StandardError
       end
 
-      def sewing_kit_asset_paths(entrypointName, extension: 'js')
-        return '' unless entrypointName.present?
+      def sewing_kit_asset_paths(entrypoint_name, extension: 'js')
+        return '' unless entrypoint_name.present?
 
-        paths = SewingKit::Webpack::Manifest.asset_paths(entrypointName)
+        paths = SewingKit::Webpack::Manifest.asset_paths(entrypoint_name)
         return '' unless paths && paths[extension]
 
-        entryPaths = paths[extension]
-        if serve_development_assets? && extension == 'js'
-          entryPaths.unshift('/webpack/assets/dll/vendor.js')
-        end
-        entryPaths
+        entry_paths = paths[extension]
+        entry_paths.unshift('/webpack/assets/dll/vendor.js') if serve_development_assets? && extension == 'js'
+        entry_paths
       end
 
       def sewing_kit_link_tag(*paths)
         options = paths.extract_options!
 
-        tags = paths.uniq.map { |path|
+        tags = paths.uniq.map do |path|
           next '' if path == ''
           create_asset_tag(:link, path, options)
-        }
+        end
 
         safe_join(tags, "\n")
       end
@@ -37,11 +36,11 @@ module SewingKit
       def sewing_kit_script_tag(*paths)
         options = paths.extract_options!
 
-        tags = paths.uniq.map { |path|
+        tags = paths.uniq.map do |path|
           next '' if path == ''
 
           create_asset_tag(:script, path, options)
-        }
+        end
 
         safe_join(tags, "\n")
       end
@@ -55,7 +54,7 @@ module SewingKit
 
         if tag_options[:integrity]
           file_hash = extract_hash(path)
-          options[:integrity] = file_hash ? encode_hash(file_hash) : nil
+          options[:integrity] = maybe_integrity(file_hash)
         end
 
         case tag_type
@@ -66,6 +65,11 @@ module SewingKit
         end
       end
 
+      def maybe_integrity(file_hash)
+        return nil unless file_hash
+        encode_hash(file_hash)
+      end
+
       def encode_hash(hash)
         # sewing-kit's default config places a sha256 hash in the filename. Browsers expect integrity
         # to be the Base64 encoded version of the binary hash prefixed with the hashing algorithm

data/lib/sewing_kit/webpack/manifest.rb

@@ -1,13 +1,41 @@
+# frozen_string_literal: true
+require 'open3'
 require 'uri'
 
 module SewingKit
   module Webpack
     # Webpack manifest loading, caching & entry point retrieval
     class Manifest
-      # Raised if we can't read our webpack manifest for whatever reason
+      # Raised if the node sewing-kit isn't installed/runnable.
+      class NodeSewingKitNotRunnable < StandardError
+        def initialize(mode, cause)
+          env_message = if 'production' == mode
+            "\nIf this is a container build, try:\n" \
+            "  - Adding `YARN_PRODUCTION=false` to your pipeline's environment variables\n" \
+            "  - Adding the node buildpack: https://github.com/heroku/heroku-buildpack-nodejs"
+          else
+            "Try `yarn add --dev @shopify/sewing-kit`"
+          end
+
+          super(
+            "Could not fetch manifest because node sewing-kit is not runnable.  " \
+            "#{env_message}\n" \
+            "Original error #{cause}"
+          )
+        end
+      end
+
+      # Raised if the node-generated manifest cannot be read from the filesystem.
       class ManifestLoadError < StandardError
-        def initialize(message, orig)
-          super "#{message} (original error #{orig})"
+        def initialize(path, cause)
+          super "Could not load manifest from #{path} (original error #{cause})"
+        end
+      end
+
+      # Raised if the node-generated manifest returns unparseable JSON.
+      class ManifestParseError < StandardError
+        def initialize(cause)
+          super "Could not parse manifest JSON (original error #{cause})"
         end
       end
 
@@ -19,55 +47,30 @@ module SewingKit
 
       class << self
         # :nodoc:
-        def asset_paths(entrypointName)
-          metadata['entrypoints'][entrypointName]
+        def asset_paths(entrypoint_name)
+          instance.asset_paths(entrypoint_name)
         end
 
         def clear_cache!
-          @metadata = nil
-          @metadata_expiry_time = nil
+          @instance = nil
         end
 
         def manifest
-          metadata['assets']
+          instance.manifest
         end
 
-        private
-
-        def metadata
-          if ::Rails.env.production?
-            # Cache at class level, as JSON loading/parsing can be expensive.
-            @metadata ||= load_metadata
+        def instance
+          return @instance if @instance
+          @instance = if Rails.env.development? && ENV['SK_SIMULATE_PRODUCTION'] != '1'
+            Development.new
           else
-            # In development, the manifest may change.
-            # A short cache lifetime avoids time consuming node callouts.
-            if self.instance_variable_defined?('@metadata_expiry_time') && @metadata_expiry_time && @metadata_expiry_time >= Time.now
-              @metadata
-            else
-              @metadata = load_metadata
-              @metadata_expiry_time = Time.now + 4
-            end
+            Production.new
           end
-
-          raise LegacyManifestError.new(@metadata) if !@metadata['entrypoints']
-
-          @metadata
-        end
-
-        def manifest_bundled?
-          !manifest["errors"].any? { |error| error.include? "Module build failed" }
-        end
-
-        def load_metadata
-          JSON.parse(`node_modules/.bin/sewing-kit manifest --mode #{mode}`)
-        rescue => e
-          raise ManifestLoadError.new("Could not load compiled manifest - have you run `rake sewing_kit:build`?", e)
-        end
-
-        def mode
-          ENV['NODE_ENV'] || Rails.env.to_s || 'production'
         end
       end
     end
   end
 end
+
+require 'sewing_kit/webpack/manifest/development'
+require 'sewing_kit/webpack/manifest/production'

data/lib/sewing_kit/webpack/manifest/base.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+module SewingKit
+  module Webpack
+    class Manifest
+      class Base
+        def initialize
+          @metadata = nil
+        end
+
+        # :nodoc:
+        def asset_paths(entrypoint_name)
+          metadata['entrypoints'][entrypoint_name]
+        end
+
+        def clear_cache!
+          @metadata = nil
+        end
+
+        def manifest
+          metadata['assets']
+        end
+
+        def load_metadata_from_node
+          begin
+            stdout, * = Open3.capture3('node_modules/.bin/sewing-kit', 'manifest', "-- mode #{mode}")
+          rescue => e
+            raise NodeSewingKitNotRunnable.new(mode, e)
+          end
+
+          begin
+            JSON.parse(stdout)
+          rescue => e
+            raise ManifestParseError, e
+          end
+        end
+
+        private
+
+        def mode
+          Rails.env.to_s || 'production'
+        end
+      end
+    end
+  end
+end

data/lib/sewing_kit/webpack/manifest/development.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+require 'sewing_kit/webpack/manifest/base'
+
+module SewingKit
+  module Webpack
+    class Manifest
+      class Development < Base
+        def initialize
+          super
+          @metadata_path = nil
+        end
+
+        def clear_cache!
+          super
+          @metadata_path = nil
+        end
+
+        def metadata
+          load_metadata
+        end
+
+        def load_metadata
+          begin
+            return load_metadata_from_fs(@metadata_path) if @metadata_path
+          rescue => e
+            Rails.logger.warn "[sewing_kit] could not read manifest from #{@metadata_path}; falling back to node.  #{e}"
+            @metadata_path = nil
+          end
+
+          result = load_metadata_from_node
+          raise LegacyManifestError, result unless result['entrypoints']
+
+          @metadata_path = result && result['path']
+          result
+        end
+
+        def load_metadata_from_fs(path)
+          begin
+            json_str = File.read(path)
+          rescue => e
+            raise ManifestLoadError.new(path, e)
+          end
+
+          begin
+            JSON.parse(json_str)
+          rescue => e
+            raise ManifestParseError, e
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sewing_kit/webpack/manifest/production.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+require 'sewing_kit/webpack/manifest/base'
+
+module SewingKit
+  module Webpack
+    class Manifest
+      class Production < Base
+        @metadata = nil
+        @metadata_path = nil
+
+        # :nodoc:
+        def asset_paths(entrypoint_name)
+          metadata['entrypoints'][entrypoint_name]
+        end
+
+        def metadata
+          # Cache at class level, as JSON loading/parsing can be expensive.
+          @metadata ||= load_metadata
+        end
+
+        def load_metadata
+          result = load_metadata_from_node
+          raise LegacyManifestError, result unless result['entrypoints']
+          result
+        end
+      end
+    end
+  end
+end

data/lib/tasks/sewing_kit.rake

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 TEMPLATE_PATH = File.expand_path("../install/template.rb", File.dirname(__FILE__))
 
 namespace :sewing_kit do
@@ -7,7 +8,7 @@ namespace :sewing_kit do
   end
 
   desc "Build webpack asset bundles"
-  task :build => :environment do
+  task build: :environment do
     compiler = SewingKit::Webpack::Compiler.new
     compiler.compile
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sewing_kit
 version: !ruby/object:Gem::Version
-  version: 0.7.1
+  version: 0.8.0
 platform: ruby
 authors:
 - Chris Sauve
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-11-09 00:00:00.000000000 Z
+date: 2018-01-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -38,6 +38,34 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 3.2.0
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.51'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.51'
+- !ruby/object:Gem::Dependency
+  name: rubocop-git
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.3
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.3
 description: 
 email:
 - chris.sauve@shopify.com
@@ -54,6 +82,9 @@ files:
 - lib/sewing_kit/webpack/dev.rb
 - lib/sewing_kit/webpack/helper.rb
 - lib/sewing_kit/webpack/manifest.rb
+- lib/sewing_kit/webpack/manifest/base.rb
+- lib/sewing_kit/webpack/manifest/development.rb
+- lib/sewing_kit/webpack/manifest/production.rb
 - lib/tasks/sewing_kit.rake
 homepage: 
 licenses:
@@ -75,7 +106,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.5.2.1
+rubygems_version: 2.6.14
 signing_key: 
 specification_version: 4
 summary: Shopify’s modern front-end tooling, nicely packaged for Rails