js-routes 2.0.8 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4f78bfaf0cba479c48245d0606cc10b262481e854f3fc82e7195a8b58548bf7a
-  data.tar.gz: 118cafad50e73568ba4b1758821af072194e9570178f1f9caf067785e9f5a0f5
+  metadata.gz: 315ddd617bc6630cf5858afc5ba38d2c204f6167a7984ccdaf7171a50404e418
+  data.tar.gz: 676d2d36107ee524c07517143499173c0658731cc06d1c52753e3ab2f4e6cb81
 SHA512:
-  metadata.gz: 95490b886a00861b0fe4a5e2419c67ec804bbb94a916edefe333acd2e0c94b407137952b97e4bf70d928ad1ebc5cf47333b5b5083f0dc227a43be2d3ebba7648
-  data.tar.gz: 666d2862d8a86e760176afdfdd62711a34202a4725d08609e5f5bf69732becb8829826ddeccaca0f8cacffa6a78022e69a05872ea26ce550e7352a9bfde0d0e4
+  metadata.gz: 6c7f715e9afd02d1daebb882381e328595beca59a6a6d8c10a3a1518801522090e986c6b362174aaa9c51faf91508ee8e1cc6fff8ba118a08c32eb26c7205ba1
+  data.tar.gz: 7f70bfa95a1fb42092f20118bb3f22f07e459ccc6f95b8d3b0651faf0457266152465873da6a4dfddc4d52df006d6f5b991e3608a083c1eb524fef5ed77ff0c8

data/CHANGELOG.md

@@ -1,5 +1,27 @@
 ## master
 
