js-routes 2.1.0 → 2.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 242f329ab92abe8be4a2fa3790f72a3f161a6c2355b2392eae484a36a91d3a24
-  data.tar.gz: 120e5191eccfe3a8978c89ecb690a4f93a62279b249c58bc84b9273fe3e900c7
+  metadata.gz: 64ddd33bda1dffe333670e22c7abe2e578d960709c5ddb42a1559fea57495288
+  data.tar.gz: af6b923046c1d3e0e838be4502355d9a2c8646af03c90b084e0bf04ec41cbce5
 SHA512:
-  metadata.gz: e1998fd3c98dff227905bfcd8a09be8bb6901d3da7293b60d1a6f11c3a2627c623372324a13010cbe425eb7b93781fa64db042c08e7b4123d4a50ec8bd8814b2
-  data.tar.gz: 5395c808f148bd39a99de0ce748cbb3a57c27620f048764bfcf6a455ac6ce2bbc43e282f4c660ba019f8d4b5df39a316728bb673d56b2667aecb667dde82d91b
+  metadata.gz: 15d336c5dae45e63e7ca1700a58ca9d9146c867a59034f9a1346fbdb03153162055fee77d018a8b206bf5ead8a813730ca8618332d1fd5b1a42e0336db8c4ece
+  data.tar.gz: fe9f55283a5b5d71a25b117f35cf9c2562128a4ca6d1efe4022a3f0108fb93779dd1ec13183b019cbf895df30ea52657c4c0f8c9df780ec7dcd486ad6eb71932

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 ## master
 
