Generates javascript file that defines all Rails named routes as javascript helpers
Your Rails Gemfile:
gem "js-routes"There are several possible ways to setup JsRoutes:
- Quick and easy - Recommended
- Uses Rack Middleware to automatically update routes locally
- Automatically generates routes files on javascript build
- Works great for a simple Rails application
- Advanced Setup
- Allows very custom setups
- Automatic updates need to be customized
- Webpacker ERB Loader - Legacy
- Requires ESM module system (the default)
- Doesn't support typescript definitions
- Sprockets - Legacy
- Deprecated and not recommended for modern apps
Setup Rack Middleware
to automatically generate and maintain routes.js file and corresponding
Typescript definitions routes.d.ts:
Run a command:
rails generate js_routes:middlewareAdd the following to config/environments/development.rb:
config.middleware.use(JsRoutes::Middleware)Use it in any JS file:
import {post_path} from '../routes';
alert(post_path(1))Upgrade js building process to update js-routes files in Rakefile:
task "javascript:build" => "js:routes:typescript"
# For setups without jsbundling-rails
task "assets:precompile" => "js:routes:typescript"Add js-routes files to .gitignore:
/app/javascript/routes.js
/app/javascript/routes.d.ts
IMPORTANT: the setup doesn't support IDE autocompletion with Typescript
Run a command:
./bin/rails generate js_routes:webpackerThe routes files can be automatically updated without rake task being called manually.
It requires rails-erb-loader npm package to work.
Add erb loader to webpacker:
yarn add rails-erb-loader
rm -f app/javascript/routes.js # delete static file if anyCreate webpack ERB config config/webpack/loaders/erb.js:
module.exports = {
module: {
rules: [
{
test: /\.erb$/,
enforce: 'pre',
loader: 'rails-erb-loader'
},
]
}
};Enable erb extension in config/webpack/environment.js:
const erb = require('./loaders/erb')
environment.loaders.append('erb', erb)Create routes file app/javascript/routes.js.erb:
<%= JsRoutes.generate() %>Use routes wherever you need them:
import {post_path} from 'routes.js.erb';
alert(post_path(2));IMPORTANT: that this setup requires the JS routes file to be updates manually
Routes file can be generated with a rake task:
rake js:routes
# OR for typescript support
rake js:routes:typescriptIn 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 setup.
// app/javascript/admin/routes.js.erb
<%= JsRoutes.generate(include: /admin/) %>// app/javascript/customer/routes.js.erb
<%= JsRoutes.generate(exclude: /admin/) %>You can manipulate the generated helper manually by injecting ruby into javascript:
export const routes = <%= JsRoutes.generate(module_type: nil, namespace: nil) %>If you want to generate the routes files manually with custom options, you can use JsRoutes.generate!:
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"}
)JsRoutes has typescript support out of the box.
Restrictions:
- Only available if
module_typeis set toESM(strongly recommended and default). - Webpacker Automatic Updates are not available because typescript compiler can not be configured to understand
.erbextensions.
For the basic setup of typscript definitions see Quick Start setup. More advanced setup would involve calling manually:
JsRoutes.definitions! # to output to file
# or
JsRoutes.definitions # to output to stringEven more advanced setups can be achieved by setting module_type to DTS inside configuration
which will cause any JsRoutes instance to generate defintions instead of routes themselves.
If you are using Sprockets you may configure js-routes in the following way.
Setup the initializer (e.g. config/initializers/js_routes.rb):
JsRoutes.setup do |config|
config.module_type = nil
config.namespace = 'Routes'
endRequire JsRoutes in app/assets/javascripts/application.js or other bundle
//= require js-routesAlso in order to flush asset pipeline cache sometimes you might need to run:
rake tmp:cache:clearThis 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.
You can configure JsRoutes in two main ways. Either with an initializer (e.g. config/initializers/js_routes.rb):
JsRoutes.setup do |config|
config.option = value
endOr dynamically in JavaScript, although only Formatter Options are supported:
import {configure, config} from 'routes'
configure({
option: value
});
config(); // current configOptions to configure JavaScript file generator. These options are only available in Ruby context but not JavaScript.
module_type- JavaScript module type for generated code. Article- Options:
ESM,UMD,CJS,AMD,DTS,nil. - Default:
ESM niloption can be used in case you don't want generated code to export anything.
- Options:
documentation- specifies if each route should be annotated with JSDoc comment- Default:
true
- Default:
exclude- Array of regexps to exclude from routes.- Default:
[] - The regexp applies only to the name before the
_pathsuffix, eg: you want to match exactlysettings_path, the regexp should be/^settings$/
- Default:
include- Array of regexps to include in routes.- Default:
[] - The regexp applies only to the name before the
_pathsuffix, eg: you want to match exactlysettings_path, the regexp should be/^settings$/
- Default:
namespace- global object used to access routes.- Only available if
module_typeoption is set tonil. - Supports nested namespace like
MyProject.routes - Default:
nil
- Only available if
camel_case- specifies if route helpers should be generated in camel case instead of underscore case.- Default:
false
- Default:
url_links- specifies if*_urlhelpers should be generated (in addition to the default*_pathhelpers).- Default:
false - Note: generated URLs will first use the protocol, host, and port options specified in the route definition. Otherwise, the URL will be based on the option specified in the
default_url_optionsconfig. If no default option has been set, then the URL will fallback to the current URL based onwindow.location.
- Default:
compact- Remove_pathsuffix in path routes(*_urlroutes stay untouched if they were enabled)- Default:
false - Sample route call when option is set to true:
users() // => /users
- Default:
application- a key to specify which rails engine you want to generate routes too.- This option allows to only generate routes for a specific rails engine, that is mounted into routes instead of all Rails app routes
- Default:
Rails.application
file- a file location where generated routes are stored- Default:
app/javascript/routes.jsif setup with Webpacker, otherwiseapp/assets/javascripts/routes.jsif setup with Sprockets.
- Default:
Options to configure routes formatting. These options are available both in Ruby and JavaScript context.
default_url_options- default parameters used when generating URLs- Example:
{format: "json", trailing_slash: true, protocol: "https", subdomain: "api", host: "example.com", port: 3000} - Default:
{}
- Example:
prefix- string that will prepend any generated URL. Usually used when app URL root includes a path component.- Example:
/rails-app - Default:
Rails.application.config.relative_url_root
- Example:
serializer- a JS function that serializes a Javascript Hash object into URL paramters like{a: 1, b: 2} => "a=1&b=2".- Default:
nil. Uses built-in serializer compatible with Rails - Example:
jQuery.param- use jQuery's serializer algorithm. You can attach serialize function from your favorite AJAX framework. - Example:
function (object) { ... }- use completely custom serializer of your application.
- Default:
special_options_key- a special key that helps JsRoutes to destinguish serialized model from options hash- This option exists because JS doesn't provide a difference between an object and a hash
- Default:
_options
Configuration above will create a nice javascript file with Routes object that has all the rails routes available:
import {
user_path, user_project_path, company_path
} as Routes from 'routes';
users_path()
// => "/users"
user_path(1)
// => "/users/1"
user_path(1, {format: 'json'})
// => "/users/1.json"
user_path(1, {anchor: 'profile'})
// => "/users/1#profile"
new_user_project_path(1, {format: 'json'})
// => "/users/1/projects/new.json"
user_project_path(1,2, {q: 'hello', custom: true})
// => "/users/1/projects/2?q=hello&custom=true"
user_project_path(1,2, {hello: ['world', 'mars']})
// => "/users/1/projects/2?hello%5B%5D=world&hello%5B%5D=mars"
var google = {id: 1, name: "Google"};
company_path(google)
// => "/companies/1"
var google = {id: 1, name: "Google", to_param: "google"};
company_path(google)
// => "/companies/google"In order to make routes helpers available globally:
import * as Routes from '../routes';
jQuery.extend(window, Routes)Possible to get spec of route by function toString:
import {user_path, users_path} from '../routes'
users_path.toString() // => "/users(.:format)"
user_path.toString() // => "/users/:id(.:format)"Route function also contain method requiredParams inside which returns required param names array:
users_path.requiredParams() // => []
user_path.requiredParams() // => ['id']JsRoutes tries to replicate the Rails routing API as closely as possible. If you find any incompatibilities (outside of what is described below), please open an issue.
Sometimes the destinction between JS Hash and Object can not be found by JsRoutes. In this case you would need to pass a special key to help:
import {company_project_path} from '../routes'
company_project_path({company_id: 1, id: 2}) // => Not enough parameters
company_project_path({company_id: 1, id: 2, _options: true}) // => "/companies/1/projects/2"JsRoutes itself does not have security holes. It makes URLs without access protection more reachable by potential attacker. If that is an issue for you, you may use one of the following solutions:
Make sure module_type is set to ESM (the default). Modern JS bundlers like
Webpack can statically determine which ESM exports are used, and remove
the unused exports to reduce bundle size. This is known as Tree
Shaking.
JS files can use named imports to import only required routes into the file, like:
import {
inbox_path,
inboxes_path,
inbox_message_path,
inbox_attachment_path,
user_path,
} from '../routes'JS files can also use star imports (import * as) for tree shaking, as long as only explicit property accesses are used.
import * as routes from '../routes';
console.log(routes.inbox_path); // OK, only `inbox_path` is included in the bundle
console.log(Object.keys(routes)); // forces bundler to include all exports, breaking tree shakingSplit your routes into multiple files related to each section of your website like:
// admin-routes.js.erb
<%= JsRoutes.generate(include: /^admin_/) %>
// app-routes.js.erb
<%= JsRoutes.generate(exclude: /^admin_/) %>There are some alternatives available. Most of them has only basic feature and don't reach the level of quality I accept. Advantages of this one are:
- Rails 4,5,6 support
- ESM Tree shaking support
- Rich options set
- Full rails compatibility
- Support Rails
#to_paramconvention for seo optimized paths - Well tested
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent