js-routes 2.0.6 → 2.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c6231e8af8fe35121f426ca02a854d242f777262920485ef6e78aa346185f5ce
-  data.tar.gz: 1f16118cfcc337e341e1d99b246a8b5ffd50fae4bce76bfce45a4c4093f647aa
+  metadata.gz: 64ddd33bda1dffe333670e22c7abe2e578d960709c5ddb42a1559fea57495288
+  data.tar.gz: af6b923046c1d3e0e838be4502355d9a2c8646af03c90b084e0bf04ec41cbce5
 SHA512:
-  metadata.gz: 804edc5773122ac7465c8f29e79708a4097232317dd6a03a4597224d560977894a86c2de041068e6e18b4101b1bc6314bd76f6bd15aaf5aa6662ff4211fd7d7d
-  data.tar.gz: f4b0489e92b61ab451cb88baf4fa2990c85b45cdb438e1c423e1b689abe0d8984bc4daad87ab01c323cb7a21929619e26bbc6398fbcd68b6da5dd347151bbaed
+  metadata.gz: 15d336c5dae45e63e7ca1700a58ca9d9146c867a59034f9a1346fbdb03153162055fee77d018a8b206bf5ead8a813730ca8618332d1fd5b1a42e0336db8c4ece
+  data.tar.gz: fe9f55283a5b5d71a25b117f35cf9c2562128a4ca6d1efe4022a3f0108fb93779dd1ec13183b019cbf895df30ea52657c4c0f8c9df780ec7dcd486ad6eb71932

data/CHANGELOG.md

@@ -1,5 +1,24 @@
 ## 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.
+
+## v2.0.8
+
+* Forbid usage of `namespace` option if `module_type` is not `nil`. [#281](https://github.com/railsware/js-routes/issues/281).
+
+## v2.0.7
+
+* Remove source map annotation from JS file. Fixes [#277](https://github.com/railsware/js-routes/issues/277)
+  * Generated file is not minified, so it is better to use app side bundler/compressor for source maps
+
+
 ## v2.0.6
 
 * Disable `namespace` option default for all envs [#278](https://github.com/railsware/js-routes/issues/278)

data/Readme.md

@@ -16,12 +16,36 @@ 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:
 
-```
+``` sh
 rake js:routes 
+# OR for typescript support
+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:
+
+``` 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"
 ```
 
 Make routes available globally in `app/javascript/packs/application.js`: 
@@ -31,21 +55,24 @@ import * as Routes from 'routes';
 window.Routes = Routes;
 ```
 
-Individual routes can be imported using:
+<div id='webpacker'></div>
 
-``` javascript
-import {edit_post_path} from 'routes';
-console.log(edit_post_path(1))
-```
+### Webpacker + automatic updates - Typescript
 
-**Note**: that this setup requires `rake js:routes` to be run each time routes file is updated.
+**IMPORTANT**: this setup doesn't support IDE autocompletion with [Typescript](#definitions)
 
-<div id='webpacker'></div>
 
-#### Webpacker + automatic updates
+#### Use a Generator
+
+Run a command:
+
+``` 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 +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`:
@@ -91,7 +118,32 @@ import * as Routes from 'routes.js.erb';
 window.Routes = Routes;
 ```
 
-#### Sprockets (Deprecated)
+<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 +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`):
 
@@ -130,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'
@@ -140,14 +192,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
@@ -159,6 +213,7 @@ Options to configure JavaScript file generator. These options are only available
   * Default: `[]`
   * The regexp applies only to the name before the `_path` suffix, eg: you want to match exactly `settings_path`, the regexp should be `/^settings$/`
 * `namespace` - global object used to access routes.
+  * Only available if `module_type` option is set to `nil`.
   * Supports nested namespace like `MyProject.routes`
   * Default: `nil`
 * `camel_case` - specifies if route helpers should be generated in camel case instead of underscore case.
@@ -175,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.
 
@@ -193,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:
@@ -231,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:
@@ -255,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`:
 
@@ -314,29 +381,20 @@ import {
 } from 'routes.js.erb'
 ```
 
+Such import structure allows for moddern JS bundlers like [Webpack](https://webpack.js.org/) to only include explicitly imported routes into JS bundle file.
+See [Tree Shaking](https://webpack.js.org/guides/tree-shaking/) for more information.
+
 ### Exclude option
 
 Split your routes into multiple files related to each section of your website like:
 
 ``` javascript
 // admin-routes.js.erb
-<%= JsRoutes.generate(include: /^admin_/)
+<%= JsRoutes.generate(include: /^admin_/) %>
 // app-routes.js.erb
-<%= JsRoutes.generate(exclude: /^admin_/)
-```
-
-## JsRoutes and Heroku
-
-When using this setup on Heroku, it is impossible to use the asset pipeline. You should use the "Very Advanced Setup" schema in this case.
-
-For example create routes.js.erb in assets folder with needed content:
-
-``` erb
-<%= JsRoutes.generate(options) %>
+<%= JsRoutes.generate(exclude: /^admin_/) %>
 ```
 
-This should just work.
-
 ## Advantages over alternatives
 
 There are some alternatives available. Most of them has only basic feature and don't reach the level of quality I accept.
@@ -349,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/VERSION_2_UPGRADE.md

@@ -2,23 +2,40 @@
 
 ### Using ESM module by default
 
-The default setting are now changed:
+New version of JsRoutes doesn't try to guess your javascript environment module system because JS has generated a ton of legacy module systems in the past. 
+[ESM+Webpacker](/Readme.md#webpacker) upgrade is recommended. 
 
-Setting | Old | New 
---- | --- | ---
-module\_type | nil | ESM 
-namespace | Routes | nil
+However, if you don't want to follow that pass, specify `module_type` configuration option instead based on module system available in your JS environment.
+Here are supported values:
 
-This is more optimized setup for WebPacker. You can restore the old configuration like this:
+* CJS
+* UMD
+* AMD
+* ESM
+* nil
+
+[Explaination Article](https://dev.to/iggredible/what-the-heck-are-cjs-amd-umd-and-esm-ikm)
+
+If you don't want to use any JS module system and make routes available via a **global variable**, specify `nil` as a `module_type` and use `namespace` option:
 
 ``` ruby
 JsRoutes.setup do |config|
   config.module_type = nil
-  config.namespace = 'Routes'
+  config.namespace = "Routes"
 end
 ```
 
-However, [ESM+Webpacker](/Readme.md#webpacker) upgrade is recommended. 
+### JSDoc comment
+
+New version of js-routes generates function comment in the [JSDoc](https://jsdoc.app) format.
+If you have any problems with that, you can disable it like this:
+
+
+``` ruby
+JsRoutes.setup do |config|
+  config.documentation = false
+end
+```
 
 ### `required_params` renamed
 
@@ -47,15 +64,3 @@ try {
   }
 }
 ```
-
-### JSDoc comment format
-
-New version of js-routes generates function comment in the [JSDoc](https://jsdoc.app) format.
-If you have any problems with that disable the annotation:
-
-``` ruby
-JsRoutes.setup do |config|
-  config.documentation = false
-end
-```
-

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/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.0.6"
+  VERSION = "2.1.1"
 end