Merge pull request #370 from matestack/sf/webpacker-part-2

Sf/webpacker part 2

Author: jonasjabari

.gitignore

@@ -6,6 +6,7 @@ spec/dummy/db/*.sqlite3
 spec/dummy/db/*.sqlite3-journal
 spec/dummy/log/*.log
 spec/dummy/node_modules/
+spec/dummy/public/packs/
 spec/dummy/yarn-error.log
 spec/dummy/storage/
 spec/dummy/tmp/

README.md

@@ -27,13 +27,12 @@ We love to see more and more people using and contributing to matestack-ui-core.
 * core refactoring, increased core maintainability and code quality
 * better integration in existing rails apps
 * improved documentation
-* webpacker support and npm based js dependecy management
 * improved dynamic core components (especially form components)
 
 
 ### Installation:
 
-Click here to see how you can add Matestack UI to your existing Rails application: [Installation Guide](https://www.matestack.org/docs/install)
+Click here to see how you can add Matestack UI to your existing Rails application: [Installation Guide](./docs/install)
 
 ### Features:
 

Rakefile

@@ -37,30 +37,30 @@ task :webpack => 'webpack:build'
 
 namespace :webpack do
   task :build => ['build:development', 'build:production']
-  
+
   namespace :build do
     task :development => 'yarn:install' do
-      Bundler.with_clean_env do
+      Bundler.with_unbundled_env do
         sh "cd builder && bin/webpack"
       end
     end
     task :production => 'yarn:install' do
-      Bundler.with_clean_env do
+      Bundler.with_unbundled_env do
         sh "cd builder && bin/rake webpacker:compile"
       end
     end
   end
-  
+
   task :watch => 'yarn:install' do
-    Bundler.with_clean_env do
+    Bundler.with_unbundled_env do
       sh "cd builder && bin/webpack --watch"
     end
   end
-  
+
   namespace :yarn do
     task :install do
       sh "yarn install && cd builder && yarn install"
     end
   end
-end 
+end
 

docs/install/README.md

@@ -1,7 +1,6 @@
 # Install
 
-If your're using the classic Rails assets pipeline, this guide shows you how to
-add matestack to your Rails app.
+This guide shows you how to add matestack-ui-core to an existing rails application.
 
 ## Gemfile
 
@@ -19,15 +18,56 @@ $ bundle install
 
 ## Javascript
 
-Require 'matestack-ui-core' in your `assets/javascript/application.js`
+Matestack uses javascripts and, in particular, [vuejs](http://vuejs.org). To include these into your existing rails app, matestack supports both, [webpack](https://webpack.js.org/)([er](https://github.com/rails/webpacker/)) and the [asset pipeline](https://guides.rubyonrails.org/asset_pipeline.html).
+
+Rails 6+ apps, by default, use webpacker, rails 5 apps, by default, use the asset pipeline.
+
+### Webpacker
+
+Add 'matestack-ui-core' to your `package.json` by running:
+
+```
+$ yarn add https://github.com/matestack/matestack-ui-core#v0.7.4
+$ yarn install
+```
+
+This adds the npm package that provides the javascript files corresponding to matestack-ui-core ruby gem. Make sure that the npm package version matches the gem version. To find out what gem version you are using, you may use `bundle info matestack-ui-core`.
+
+Next, import 'matestack-ui-core' in your `app/javascript/packs/application.js`
+
+```js
+import MatestackUiCore from 'matestack-ui-core'
+```
+
+and compile the javascript code with webpack:
+
+```
+$ bin/webpack
+```
+
+When, in the future, you update the matestack-ui-core gem, make also sure to update the npm package as well.
+
+### Asset Pipeline
+
+If you are not using webpacker but the asset pipeline, you don't need to install a separate npm package. All required javascript libraries including vuejs are provided by matestack-ui-core ready-to-use via the asset pipeline.
+
+Require 'matestack-ui-core' in your `app/assets/javascript/application.js`
 
 ```javascript
 //= require matestack-ui-core
 ```
-Note:
 
-- **Remove turbolinks! Currently, matestack can't be used with turbolinks. This will be fixed soon**
-- Additional Webpacker integration is coming soon
+Require 'matestack-ui-core' in your `app/assets/stylesheets/application.css`
+
+```css
+/*
+ *= require matestack-ui-core
+ */
+```
+
+### Turbolinks Coming Soon
+
+At the moment, matestack-ui-core is not compatible with [turbolinks](https://github.com/turbolinks/turbolinks). Please remove or deactive turbolinks for now. We are working on turbolinks support and will add it soon. ([Issue #232](https://github.com/matestack/matestack-ui-core/issues/232))
 
 ## Matestack Folder
 
@@ -54,7 +94,7 @@ You need to add the ID "matestack_ui" to some part of your application layout (o
 
 For Example, your `app/views/layouts/application.html.erb` should look like this:
 
-```html+erb
+```erb
 <!DOCTYPE html>
 <html>
   <head>
@@ -63,6 +103,11 @@ For Example, your `app/views/layouts/application.html.erb` should look like this
     <%= csp_meta_tag %>
 
     <%= stylesheet_link_tag    'application', media: 'all' %>
+
+    <!-- if you are using webpacker: -->
+    <%= javascript_pack_tag 'application' %>
+
+    <!-- if you are using the asset pipeline: -->
     <%= javascript_include_tag 'application' %>
   </head>
 
@@ -75,13 +120,25 @@ For Example, your `app/views/layouts/application.html.erb` should look like this
 ```
 Don't apply the matestack_ui ID to the body tag.
 
