js-routes 2.1.0 → 2.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 242f329ab92abe8be4a2fa3790f72a3f161a6c2355b2392eae484a36a91d3a24
-  data.tar.gz: 120e5191eccfe3a8978c89ecb690a4f93a62279b249c58bc84b9273fe3e900c7
+  metadata.gz: 54158654106dece477c1fdf36afa52b504a43b8210c4c8d30f98d41ccd0ef600
+  data.tar.gz: a67b36754269392839bb6d2e86a20899ec2575437ac9667f10cdd9feb7306185
 SHA512:
-  metadata.gz: e1998fd3c98dff227905bfcd8a09be8bb6901d3da7293b60d1a6f11c3a2627c623372324a13010cbe425eb7b93781fa64db042c08e7b4123d4a50ec8bd8814b2
-  data.tar.gz: 5395c808f148bd39a99de0ce748cbb3a57c27620f048764bfcf6a455ac6ce2bbc43e282f4c660ba019f8d4b5df39a316728bb673d56b2667aecb667dde82d91b
+  metadata.gz: 582b6a39a062f6fcfd7b2cb4a57b4fd4573e343f93d5751ef764b7e3617cb7243801caf61ee971224a2c1a41e43a2f51221e5d3a40c12d5db21af98f47467044
+  data.tar.gz: f54b26ed68ed8ef2a6b4ad5ebf2e0322bfbec7385756a8578b5c11c01eca646d42baa5634d16cef6d16520e3eed4d1b1a37260e4ade943ee568b6b4755153cea

data/CHANGELOG.md

@@ -1,5 +1,27 @@
 ## master
 
+## v2.2.1
+
+* Improve generator to update route files on `assets:precompile` and add them to `.gitignore by default` [#288](https://github.com/railsware/js-routes/issues/288#issuecomment-1012182815)
+
+## 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.

data/Readme.md

@@ -16,40 +16,84 @@ gem "js-routes"
 
 ## Setup
 
+There are several 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 ERB Loader](#webpacker)
+  * 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 
 
-Run:
+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`:
+
+#### Use a Generator
+
+Run a command:
 
 ``` sh
-rake js:routes 
-# OR for typescript support
-rake js:routes:typescript
+rails generate js_routes:middleware
 ```
 
+#### Setup Manually
 
-Individual routes can be imported using:
+Add the following to `config/environments/development.rb`:
 
-``` javascript
-import {edit_post_path, posts_path} from 'routes';
-console.log(posts_path({format: 'json'})) // => "/posts.json"
-console.log(edit_post_path(1)) // => "/posts/1/edit"
+``` ruby
+  config.middleware.use(JsRoutes::Middleware)
 ```
 
-Make routes available globally in `app/javascript/packs/application.js`: 
+Use it in `app/javascript/packs/application.js`:
 
 ``` javascript
-import * as Routes from 'routes';
-window.Routes = Routes;
+import * as Routes from '../routes';
+// window.Routes = Routes;
+alert(Routes.post_path(1))
 ```
 
-**Note**: that this setup requires `rake js:routes` to be run each time routes file is updated.
+Upgrade `rake assets:precompile` to update js-routes files: 
+
+``` ruby
+namespace :assets do
+  task :precompile => "js:routes:typescript"
+end
+```
+
+Add js-routes files to `.gitignore`:
+
+```
+/app/javascript/routes.js
+/app/javascript/routes.d.ts
+```
 
 <div id='webpacker'></div>
 
-#### Webpacker + automatic updates
+### Webpacker ERB loader
+
+**IMPORTANT**: this setup doesn't support IDE autocompletion with [Typescript](https://www.typescriptlang.org/docs/handbook/declaration-files/templates/module-d-ts.html)
+
 
+#### Use a Generator
 
-This setup can automatically update your routes without `rake js:routes` being called manually.
+Run a command:
+
+``` 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 +107,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`:
@@ -95,23 +139,77 @@ import * as Routes from 'routes.js.erb';
 window.Routes = Routes;
 ```
 
+<div id='advanced-setup'></div>
+
+### Advanced Setup
+
+**IMPORTANT**: that this setup requires the JS routes file to be updates manually
+
+Routes file can be generated with a `rake` task:
+
+``` 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:
+
+**IMPORTANT**: Requires [Webpacker ERB Loader](#webpacker) setup.
+
+``` 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. In order to generate typscript definitions file (aka `routes.d.ts`) you can call:
+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!
+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 +238,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 +248,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 +258,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 +296,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.
 
@@ -214,36 +316,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
 
@@ -252,22 +324,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 +360,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 +445,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/middleware.rb

@@ -0,0 +1,58 @@
+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"
+    inject_into_file "app/javascript/packs/application.js", pack_content
+    inject_into_file "config/environments/development.rb", middleware_content, before: /^end\n\z/
+    inject_into_file "Rakefile", rakefile_content
+    inject_into_file ".gitignore", gitignore_content
+    JsRoutes.generate!
+    JsRoutes.definitions!
+  end
+
+  protected
+
+  def pack_content
+    <<-JS
+import * as Routes from '../routes';
+window.Routes = Routes;
+    JS
+  end
+
+  def middleware_content
+    <<-RB
+
+  # Automatically update js-routes file
+  # when routes.rb is changed
+  config.middleware.use(JsRoutes::Middleware)
+    RB
+  end
+
+  def rakefile_content
+    <<-RB
+
+# Update js-routes file before assets precompile
+namespace :assets do
+  task :precompile => "js:routes:typescript"
+end
+    RB
+  end
+
+  def gitignore_content
+    banner = <<-TXT
+
+# Ignore automatically generated js-routes files.
+    TXT
+
+    banner + [
+      {},
+      {module_type: 'DTS'}
+    ].map do |config|
+      File.join('/', JsRoutes.new(config).configuration.output_file) + "\n"
+    end.join
+  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