js-routes 2.0.6 → 2.1.1

Sign up to get free protection for your applications and to get access to all the features.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: c6231e8af8fe35121f426ca02a854d242f777262920485ef6e78aa346185f5ce
4
- data.tar.gz: 1f16118cfcc337e341e1d99b246a8b5ffd50fae4bce76bfce45a4c4093f647aa
3
+ metadata.gz: 64ddd33bda1dffe333670e22c7abe2e578d960709c5ddb42a1559fea57495288
4
+ data.tar.gz: af6b923046c1d3e0e838be4502355d9a2c8646af03c90b084e0bf04ec41cbce5
5
5
  SHA512:
6
- metadata.gz: 804edc5773122ac7465c8f29e79708a4097232317dd6a03a4597224d560977894a86c2de041068e6e18b4101b1bc6314bd76f6bd15aaf5aa6662ff4211fd7d7d
7
- data.tar.gz: f4b0489e92b61ab451cb88baf4fa2990c85b45cdb438e1c423e1b689abe0d8984bc4daad87ab01c323cb7a21929619e26bbc6398fbcd68b6da5dd347151bbaed
6
+ metadata.gz: 15d336c5dae45e63e7ca1700a58ca9d9146c867a59034f9a1346fbdb03153162055fee77d018a8b206bf5ead8a813730ca8618332d1fd5b1a42e0336db8c4ece
7
+ data.tar.gz: fe9f55283a5b5d71a25b117f35cf9c2562128a4ca6d1efe4022a3f0108fb93779dd1ec13183b019cbf895df30ea52657c4c0f8c9df780ec7dcd486ad6eb71932
data/CHANGELOG.md CHANGED
@@ -1,5 +1,24 @@
1
1
  ## master
2
2
 
