frails 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6ee508fa6664a6ab99ce98455154178494206803ec8d377d0fe305b6b5601bdc
-  data.tar.gz: d55d3414d0e8e105abfc59a23dffc6d09feaeaf1a54924231137b91949abad9c
+  metadata.gz: 6b49013f43563b5bf245a5e4190e36326ed5c92086e8b189918504fa9fd31904
+  data.tar.gz: 1cc03eb7682559dd5563d4b7152266fbe7f4ab3f0b2a7b0d6393a90833bb547f
 SHA512:
-  metadata.gz: 1e68db6995b9d72a2250b1f6f4672fe171f3aa3464627270a9dd8d9e4f710ad2313a4ebb0f5bc6d1a4aabe9b7dcb185df34652598d8f6e88bc659d9f2d954a83
-  data.tar.gz: '09e905d8ac0b2df6a9f90bdfaabe9501182982817e8a777060b151c9babd239ad4c94a9ebae6f8c4173e63146d1a514f9e8ee93db40329672cfcca0bd07c41b6'
+  metadata.gz: 63a219ca5f4ebf78c7cfbf53b1d38c7ee8b7e7ddfec0d9578046962cace8e1eb7e3bf18bbdb323610e4b61144f76c1def6c679e08238a7c220afb7d717c7d02a
+  data.tar.gz: 78e7991fa8ee31e6c911cf651dd232ee7a56b23e2b081457d8152e834d55da8afbd82185a6252db69d008245098be6d4338ba4aa8241451d6cab414acee87d6b

data/.gitignore

@@ -1,3 +1,4 @@
+/node_modules/
 /.bundle/
 /.yardoc
 /_yardoc/
@@ -6,3 +7,5 @@
 /pkg/
 /spec/reports/
 /tmp/
+.DS_Store
+*.log

data/.rubocop.yml

@@ -9,6 +9,4 @@ Style/ClassAndModuleChildren:
 Metrics/LineLength:
   Max: 100
 Layout/IndentationConsistency:
-  EnforcedStyle: rails
-  SupportedStyles:
-    - rails
+  EnforcedStyle: indented_internal_methods

data/Gemfile

@@ -1,8 +1,19 @@
 # frozen_string_literal: true
 
 source 'https://rubygems.org'
+git_source(:github) { |repo| "https://github.com/#{repo}.git" }
 
-# Specify your gem's dependencies in frails.gemspec
+# Declare your gem's dependencies in frails.gemspec.
+# Bundler will treat runtime dependencies like base dependencies, and
+# development dependencies will be added by default to the :development group.
 gemspec
 
+# Declare any dependencies that are still in development here instead of in
+# your gemspec. These might include edge Rails or gems from your path or
+# Git. Remember to move these dependencies to your gemspec before releasing
+# your gem to rubygems.org.
+
+# To use a debugger
+# gem 'byebug', group: [:development, :test]
+
 gem 'rubocop', require: false

data/Gemfile.lock

@@ -1,93 +1,161 @@
 PATH
   remote: .
   specs:
-    frails (0.1.0)
+    frails (0.3.0)
+      nokogiri (>= 1.10.4)
       rack-proxy (>= 0.6.5)