+## v2.1.1
+
+* Added webpacker generator `./bin/rails generate js_routes:webpacker`
+* Reorganized Readme to describe different setups with their pros and cons more clearly
+
 ## v2.1.0
 
 * Support typescript defintions file aka `routes.d.ts`. See [Readme.md](./Readme.md#definitions) for more information.

data/Readme.md

@@ -16,6 +16,18 @@ gem "js-routes"
 
 ## Setup
 
+There are 3 possible ways to setup JsRoutes:
+
+* [Quick and easy](#quick-start)
+  * Requires rake task to be run each time route file is updated
+* [Webpacker](#webpacker) automatic updates
+  * Requires ESM module system (the default)
+  * Doesn't support typescript definitions
+* [Sprockets](#sprockets) legacy
+  * Deprecated and not recommended for modern apps
+
+<div id='quick-start'></div>
+
 ### Quick Start 
 
 Run:
@@ -26,6 +38,7 @@ rake js:routes
 rake js:routes:typescript
 ```
 
+**IMPORTANT**: that this setup requires the rake task to be run each time routes file is updated.
 
 Individual routes can be imported using:
 
@@ -42,14 +55,24 @@ import * as Routes from 'routes';
 window.Routes = Routes;
 ```
 
-**Note**: that this setup requires `rake js:routes` to be run each time routes file is updated.
-
 <div id='webpacker'></div>
 
-#### Webpacker + automatic updates
+### Webpacker + automatic updates - Typescript
+
+**IMPORTANT**: this setup doesn't support IDE autocompletion with [Typescript](#definitions)
+
+
+#### Use a Generator
 
+Run a command:
 
-This setup can automatically update your routes without `rake js:routes` being called manually.
+``` sh
+./bin/rails generate js_routes:webpacker
+```
+
+#### Setup manually
+
+The routes files can be automatically updated  without `rake` task being called manually.
 It requires [rails-erb-loader](https://github.com/usabilityhub/rails-erb-loader) npm package to work.
 
 Add `erb` loader to webpacker:
@@ -63,16 +86,16 @@ Create webpack ERB config `config/webpack/loaders/erb.js`:
 
 ``` javascript
 module.exports = {
-  test: /\.js\.erb$/,
-  enforce: 'pre',
-  exclude: /node_modules/,
-  use: [{
-    loader: 'rails-erb-loader',
-    options: {
-      runner: (/^win/.test(process.platform) ? 'ruby ' : '') + 'bin/rails runner'
-    }
-  }]
-}
+  module: {
+    rules: [
+      {
+        test: /\.erb$/,
+        enforce: 'pre',
+        loader: 'rails-erb-loader'
+      },
+    ]
+  }
+};
 ```
 
 Enable `erb` extension in `config/webpack/environment.js`:
@@ -97,21 +120,30 @@ window.Routes = Routes;
 
 <div id='definitions'></div>
 
-#### Typescript Definitions
+### Typescript Definitions
+
+JsRoutes has typescript support out of the box. 
+
+Restrictions:
 
-JsRoutes has typescript support out of the box. In order to generate typscript definitions file (aka `routes.d.ts`) you can call:
+* Only available if `module_type` is set to `ESM` (strongly recommended and default).
+* Webpacker Automatic Updates are not available because typescript compiler can not be configured to understand `.erb` extensions.
+
+For the basic setup of typscript definitions  see [Quick Start](#quick-start) setup.
+More advanced setup would involve calling manually:
 
 ``` ruby
-JsRoutes.definitions!
+JsRoutes.definitions! # to output to file
+# or 
+JsRoutes.definitions # to output to string
 ```
 
-Or create an automatic updates file at `app/javascript/routes.d.ts.erb`:
+Even more advanced setups can be achieved by setting `module_type` to `DTS` inside [configuration](#module_type) 
+which will cause any `JsRoutes` instance to generate defintions instead of routes themselves.
 
-``` erb
-<%= JsRoutes.defintions %>
-```
+<div id="sprockets"></div>
 
-#### Sprockets (Deprecated)
+### Sprockets (Deprecated)
 
 If you are using [Sprockets](https://github.com/rails/sprockets-rails) you may configure js-routes in the following way.
 
@@ -140,7 +172,7 @@ This cache is not flushed on server restart in development environment.
 
 **Important:** If routes.js file is not updated after some configuration change you need to run this rake task again.
 
-### Configuration
+## Configuration
 
 You can configure JsRoutes in two main ways. Either with an initializer (e.g. `config/initializers/js_routes.rb`):
 
@@ -150,7 +182,7 @@ JsRoutes.setup do |config|
 end
 ```
 
-Or dynamically in JavaScript, although only [Formatter Options](#formatter-options) are supported (see below)
+Or dynamically in JavaScript, although only [Formatter Options](#formatter-options) are supported:
 
 ``` js
 import * as Routes from 'routes'
@@ -160,12 +192,14 @@ Routes.configure({
 Routes.config(); // current config
 ```
 
-#### Available Options
+### Available Options
 
-##### Generator Options
+#### Generator Options
 
 Options to configure JavaScript file generator. These options are only available in Ruby context but not JavaScript.
 
+<div id='module-type'></div>
+
 * `module_type` - JavaScript module type for generated code. [Article](https://dev.to/iggredible/what-the-heck-are-cjs-amd-umd-and-esm-ikm)
   * Options: `ESM`, `UMD`, `CJS`, `AMD`, `DTS`, `nil`.
   * Default: `ESM`
@@ -196,7 +230,7 @@ Options to configure JavaScript file generator. These options are only available
 * `file` - a file location where generated routes are stored
   * Default: `app/javascript/routes.js` if setup with Webpacker, otherwise `app/assets/javascripts/routes.js` if setup with Sprockets.
 
-##### Formatter Options
+#### Formatter Options
 
 Options to configure routes formatting. These options are available both in Ruby and JavaScript context.
 
@@ -214,7 +248,7 @@ Options to configure routes formatting. These options are available both in Ruby
   * This option exists because JS doesn't provide a difference between an object and a hash
   * Default: `_options`
 
-### Advanced Setup
+## Advanced Setup
 
 In case you need multiple route files for different parts of your application, you have to create the files manually.
 If your application has an `admin` and an `application` namespace for example:
@@ -252,22 +286,34 @@ Configuration above will create a nice javascript file with `Routes` object that
 ``` js
 import * as Routes from 'routes';
 
-Routes.users_path() // => "/users"
-Routes.user_path(1) // => "/users/1"
-Routes.user_path(1, {format: 'json'}) // => "/users/1.json"
-Routes.user_path(1, {anchor: 'profile'}) // => "/users/1#profile"
-Routes.new_user_project_path(1, {format: 'json'}) // => "/users/1/projects/new.json"
-Routes.user_project_path(1,2, {q: 'hello', custom: true}) // => "/users/1/projects/2?q=hello&custom=true"
-Routes.user_project_path(1,2, {hello: ['world', 'mars']}) // => "/users/1/projects/2?hello%5B%5D=world&hello%5B%5D=mars"
-```
+Routes.users_path() 
+  // => "/users"
 
-Using serialized object as route function arguments:
+Routes.user_path(1) 
+  // => "/users/1"
+  
+Routes.user_path(1, {format: 'json'}) 
+  // => "/users/1.json"
+
+Routes.user_path(1, {anchor: 'profile'}) 
+  // => "/users/1#profile"
+
+Routes.new_user_project_path(1, {format: 'json'}) 
+  // => "/users/1/projects/new.json"
+
+Routes.user_project_path(1,2, {q: 'hello', custom: true}) 
+  // => "/users/1/projects/2?q=hello&custom=true"
+
+Routes.user_project_path(1,2, {hello: ['world', 'mars']}) 
+  // => "/users/1/projects/2?hello%5B%5D=world&hello%5B%5D=mars"
 
-``` js
 var google = {id: 1, name: "Google"};
-Routes.company_path(google) // => "/companies/1"
+Routes.company_path(google) 
+  // => "/companies/1"
+
 var google = {id: 1, name: "Google", to_param: "google"};
-Routes.company_path(google) // => "/companies/google"
+Routes.company_path(google) 
+  // => "/companies/google"
 ```
 
 In order to make routes helpers available globally:
@@ -276,7 +322,7 @@ In order to make routes helpers available globally:
 jQuery.extend(window, Routes)
 ```
 
-## Get spec of routes and required params
+### Get spec of routes and required params
 
 Possible to get `spec` of route by function `toString`:
 
@@ -361,14 +407,6 @@ Advantages of this one are:
 * Support Rails `#to_param` convention for seo optimized paths
 * Well tested
 
-## Version 2 TODO
-
-* Add routes generation .d.ts file
-* Add config option on the output format: js, ts, d.ts
-* Add prettier
-* Add eslint
-* Add development guide
-
 #### Thanks to [contributors](https://github.com/railsware/js-routes/contributors)
 
 #### Have fun

data/lib/js_routes/generators/webpacker.rb

@@ -0,0 +1,32 @@
+require "rails/generators"
+
+class JsRoutes::Webpacker < Rails::Generators::Base
+
+  source_root File.expand_path(__FILE__ + "/../../../templates")
+
+  def create_webpack
+    copy_file "initializer.rb", "config/initializers/js_routes.rb"
+    copy_file "erb.js", "config/webpack/loaders/erb.js"
+    copy_file "routes.js.erb", "app/javascript/routes.js.erb"
+    inject_into_file "config/webpack/environment.js", loader_content
+    inject_into_file "app/javascript/packs/application.js", pack_content
+    command = Rails.root.join("./bin/yarn add rails-erb-loader")
+    run command
+  end
+
+  protected
+
+  def pack_content
+    <<-JS
+import * as Routes from 'routes.js.erb';
+window.Routes = Routes;
+    JS
+  end
+
+  def loader_content
+    <<-JS
+const erb = require('./loaders/erb')
+environment.loaders.append('erb', erb)
+    JS
+  end
+end

data/lib/js_routes/version.rb

@@ -1,3 +1,3 @@
 class JsRoutes
-  VERSION = "2.1.0"
+  VERSION = "2.1.1"
 end

data/lib/js_routes.rb

@@ -66,6 +66,10 @@ class JsRoutes
       esm? || dts?
     end
 
+    def require_esm
+      raise "ESM module type is required" unless modern?
+    end
+
     def source_file
       File.dirname(__FILE__) + "/" + default_file_name
     end
@@ -115,7 +119,7 @@ class JsRoutes
       @configuration ||= Configuration.new
     end
 
-    def generate(opts = {})
+    def generate(**opts)
       new(opts).generate
     end
 
@@ -123,9 +127,13 @@ class JsRoutes
       new(file: file_name, **opts).generate!
     end
 
+    def definitions(**opts)
+      generate(module_type: 'DTS', **opts)
+    end
+
     def definitions!(file_name = nil, **opts)
       file_name ||= configuration.file&.sub!(%r{\.(j|t)s\Z}, ".d.ts")
-      new(file: file_name, module_type: 'DTS', **opts).generate!
+      generate!(file_name, module_type: 'DTS', **opts)
     end
 
     def json(string)
@@ -449,3 +457,5 @@ JS
     end
   end
 end
+
+require "js_routes/generators/webpacker"

data/lib/templates/erb.js

@@ -0,0 +1,11 @@
+module.exports = {
+  module: {
+    rules: [
+      {
+        test: /\.erb$/,
+        enforce: 'pre',
+        loader: 'rails-erb-loader'
+      },
+    ]
+  }
+};

data/lib/templates/initializer.rb

@@ -0,0 +1,5 @@
+JsRoutes.setup do |c|
+  # Setup your JS module system:
+  # ESM, CJS, AMD, UMD or nil
+  # c.module_type = "ESM"
+end

data/lib/templates/routes.js.erb

@@ -0,0 +1 @@
+<%= JsRoutes.generate %>

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: js-routes
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 2.1.1
 platform: ruby
 authors:
 - Bogdan Gusiev
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-09-09 00:00:00.000000000 Z
+date: 2021-10-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -171,11 +171,15 @@ files:
 - lib/js-routes.rb
 - lib/js_routes.rb
 - lib/js_routes/engine.rb
+- lib/js_routes/generators/webpacker.rb
 - lib/js_routes/version.rb
 - lib/routes.d.ts
 - lib/routes.js
 - lib/routes.ts
 - lib/tasks/js_routes.rake
+- lib/templates/erb.js
+- lib/templates/initializer.rb
+- lib/templates/routes.js.erb
 - package.json
 - spec/dummy/app/assets/config/manifest.js
 - spec/dummy/app/assets/javascripts/.gitkeep