3
+ ## v2.1.1
4
+
5
+ * Added webpacker generator `./bin/rails generate js_routes:webpacker`
6
+ * Reorganized Readme to describe different setups with their pros and cons more clearly
7
+
8
+ ## v2.1.0
9
+
10
+ * Support typescript defintions file aka `routes.d.ts`. See [Readme.md](./Readme.md#definitions) for more information.
11
+
12
+ ## v2.0.8
13
+
14
+ * Forbid usage of `namespace` option if `module_type` is not `nil`. [#281](https://github.com/railsware/js-routes/issues/281).
15
+
16
+ ## v2.0.7
17
+
18
+ * Remove source map annotation from JS file. Fixes [#277](https://github.com/railsware/js-routes/issues/277)
19
+ * Generated file is not minified, so it is better to use app side bundler/compressor for source maps
20
+
21
+
3
22
  ## v2.0.6
4
23
 
5
24
  * Disable `namespace` option default for all envs [#278](https://github.com/railsware/js-routes/issues/278)
data/Readme.md CHANGED
@@ -16,12 +16,36 @@ gem "js-routes"
16
16
 
17
17
  ## Setup
18
18
 
19
+ There are 3 possible ways to setup JsRoutes:
20
+
21
+ * [Quick and easy](#quick-start)
22
+ * Requires rake task to be run each time route file is updated
23
+ * [Webpacker](#webpacker) automatic updates
24
+ * Requires ESM module system (the default)
25
+ * Doesn't support typescript definitions
26
+ * [Sprockets](#sprockets) legacy
27
+ * Deprecated and not recommended for modern apps
28
+
29
+ <div id='quick-start'></div>
30
+
19
31
  ### Quick Start
20
32
 
21
33
  Run:
22
34
 
23
- ```
35
+ ``` sh
24
36
  rake js:routes
37
+ # OR for typescript support
38
+ rake js:routes:typescript
39
+ ```
40
+
41
+ **IMPORTANT**: that this setup requires the rake task to be run each time routes file is updated.
42
+
43
+ Individual routes can be imported using:
44
+
45
+ ``` javascript
46
+ import {edit_post_path, posts_path} from 'routes';
47
+ console.log(posts_path({format: 'json'})) // => "/posts.json"
48
+ console.log(edit_post_path(1)) // => "/posts/1/edit"
25
49
  ```
26
50
 
27
51
  Make routes available globally in `app/javascript/packs/application.js`:
@@ -31,21 +55,24 @@ import * as Routes from 'routes';
31
55
  window.Routes = Routes;
32
56
  ```
33
57
 
34
- Individual routes can be imported using:
58
+ <div id='webpacker'></div>
35
59
 
36
- ``` javascript
37
- import {edit_post_path} from 'routes';
38
- console.log(edit_post_path(1))
39
- ```
60
+ ### Webpacker + automatic updates - Typescript
40
61
 
41
- **Note**: that this setup requires `rake js:routes` to be run each time routes file is updated.
62
+ **IMPORTANT**: this setup doesn't support IDE autocompletion with [Typescript](#definitions)
42
63
 
43
- <div id='webpacker'></div>
44
64
 
45
- #### Webpacker + automatic updates
65
+ #### Use a Generator
66
+
67
+ Run a command:
68
+
69
+ ``` sh
70
+ ./bin/rails generate js_routes:webpacker
71
+ ```
46
72
 
73
+ #### Setup manually
47
74
 
48
- This setup can automatically update your routes without `rake js:routes` being called manually.
75
+ The routes files can be automatically updated without `rake` task being called manually.
49
76
  It requires [rails-erb-loader](https://github.com/usabilityhub/rails-erb-loader) npm package to work.
50
77
 
51
78
  Add `erb` loader to webpacker:
@@ -59,16 +86,16 @@ Create webpack ERB config `config/webpack/loaders/erb.js`:
59
86
 
60
87
  ``` javascript
61
88
  module.exports = {
62
- test: /\.js\.erb$/,
63
- enforce: 'pre',
64
- exclude: /node_modules/,
65
- use: [{
66
- loader: 'rails-erb-loader',
67
- options: {
68
- runner: (/^win/.test(process.platform) ? 'ruby ' : '') + 'bin/rails runner'
69
- }
70
- }]
71
- }
89
+ module: {
90
+ rules: [
91
+ {
92
+ test: /\.erb$/,
93
+ enforce: 'pre',
94
+ loader: 'rails-erb-loader'
95
+ },
96
+ ]
97
+ }
98
+ };
72
99
  ```
73
100
 
74
101
  Enable `erb` extension in `config/webpack/environment.js`:
@@ -91,7 +118,32 @@ import * as Routes from 'routes.js.erb';
91
118
  window.Routes = Routes;
92
119
  ```
93
120
 
94
- #### Sprockets (Deprecated)
121
+ <div id='definitions'></div>
122
+
123
+ ### Typescript Definitions
124
+
125
+ JsRoutes has typescript support out of the box.
126
+
127
+ Restrictions:
128
+
129
+ * Only available if `module_type` is set to `ESM` (strongly recommended and default).
130
+ * Webpacker Automatic Updates are not available because typescript compiler can not be configured to understand `.erb` extensions.
131
+
132
+ For the basic setup of typscript definitions see [Quick Start](#quick-start) setup.
133
+ More advanced setup would involve calling manually:
134
+
135
+ ``` ruby
136
+ JsRoutes.definitions! # to output to file
137
+ # or
138
+ JsRoutes.definitions # to output to string
139
+ ```
140
+
141
+ Even more advanced setups can be achieved by setting `module_type` to `DTS` inside [configuration](#module_type)
142
+ which will cause any `JsRoutes` instance to generate defintions instead of routes themselves.
143
+
144
+ <div id="sprockets"></div>
145
+
146
+ ### Sprockets (Deprecated)
95
147
 
96
148
  If you are using [Sprockets](https://github.com/rails/sprockets-rails) you may configure js-routes in the following way.
97
149
 
@@ -120,7 +172,7 @@ This cache is not flushed on server restart in development environment.
120
172
 
121
173
  **Important:** If routes.js file is not updated after some configuration change you need to run this rake task again.
122
174
 
123
- ### Configuration
175
+ ## Configuration
124
176
 
125
177
  You can configure JsRoutes in two main ways. Either with an initializer (e.g. `config/initializers/js_routes.rb`):
126
178
 
@@ -130,7 +182,7 @@ JsRoutes.setup do |config|
130
182
  end
131
183
  ```
132
184
 
133
- Or dynamically in JavaScript, although only [Formatter Options](#formatter-options) are supported (see below)
185
+ Or dynamically in JavaScript, although only [Formatter Options](#formatter-options) are supported:
134
186
 
135
187
  ``` js
136
188
  import * as Routes from 'routes'
@@ -140,14 +192,16 @@ Routes.configure({
140
192
  Routes.config(); // current config
141
193
  ```
142
194
 
143
- #### Available Options
195
+ ### Available Options
144
196
 
145
- ##### Generator Options
197
+ #### Generator Options
146
198
 
147
199
  Options to configure JavaScript file generator. These options are only available in Ruby context but not JavaScript.
148
200
 
201
+ <div id='module-type'></div>
202
+
149
203
  * `module_type` - JavaScript module type for generated code. [Article](https://dev.to/iggredible/what-the-heck-are-cjs-amd-umd-and-esm-ikm)
150
- * Options: `ESM`, `UMD`, `CJS`, `AMD`, `nil`.
204
+ * Options: `ESM`, `UMD`, `CJS`, `AMD`, `DTS`, `nil`.
151
205
  * Default: `ESM`
152
206
  * `nil` option can be used in case you don't want generated code to export anything.
153
207
  * `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
159
213
  * Default: `[]`
160
214
  * The regexp applies only to the name before the `_path` suffix, eg: you want to match exactly `settings_path`, the regexp should be `/^settings$/`
161
215
  * `namespace` - global object used to access routes.
216
+ * Only available if `module_type` option is set to `nil`.
162
217
  * Supports nested namespace like `MyProject.routes`
163
218
  * Default: `nil`
164
219
  * `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
175
230
  * `file` - a file location where generated routes are stored
176
231
  * Default: `app/javascript/routes.js` if setup with Webpacker, otherwise `app/assets/javascripts/routes.js` if setup with Sprockets.
177
232
 
178
- ##### Formatter Options
233
+ #### Formatter Options
179
234
 
180
235
  Options to configure routes formatting. These options are available both in Ruby and JavaScript context.
181
236
 
@@ -193,7 +248,7 @@ Options to configure routes formatting. These options are available both in Ruby
193
248
  * This option exists because JS doesn't provide a difference between an object and a hash
194
249
  * Default: `_options`
195
250
 
196
- ### Advanced Setup
251
+ ## Advanced Setup
197
252
 
198
253
  In case you need multiple route files for different parts of your application, you have to create the files manually.
199
254
  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
231
286
  ``` js
232
287
  import * as Routes from 'routes';
233
288
 
234
- Routes.users_path() // => "/users"
235
- Routes.user_path(1) // => "/users/1"
236
- Routes.user_path(1, {format: 'json'}) // => "/users/1.json"
237
- Routes.user_path(1, {anchor: 'profile'}) // => "/users/1#profile"
238
- Routes.new_user_project_path(1, {format: 'json'}) // => "/users/1/projects/new.json"
239
- Routes.user_project_path(1,2, {q: 'hello', custom: true}) // => "/users/1/projects/2?q=hello&custom=true"
240
- Routes.user_project_path(1,2, {hello: ['world', 'mars']}) // => "/users/1/projects/2?hello%5B%5D=world&hello%5B%5D=mars"
241
- ```
289
+ Routes.users_path()
290
+ // => "/users"
242
291
 
243
- Using serialized object as route function arguments:
292
+ Routes.user_path(1)
293
+ // => "/users/1"
294
+
295
+ Routes.user_path(1, {format: 'json'})
296
+ // => "/users/1.json"
297
+
298
+ Routes.user_path(1, {anchor: 'profile'})
299
+ // => "/users/1#profile"
300
+
301
+ Routes.new_user_project_path(1, {format: 'json'})
302
+ // => "/users/1/projects/new.json"
303
+
304
+ Routes.user_project_path(1,2, {q: 'hello', custom: true})
305
+ // => "/users/1/projects/2?q=hello&custom=true"
306
+
307
+ Routes.user_project_path(1,2, {hello: ['world', 'mars']})
308
+ // => "/users/1/projects/2?hello%5B%5D=world&hello%5B%5D=mars"
244
309
 
245
- ``` js
246
310
  var google = {id: 1, name: "Google"};
247
- Routes.company_path(google) // => "/companies/1"
311
+ Routes.company_path(google)
312
+ // => "/companies/1"
313
+
248
314
  var google = {id: 1, name: "Google", to_param: "google"};
249
- Routes.company_path(google) // => "/companies/google"
315
+ Routes.company_path(google)
316
+ // => "/companies/google"
250
317
  ```
251
318
 
252
319
  In order to make routes helpers available globally:
@@ -255,7 +322,7 @@ In order to make routes helpers available globally:
255
322
  jQuery.extend(window, Routes)
256
323
  ```
257
324
 
258
- ## Get spec of routes and required params
325
+ ### Get spec of routes and required params
259
326
 
260
327
  Possible to get `spec` of route by function `toString`:
261
328
 
@@ -314,29 +381,20 @@ import {
314
381
  } from 'routes.js.erb'
315
382
  ```
316
383
 
384
+ Such import structure allows for moddern JS bundlers like [Webpack](https://webpack.js.org/) to only include explicitly imported routes into JS bundle file.
385
+ See [Tree Shaking](https://webpack.js.org/guides/tree-shaking/) for more information.
386
+
317
387
  ### Exclude option
318
388
 
319
389
  Split your routes into multiple files related to each section of your website like:
320
390
 
321
391
  ``` javascript
322
392
  // admin-routes.js.erb
323
- <%= JsRoutes.generate(include: /^admin_/)
393
+ <%= JsRoutes.generate(include: /^admin_/) %>
324
394
  // app-routes.js.erb
325
- <%= JsRoutes.generate(exclude: /^admin_/)
326
- ```
327
-
328
- ## JsRoutes and Heroku
329
-
330
- 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.
331
-
332
- For example create routes.js.erb in assets folder with needed content:
333
-
334
- ``` erb
335
- <%= JsRoutes.generate(options) %>
395
+ <%= JsRoutes.generate(exclude: /^admin_/) %>
336
396
  ```
337
397
 
338
- This should just work.
339
-
340
398
  ## Advantages over alternatives
341
399
 
342
400
  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:
349
407
  * Support Rails `#to_param` convention for seo optimized paths
350
408
  * Well tested
351
409
 
352
- ## Version 2 TODO
353
-
354
- * Add routes generation .d.ts file
355
- * Add config option on the output format: js, ts, d.ts
356
- * Add prettier
357
- * Add eslint
358
- * Add development guide
359
-
360
410
  #### Thanks to [contributors](https://github.com/railsware/js-routes/contributors)
361
411
 
362
412
  #### Have fun
data/VERSION_2_UPGRADE.md CHANGED
@@ -2,23 +2,40 @@
2
2
 
3
3
  ### Using ESM module by default
4
4
 
5
- The default setting are now changed:
5
+ 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.
6
+ [ESM+Webpacker](/Readme.md#webpacker) upgrade is recommended.
6
7
 
7
- Setting | Old | New
8
- --- | --- | ---
9
- module\_type | nil | ESM
10
- namespace | Routes | nil
8
+ 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.
9
+ Here are supported values:
11
10
 
12
- This is more optimized setup for WebPacker. You can restore the old configuration like this:
11
+ * CJS
12
+ * UMD
13
+ * AMD
14
+ * ESM
15
+ * nil
16
+
17
+ [Explaination Article](https://dev.to/iggredible/what-the-heck-are-cjs-amd-umd-and-esm-ikm)
18
+
19
+ 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:
13
20
 
14
21
  ``` ruby
15
22
  JsRoutes.setup do |config|
16
23
  config.module_type = nil
17
- config.namespace = 'Routes'
24
+ config.namespace = "Routes"
18
25
  end
19
26
  ```
20
27
 
21
- However, [ESM+Webpacker](/Readme.md#webpacker) upgrade is recommended.
28
+ ### JSDoc comment
29
+
30
+ New version of js-routes generates function comment in the [JSDoc](https://jsdoc.app) format.
31
+ If you have any problems with that, you can disable it like this:
32
+
33
+
34
+ ``` ruby
35
+ JsRoutes.setup do |config|
36
+ config.documentation = false
37
+ end
38
+ ```
22
39
 
23
40
  ### `required_params` renamed
24
41
 
@@ -47,15 +64,3 @@ try {
47
64
  }
48
65
  }
49
66
  ```
50
-
51
- ### JSDoc comment format
52
-
53
- New version of js-routes generates function comment in the [JSDoc](https://jsdoc.app) format.
54
- If you have any problems with that disable the annotation:
55
-
56
- ``` ruby
57
- JsRoutes.setup do |config|
58
- config.documentation = false
59
- end
60
- ```
61
-
data/js-routes.gemspec CHANGED
@@ -25,7 +25,7 @@ Gem::Specification.new do |s|
25
25
 
26
26
  s.add_runtime_dependency(%q<railties>, [">= 4"])
27
27
  s.add_development_dependency(%q<sprockets-rails>)
28
- s.add_development_dependency(%q<rspec>, [">= 3.0.0"])
28
+ s.add_development_dependency(%q<rspec>, [">= 3.10.0"])
29
29
  s.add_development_dependency(%q<bundler>, [">= 1.1.0"])
30
30
  s.add_development_dependency(%q<appraisal>, [">= 0.5.2"])
31
31
  s.add_development_dependency(%q<bump>, [">= 0.10.0"])
@@ -0,0 +1,32 @@
1
+ require "rails/generators"
2
+
3
+ class JsRoutes::Webpacker < Rails::Generators::Base
4
+
5
+ source_root File.expand_path(__FILE__ + "/../../../templates")
6
+
7
+ def create_webpack
8
+ copy_file "initializer.rb", "config/initializers/js_routes.rb"
9
+ copy_file "erb.js", "config/webpack/loaders/erb.js"
10
+ copy_file "routes.js.erb", "app/javascript/routes.js.erb"
11
+ inject_into_file "config/webpack/environment.js", loader_content
12
+ inject_into_file "app/javascript/packs/application.js", pack_content
13
+ command = Rails.root.join("./bin/yarn add rails-erb-loader")
14
+ run command
15
+ end
16
+
17
+ protected
18
+
19
+ def pack_content
20
+ <<-JS
21
+ import * as Routes from 'routes.js.erb';
22
+ window.Routes = Routes;
23
+ JS
24
+ end
25
+
26
+ def loader_content
27
+ <<-JS
28
+ const erb = require('./loaders/erb')
29
+ environment.loaders.append('erb', erb)
30
+ JS
31
+ end
32
+ end
@@ -1,3 +1,3 @@
1
1
  class JsRoutes
2
- VERSION = "2.0.6"
2
+ VERSION = "2.1.1"
3
3
  end