-      railties (>= 5.2)
+      rails (>= 6.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    actionpack (5.2.3)
-      actionview (= 5.2.3)
-      activesupport (= 5.2.3)
+    actioncable (6.0.0)
+      actionpack (= 6.0.0)
+      nio4r (~> 2.0)
+      websocket-driver (>= 0.6.1)
+    actionmailbox (6.0.0)
+      actionpack (= 6.0.0)
+      activejob (= 6.0.0)
+      activerecord (= 6.0.0)
+      activestorage (= 6.0.0)
+      activesupport (= 6.0.0)
+      mail (>= 2.7.1)
+    actionmailer (6.0.0)
+      actionpack (= 6.0.0)
+      actionview (= 6.0.0)
+      activejob (= 6.0.0)
+      mail (~> 2.5, >= 2.5.4)
+      rails-dom-testing (~> 2.0)
+    actionpack (6.0.0)
+      actionview (= 6.0.0)
+      activesupport (= 6.0.0)
       rack (~> 2.0)
       rack-test (>= 0.6.3)
       rails-dom-testing (~> 2.0)
-      rails-html-sanitizer (~> 1.0, >= 1.0.2)
-    actionview (5.2.3)
-      activesupport (= 5.2.3)
+      rails-html-sanitizer (~> 1.0, >= 1.2.0)
+    actiontext (6.0.0)
+      actionpack (= 6.0.0)
+      activerecord (= 6.0.0)
+      activestorage (= 6.0.0)
+      activesupport (= 6.0.0)
+      nokogiri (>= 1.8.5)
+    actionview (6.0.0)
+      activesupport (= 6.0.0)
       builder (~> 3.1)
       erubi (~> 1.4)
       rails-dom-testing (~> 2.0)
-      rails-html-sanitizer (~> 1.0, >= 1.0.3)
-    activesupport (5.2.3)
+      rails-html-sanitizer (~> 1.1, >= 1.2.0)
+    activejob (6.0.0)
+      activesupport (= 6.0.0)
+      globalid (>= 0.3.6)
+    activemodel (6.0.0)
+      activesupport (= 6.0.0)
+    activerecord (6.0.0)
+      activemodel (= 6.0.0)
+      activesupport (= 6.0.0)
+    activestorage (6.0.0)
+      actionpack (= 6.0.0)
+      activejob (= 6.0.0)
+      activerecord (= 6.0.0)
+      marcel (~> 0.3.1)
+    activesupport (6.0.0)
       concurrent-ruby (~> 1.0, >= 1.0.2)
       i18n (>= 0.7, < 2)
       minitest (~> 5.1)
       tzinfo (~> 1.1)
+      zeitwerk (~> 2.1, >= 2.1.8)
     ast (2.4.0)
     builder (3.2.3)
     concurrent-ruby (1.1.5)
     crass (1.0.4)
-    erubi (1.8.0)
+    erubi (1.9.0)
+    globalid (0.4.2)
+      activesupport (>= 4.2.0)
     i18n (1.6.0)
       concurrent-ruby (~> 1.0)
-    jaro_winkler (1.5.2)
+    jaro_winkler (1.5.3)
     loofah (2.2.3)
       crass (~> 1.0.2)
       nokogiri (>= 1.5.9)
+    mail (2.7.1)
+      mini_mime (>= 0.1.1)
+    marcel (0.3.3)
+      mimemagic (~> 0.3.2)
     method_source (0.9.2)
+    mimemagic (0.3.3)
+    mini_mime (1.0.2)
     mini_portile2 (2.4.0)
-    minitest (5.11.3)
-    nokogiri (1.10.2)
+    minitest (5.12.0)
+    nio4r (2.5.2)
+    nokogiri (1.10.4)
       mini_portile2 (~> 2.4.0)
-    parallel (1.16.0)
-    parser (2.6.2.0)
+    parallel (1.17.0)
+    parser (2.6.4.1)
       ast (~> 2.4.0)
-    psych (3.1.0)
     rack (2.0.7)
     rack-proxy (0.6.5)
       rack
     rack-test (1.1.0)
       rack (>= 1.0, < 3)
+    rails (6.0.0)
+      actioncable (= 6.0.0)
+      actionmailbox (= 6.0.0)
+      actionmailer (= 6.0.0)
+      actionpack (= 6.0.0)
+      actiontext (= 6.0.0)
+      actionview (= 6.0.0)
+      activejob (= 6.0.0)
+      activemodel (= 6.0.0)
+      activerecord (= 6.0.0)
+      activestorage (= 6.0.0)
+      activesupport (= 6.0.0)
+      bundler (>= 1.3.0)
+      railties (= 6.0.0)
+      sprockets-rails (>= 2.0.0)
     rails-dom-testing (2.0.3)
       activesupport (>= 4.2.0)
       nokogiri (>= 1.6)
-    rails-html-sanitizer (1.0.4)
+    rails-html-sanitizer (1.2.0)
       loofah (~> 2.2, >= 2.2.2)
-    railties (5.2.3)
-      actionpack (= 5.2.3)
-      activesupport (= 5.2.3)
+    railties (6.0.0)
+      actionpack (= 6.0.0)
+      activesupport (= 6.0.0)
       method_source
       rake (>= 0.8.7)
-      thor (>= 0.19.0, < 2.0)
+      thor (>= 0.20.3, < 2.0)
     rainbow (3.0.0)
-    rake (10.5.0)
-    rubocop (0.66.0)
+    rake (12.3.3)
+    rubocop (0.74.0)
       jaro_winkler (~> 1.5.1)
       parallel (~> 1.10)
-      parser (>= 2.5, != 2.5.1.1)
-      psych (>= 3.1.0)
+      parser (>= 2.6)
       rainbow (>= 2.2.2, < 4.0)
       ruby-progressbar (~> 1.7)
-      unicode-display_width (>= 1.4.0, < 1.6)
-    ruby-progressbar (1.10.0)
+      unicode-display_width (>= 1.4.0, < 1.7)
+    ruby-progressbar (1.10.1)
+    sprockets (3.7.2)
+      concurrent-ruby (~> 1.0)
+      rack (> 1, < 3)
+    sprockets-rails (3.2.1)
+      actionpack (>= 4.0)
+      activesupport (>= 4.0)
+      sprockets (>= 3.0.0)
     thor (0.20.3)
     thread_safe (0.3.6)
     tzinfo (1.2.5)
       thread_safe (~> 0.1)
-    unicode-display_width (1.5.0)
+    unicode-display_width (1.6.0)
+    websocket-driver (0.7.1)
+      websocket-extensions (>= 0.1.0)
+    websocket-extensions (0.1.4)
+    zeitwerk (2.1.10)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
-  bundler (~> 2.0)
   frails!
-  minitest (~> 5.0)
-  rake (~> 10.0)
   rubocop
 
 BUNDLED WITH
-   2.0.1
+   2.0.2

data/README.md

@@ -2,10 +2,11 @@
 
 Frails is a modern asset pipeline for [Rails](https://rubyonrails.org), built on [Webpack](https://webpack.js.org/). Its aims are:
 
-  - Follow convention over configuration as much as possible.
-  - Tight integration with Rails, without tying you up in knots.
-  - Full Webpack control without fighting with the likes of Webpacker.
-  - Embrace modern front end practises.
+- Follow convention over configuration as much as possible.
+- Tight integration with Rails, without tying you up in knots.
+- Un-opinionated webpack configuration - batteries not included!
+- Full Webpack control without fighting with the likes of Webpacker.
+- Embrace modern front end practices.
 
 ## Installation
 
@@ -35,27 +36,176 @@ or run the dev server:
 
     $ yarn webpack-dev-server
 
-Rails will proxy requests to any running Webpack dev server
+Rails will proxy requests to any running Webpack dev server.
 
-## Configuration
+### Using in Tests
+
+Please note that Frails is not designed or intended to be run in your test environment. This would require a full webpack compile on every test run, which would slow your tests down hugely! Instead, I recommend that you test your Javascript independently using the likes of Jest or some other good Javascript test runner.
+
+### Webpack Configuration
+
+Frails requires the user of the `webpack-assets-manifest` webpack plugin in order for its helpers to
+work correctly. This is because it needs to be able lookup the real paths of assets, and the
+manifest file provides that data.
+
+```javascript
+module.exports = {
+  ...
+  plugins: [
+    new WebpackAssetsManifest({
+      writeToDisk: true,
+      entrypoints: true,
+      publicPath: true
+    })
+  ]
+}
+```
+
+### Compilation for Production
 
-Frails is built to be as simple as possible, so has very few configuration options. But if you really must change the defaults, just add any of the following config options by adding to `config/application.rb` or and/any of the environment initialzers at `config/environment`.
+To take advantage of Rails asset host functionality, we recommend that you compile your assets using the provided Rake task:
 
-For example:
+    $ rails frails:compile
+
+This will ensure that you assets respect the `asset_host` configuration.
+
+### Rails Helpers
+
+#### `javascript_pack_tag`
+
+Just like `javascript_include_tag`, but will use your webpack assets.
 
 ```ruby
-Rails.application.configure do
-  config.frails.dev_server_port = 3035
-end
+javascript_include_tag 'application'
+```
+
+#### `stylesheet_pack_tag`
+
+Just like `stylesheet_link_tag`, but will use your webpack assets.
+
+```ruby
+stylesheet_pack_tag 'application'
+```
+
+#### `image_pack_tag`
+
+Just like `image_tag`, but will use your webpack assets.
+
+```ruby
+image_pack_tag 'logo.png'
+```
+
+### Side Loaded Assets
+
+Frails has the ability to automatically include your Javascript and CSS based on the current layout
+and/or view. It even supports side loading partials.
+
+As an example, given a view at `/app/views/pages/home.html.erb`, we can create
+`/app/views/pages/home.css` and/or `/app/views/pages/home.js`. These side-loaded assets will then be
+included automatically in the page.
+
+```yml
+app/views/pages: ├── home.html.erb
+  ├── home.css
+  ├── home.js
+  ├── _header.html.erb
+  ├── _header.css
+```
+
+Make sure you yield the side loaded CSS and JS tags; `<%= yield :side_loaded_css %>` in your
+`<head>`, and `<%= yield :side_loaded_js %>` at the bottom of the body:
+
+```html
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>My App</title>
+    <%= yield :side_loaded_css %>
+  </head>
+  <body>
+    <%= yield %> <%= yield :side_loaded_js %>
+  </body>
+</html>
 ```
 
-Of course, if you do change any of these options, be sure to modify your Webpack config accordingly.
+CSS is included in-line for faster renders, and JS is included as <script src="..."> tags. Check out
+`./package/side_load.js` for the webpack config needed to make this work.
+
+#### Partials and CSS Modules
+
+Partial CSS supports CSS Modules, and it is recommended that partial CSS are compiled as local CSS
+modules. Then in your partial, you can use the `css_module` attribute on any HTML tag, and it will
+be replaced with the compiled class name of the CSS module.
+
+So given a partial `views/layouts/_awesome.html.erb`:
+
+```html
+<div css_module="base">Hello World</div>
+```
+
+and a stylesheet at `views/layouts/_awesome.css`:
+
+```css
+.base {
+  color: red;
+}
+```
+
+When the partial is rendered, it will look something like this:
+
+```html
+<div class="app-views-layouts-_awesome__base___abc123">Hello World</div>
+```
+
+And the compiled CSS:
+
+```css
+.app-views-layouts-_awesome__base___abc123 {
+  color: red;
+}
+```
+
+Of course in theory, you could apply this to all your side loaded CSS, but Frails will only
+transform `css_module` HTML attributes in partials.
+
+Your Webpack config could use the following to compile your partial CSS as modules (local), and
+layout and view CSS normally (global):
+
+```javascript
+module.exports = {
+  module: {
+    rules: [
+      {
+        // Partials - modules (local)
+        test: /app\/views\/.+(\/_([\w-_]+)\.css)$/,
+        use: ["style-loader", "css-loader"]
+      },
+      {
+        // Layouts and views - no CSS modules (global)
+        test: /app\/views\/.+(\/[^_]([\w-_]+)\.css)$/,
+        use: ["style-loader", "css-loader"]
+      }
+    ]
+  }
+};
+```
+
+## Configuration
+
+Frails is built to be as simple as possible, so has very few configuration options. But if you really must change the defaults, just set any of the following environment variables. Of course, if you do change any of these options, be sure to modify your Webpack config accordingly.
+
+Be sure to install dotenv-flow package and add that to the very top of your primary webpack config:
+
+```javascript
+require("dotenv-flow").config();
+```
 
 ### Options
 
-  - `dev_server_port` - The HTTP port that Rails will proxy asset requests to. (default: `8080`)
-  - `dev_server_host` - The HTTP host that Rails will proxy asset requests to. (default: `localhost`)
-  - `public_output_path` - The public path where Webpack will output its build to, relative to your app's `/public` directory. (default: `/assets`)
+- `ENV['FRAILS_DEV_SERVER_PORT']` - The HTTP port that Rails will proxy asset requests to. (default: `8080`)
+- `ENV['FRAILS_DEV_SERVER_HOST']` - The HTTP host that Rails will proxy asset requests to. (default: `localhost`)
+- `ENV['FRAILS_PUBLIC_OUTPUT_PATH']` - The public path where Webpack will output its build to, relative to your app's `/public` directory. (default: `assets`)
+- `ENV['FRAILS_MANIFEST_PATH']` - Path to the produced Webpack manifest file, relative to the `public_output_path`. (default: `manifest.json`)
 
 ## Development
 
@@ -69,4 +219,4 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/joelmo
 
 ## Thanks...
 
-A huge thank you goes out to the peeps behind [Webpacker](https://github.com/rails/webpacker). Frails has borrowed heavily from Webpacker, particularly for the dev server proxy and minifest code. 🙏
+A huge thank you goes out to the peeps behind [Webpacker](https://github.com/rails/webpacker). Frails has borrowed heavily from Webpacker, particularly for the dev server proxy and minifest code. 🙏