-## Extend Asset Paths
+## Adding Support for Custom Components
+
+If you intend to write custom dynamic matestack components for your app, you need to make those accessible to the matestack-ui-core javscript code.
+
+### Webpack
+
+When using webpack, make sure to import your custom components in `app/javascript/packs/application.js`:
+
+```js
+import MatestackUiCore from 'matestack-ui-core'
+import '../../../app/matestack/components/my_custom_component'
+```
 
-In order to enable custom Vue.js components, add the matestack folder to the asset paths:
+### Asset Pipeline
 
-`config/initializers/assets.rb`
+When using the asset pipeline, add the matestack folder to the asset paths:
 
 ```ruby
+# config/initializers/assets.rb
 Rails.application.config.assets.paths << Rails.root.join('app/matestack/components')
 ```
 

spec/dummy/.babelrc

@@ -7,4 +7,6 @@
 // To reference this file, add <%= javascript_pack_tag 'application' %> to the appropriate
 // layout file, like app/views/layouts/application.html.erb
 
+import MatestackUiCore from 'matestack-ui-core'
+
 console.log('Hello World from Webpacker')

spec/dummy/.postcssrc.yml

@@ -0,0 +1,17 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Dummy</title>
+    <%= csrf_meta_tags %>
+    <%= csp_meta_tag %>
+
+    <%= stylesheet_link_tag 'application', media: 'all' %>
+    <%= javascript_pack_tag 'application' %>
+  </head>
+
+  <body>
+    <div id="matestack_ui">
+      <%= yield %>
+    </div>
+  </body>
+</html>

spec/dummy/app/javascript/packs/application.js

@@ -8,7 +8,7 @@ default: &default
 
   # Additional paths webpack should lookup modules
   # ['app/assets', 'engine/foo/app/assets']
-  resolved_paths: []
+  resolved_paths: ['node_modules']
 
   # Reload manifest.json on all requests so we reload latest compiled packs
   cache_manifest: false

spec/dummy/app/views/layouts/application_with_webpack.html.erb

@@ -2,7 +2,8 @@
   "name": "dummy",
   "private": true,
   "dependencies": {
-    "@rails/webpacker": "4.2.2"
+    "@rails/webpacker": "4.2.2",
+    "matestack-ui-core": "../../"
   },
   "devDependencies": {
     "webpack-dev-server": "^3.10.2"