+## v2.2.0
+
+* Use Rack Middleware to automatically update routes file in development [#288](https://github.com/railsware/js-routes/issues/288)
+  * This setup is now a default recommended due to lack of any downside comparing to [ERB Loader](./Readme.md#webpacker) and [Manual Setup](./Readme.md#advanced-setup)
+
+## v2.1.3
+
+* Fix `default_url_options` bug. [#290](https://github.com/railsware/js-routes/issues/290)
+
+## v2.1.2
+
+* Improve browser window object detection. [#287](https://github.com/railsware/js-routes/issues/287)
+
+## 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.
+
 ## v2.0.8
 
 * Forbid usage of `namespace` option if `module_type` is not `nil`. [#281](https://github.com/railsware/js-routes/issues/281).

data/Readme.md

@@ -16,36 +16,50 @@ gem "js-routes"
 
 ## Setup
 
+There are 3 possible ways to setup JsRoutes:
+
+* [Quick and easy](#quick-start)
+  * Uses Rack Middleware to automatically update routes locally
+  * Works great for a simple Rails application
+* [Webpacker](#webpacker) automatic updates
+  * Requires ESM module system (the default)
+  * Doesn't support typescript definitions
+* [Advanced Setup](#advanced-setup)
+  * Allows very custom setups
+* [Sprockets](#sprockets) legacy
+  * Deprecated and not recommended for modern apps
+
+<div id='quick-start'></div>
+
 ### Quick Start 
 
+Setup [Rack Middleware](https://guides.rubyonrails.org/rails_on_rack.html#action-dispatcher-middleware-stack) to automatically generate and maintain `routes.js` file and corresponding [Typescript definitions](https://www.typescriptlang.org/docs/handbook/declaration-files/templates/module-d-ts.html) `routes.d.ts`:
+
 Run:
 
-```
-rake js:routes 
+``` sh
+rails generate js_routes:middleware
 ```
 
-Make routes available globally in `app/javascript/packs/application.js`: 
 
-``` javascript
-import * as Routes from 'routes';
-window.Routes = Routes;
-```
+<div id='webpacker'></div>
 
-Individual routes can be imported using:
+### Webpacker + automatic updates - Typescript
 
-``` javascript
-import {edit_post_path} from 'routes';
-console.log(edit_post_path(1))
-```
+**IMPORTANT**: this setup doesn't support IDE autocompletion with [Typescript](https://www.typescriptlang.org/docs/handbook/declaration-files/templates/module-d-ts.html)
 
-**Note**: that this setup requires `rake js:routes` to be run each time routes file is updated.
 
-<div id='webpacker'></div>
+#### Use a Generator
+
+Run a command:
 
-#### Webpacker + automatic updates
+``` sh
+./bin/rails generate js_routes:webpacker
+```
 
+#### Setup manually
 
-This setup can automatically update your routes without `rake js:routes` being called 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:
@@ -59,16 +73,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`:
@@ -91,7 +105,75 @@ import * as Routes from 'routes.js.erb';
 window.Routes = Routes;
 ```
 
-#### Sprockets (Deprecated)
+<div id='advanced-setup'></div>
+
+### Advanced Setup
+
+**IMPORTANT**: that this setup requires the JS routes file to be updates manually
+
+You can run every time you want to generate a routes file:
+
+``` sh
+rake js:routes 
+# OR for typescript support
+rake js:routes:typescript
+```
+
+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:
+
+``` erb
+// app/javascript/admin/routes.js.erb
+<%= JsRoutes.generate(include: /admin/) %>
+```
+
+``` erb
+// app/javascript/customer/routes.js.erb
+<%= JsRoutes.generate(exclude: /admin/) %>
+```
+
+You can manipulate the generated helper manually by injecting ruby into javascript:
+
+``` erb
+export const routes = <%= JsRoutes.generate(module_type: nil, namespace: nil) %>
+```
+
+If you want to generate the routes files outside of the asset pipeline, you can use `JsRoutes.generate!`:
+
+``` ruby
+path = Rails.root.join("app/javascript")
+
+JsRoutes.generate!("#{path}/app_routes.js", exclude: [/^admin_/, /^api_/])
+JsRoutes.generate!("#{path}/adm_routes.js", include: /^admin_/)
+JsRoutes.generate!("#{path}/api_routes.js", include: /^api_/, default_url_options: {format: "json"})
+```
+
+<div id='definitions'></div>
+
+#### Typescript Definitions
+
+JsRoutes has typescript support out of the box. 
+
+Restrictions:
+
+* 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! # to output to file
+# or 
+JsRoutes.definitions # to output to string
+```
+
+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.
+
+<div id="sprockets"></div>
+
+### Sprockets (Deprecated)
 
 If you are using [Sprockets](https://github.com/rails/sprockets-rails) you may configure js-routes in the following way.
 
@@ -120,7 +202,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`):
 
@@ -130,7 +212,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'
@@ -140,14 +222,16 @@ 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`, `nil`.
+  * Options: `ESM`, `UMD`, `CJS`, `AMD`, `DTS`, `nil`.
   * Default: `ESM`
   * `nil` option can be used in case you don't want generated code to export anything.
 * `documentation` - specifies if each route should be annotated with [JSDoc](https://jsdoc.app/) comment
@@ -176,7 +260,9 @@ 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
+<div id="formatter-options"></div>
+
+#### Formatter Options
 
 Options to configure routes formatting. These options are available both in Ruby and JavaScript context.
 
@@ -194,36 +280,6 @@ 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
-
-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:
-
-``` erb
-// app/javascript/admin/routes.js.erb
-<%= JsRoutes.generate(include: /admin/) %>
-```
-
-``` erb
-// app/javascript/customer/routes.js.erb
-<%= JsRoutes.generate(exclude: /admin/) %>
-```
-
-You can manipulate the generated helper manually by injecting ruby into javascript:
-
-``` erb
-export const routes = <%= JsRoutes.generate(module_type: nil, namespace: nil) %>
-```
-
-If you want to generate the routes files outside of the asset pipeline, you can use `JsRoutes.generate!`:
-
-``` ruby
-path = Rails.root.join("app/javascript")
-
-JsRoutes.generate!("#{path}/app_routes.js", exclude: [/^admin_/, /^api_/])
-JsRoutes.generate!("#{path}/adm_routes.js", include: /^admin_/)
-JsRoutes.generate!("#{path}/api_routes.js", include: /^api_/, default_url_options: {format: "json"})
-```
 
 ## Usage
 
@@ -232,22 +288,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:
@@ -256,7 +324,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`:
 
@@ -324,9 +392,9 @@ Split your routes into multiple files related to each section of your website li
 
 ``` javascript
 // admin-routes.js.erb
-<%= JsRoutes.generate(include: /^admin_/)
+<%= JsRoutes.generate(include: /^admin_/) %>
 // app-routes.js.erb
-<%= JsRoutes.generate(exclude: /^admin_/)
+<%= JsRoutes.generate(exclude: /^admin_/) %>
 ```
 
 ## Advantages over alternatives
@@ -341,14 +409,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/js-routes.gemspec

@@ -25,7 +25,7 @@ Gem::Specification.new do |s|
 
   s.add_runtime_dependency(%q<railties>, [">= 4"])
   s.add_development_dependency(%q<sprockets-rails>)
-  s.add_development_dependency(%q<rspec>, [">= 3.0.0"])
+  s.add_development_dependency(%q<rspec>, [">= 3.10.0"])
   s.add_development_dependency(%q<bundler>, [">= 1.1.0"])
   s.add_development_dependency(%q<appraisal>, [">= 0.5.2"])
   s.add_development_dependency(%q<bump>, [">= 0.10.0"])

data/lib/js_routes/generators/middleware.rb

@@ -0,0 +1,33 @@
+require "rails/generators"
+
+class JsRoutes::Generators::Middleware < Rails::Generators::Base
+
+  source_root File.expand_path(__FILE__ + "/../../../templates")
+
+  def create_middleware
+    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
+    inject_into_file "config/environments/development.rb", middleware_content, before: /^end\n\z/
+  end
+
+  protected
+
+  def pack_content
+    <<-JS
+import * as Routes from '../routes';
+window.Routes = Routes;
+    JS
+  end
+
+  def middleware_content
+    <<-RB
+
+  # Automatically update routes.js file
+  # when routes.rb is changed
+  config.middleware.use(JsRoutes::Middleware)
+    RB
+  end
+end

data/lib/js_routes/generators/webpacker.rb

@@ -0,0 +1,32 @@
+require "rails/generators"
+
+class JsRoutes::Generators::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/middleware.rb

@@ -0,0 +1,36 @@
+class JsRoutes
+  # A Rack middleware that automatically updates routes file
+  # whenever routes.rb is modified
+  #
+  # Inspired by
+  # https://github.com/fnando/i18n-js/blob/main/lib/i18n/js/middleware.rb
+  class Middleware
+    def initialize(app)
+      @app = app
+      @routes_file = Rails.root.join("config/routes.rb")
+      @mtime = nil
+    end
+
+    def call(env)
+      update_js_routes
+      @app.call(env)
+    end
+
+    protected
+
+    def update_js_routes
+      new_mtime = routes_mtime
+      unless new_mtime == @mtime
+        JsRoutes.generate!
+        JsRoutes.definitions!
+        @mtime = new_mtime
+      end
+    end
+
+    def routes_mtime
+      File.mtime(@routes_file)
+    rescue Errno::ENOENT
+      nil
+    end
+  end
+end

data/lib/js_routes/version.rb

@@ -1,3 +1,3 @@
 class JsRoutes
-  VERSION = "2.0.8"
+  VERSION = "2.2.0"
 end