[feature request] add public method to generate __jsr object

[phegman]

Background

I am customizing the output of js-routes because of some customizations in our routing system and to split the path helpers up into multiple files. I am using JsRoutes::Route to generate the path helper but there is no built in way to generate the __jsr object without also generating the path helpers. I am using this workaround at the moment but it would be cleaner if I could just call a method.

# frozen_string_literal: true

# We want the js-routes JavaScript utils but need to customize the output of the JavaScript path helpers.
# To force js-routes to generate the JavaScript utils but not the JavaScript path helpers
# we can pass a fake `Rails::Application` object with empty `named_routes`.
# We then customize the output of the JavaScript path helpers in `lib/gitlab/js_routes.rb`
class EmptyRoutesApplication
  Routes = Struct.new(:named_routes)

  NamedRoutes = Struct.new do
    def to_h
      {}
    end
  end

  def routes
    Routes.new(NamedRoutes.new)
  end

  def reload_routes_unless_loaded; end

  def reload_routes!; end

  def is_a?(klass)
    klass == Rails::Application
  end
end

JsRoutes.setup do |c|
  c.application = -> do
    EmptyRoutesApplication.new
  end
end

Proposal

Add a public method such as generate_jsr to lib/js_routes/instance.rb. This will allow more custom setups where you can fully customize the output.

[phegman]

Happy to open a PR if this feature request is approved

[bogdan]

__jsr method is not public and it changed a lot. Also, it is optimized for minimal bundle size but not developer convenience.

I don't see this as a valuable direction for the library to go.
I think if you can explain how you are using it, we can find a better solution or you convince me otherwise.

[phegman]

@bogdan thanks for the reply!

https://gitlab.com/gitlab-org/gitlab/-/merge_requests/216184 is the merge request we are trying to implement js-routes in. Below is the TL:DR on why exposing __jsr would be helpful for us:

1. We have a custom routing setup so need to generate the JavaScript path helpers ourselves. For example we are implementing Organization scoped routing where we choose a path helper behind the scenes depending on the organization context. We also have shorthand project helpers that we had to implement in JavaScript helpers as well.

2. When we generated one file it was ~15mb which, even in development, is quite large. In our dev environment (vite) we don't have code splitting (this is default how vite works) and therefore you need to download a 15mb file. Not a huge deal but we decided it was large enough that we wanted to split the path helpers up into multiple files. This is an abbreviated version of what we went with:

.
└── app/
    └── assets/
        └── javascripts/
            └── path_helpers/
                ├── core.js
                ├── utils.js
                ├── project.js
                ├── group.js
                └── admin.js

// app/asssets/javascripts/path_helpers/group.js

import { __jsr } from '~/path_helpers/core';
import { hasOrganizationScopedPaths } from '~/path_helpers/utils';


/**
 * Generates rails route to
 * /groups/*id/-/edit(.:format)
 * @param {any} id
 * @param {object | undefined} options
 * @returns {string} route path
 */
export const editGroupPath = /*#__PURE__*/ (...args) => {
  const _organizationEditGroupPath = __jsr.r({"organization_path":{"r":true},"id":{"r":true},"format":{}}, [2,[7,"/"],[2,[6,"o"],[2,[7,"/"],[2,[3,"organization_path"],[2,[7,"/"],[2,[6,"groups"],[2,[7,"/"],[2,[5,[3,"id"]],[2,[7,"/"],[2,[6,"-"],[2,[7,"/"],[2,[6,"edit"],[1,[2,[8,"."],[3,"format"]]]]]]]]]]]]]]]);
  const _editGroupPath = __jsr.r({"id":{"r":true},"format":{}}, [2,[7,"/"],[2,[6,"groups"],[2,[7,"/"],[2,[5,[3,"id"]],[2,[7,"/"],[2,[6,"-"],[2,[7,"/"],[2,[6,"edit"],[1,[2,[8,"."],[3,"format"]]]]]]]]]]]);

  if (hasOrganizationScopedPaths()) {
    return _organizationEditGroupPath(gon?.current_organization.path, ...args);
  }

  return _editGroupPath(...args);
};

I realize this is a very custom setup so I understand if it is not something you want to support. That said, I do think giving the option to generate __jsr separately makes the gem more flexible.

[bogdan]

The thing that immediately comes to my mind is the conversation here: #326 (comment). That may feel related.

So I guess what I would do is have something like this in my routes:

Rails.application.routes.draw do
  scope "(/o/:organization_path)" do
    ...
  end
end

So now, your route helper names are the same when organization_path is present or not. You can control the appearance of that part of the path with:

import { configure } from "./routes.js"

configure({default_url_options: {
  organization_path: gon?.current_organization?.has_scoped_paths ?  gon?.current_organization.path : nil
}})

The part I didn't understand:

we wanted to split the path helpers up into multiple files

How is the approach would help to split files?

BTW you can probably generate the no-routes file you need with:

JsRoutes.generate(include: %r{\A\z} )

[phegman]

@bogdan thanks for the help, appreciate it!

I think the routing example you gave is essentially what we have in https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/routes.rb#L384. The thing is we want engineers to just be able to call the global path helper and have the organization scoping be taken care of behind the scenes. So we don't want them to have to choose between fooBarPath and organizationFooBarPath if that makes any sense.

Essentially we are trying to have the same logic in https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/helpers/routing/organizations_helper.rb#L78 on the frontend.

It is a very custom setup so wouldn't expect this package to take care of any of this out of the box.

How is the approach would help to split files?

You have docs on generating multiple files but I couldn't think of a way to split the routes into multiple files without having __jsr defined separately in each file. The downside to this is:

• If you want to use configure you would need to import it from each file and call each one separately
• __jsr will be defined multiple times in the production bundle causing unnecessary bloat

In my testing with a production Webpack build if I put __jsr in a separate file then import it in each file with import { __jsr } from '~/path_helpers/core'; I get the desired output which is __jsr is in the main.chunk.js and all the individual path helpers are in the bundle they are used in (e.g. commons-pages.admin.projects.index-pages.dashboard.groups.chunk.js). Also I can import configure from ~/path_helpers/core and it applies to all helpers across multiple files.

I realize this may be specific to our setup, but I do think having the option to import __jsr in multiple files gives this package more flexibility for different bundling setups.

Sidenote: thank you for all your hard work on this package, it is an amazing package! I am excited about how it can improve our developer experience at GitLab and help reduce the number of URL related bugs.

[bogdan]

In order to have same route helper names for organization and non-organization scoped routes you need to define them once without as option for wrapping scope and with () optional notation:

    scope(
      path: '(/o/:organization_path)',
      constraints: {
        organization_path: Gitlab::PathRegex.organization_route_regex
      },
    ) do
      draw_all_routes
    end

Did you try that?

I am not sure how contraits are applied to dynamic route parts. Maybe you would need to modify your constratin to allow nil or "" values.

from LLM: https://gist.github.com/bogdan/ee68864c288b05128bd9c902672381f0

[phegman]

@bogdan I believe we looked into something similar but decided against it as we didn't want to modify existing routes. Instead we opted to create counterpart organization scoped routes as it gave us more flexibility with feature flags and reduced risk.

Even if we were able to implement your suggestion above it doesn't really fix our problem of wanting to split the JavaScript path helpers into multiple files but only include __jsr once. Another reason we want to do this (which I forgot to mention previously) is we put enterprise edition code in a separate directory and we would like to keep this same pattern for JavaScript path helpers.

What is your concern with allowing __jsr to be stored in a separate file and then imported with ES6 imports? It opens up flexibility around splitting up JavaScript path helpers into multiple files without having __jsr included in the bundle multiple times.

Adding new methods something like these would solve our problem:

generate_utils - generates __jsr object
generate_without_utils - same as generate but doesn't inline __jsr object.

Then you could do something like this:

class AdvancedJsRoutesMiddleware < JsRoutes::Middleware
  def regenerate
    path = "app/javascript"

   utils = <<~JS
     #{JsRoutes.generate_utils}
     export { __jsr };
   JS
   write_file(Rails.root.join(path, 'utils.js'), utils)

   admin_routes = <<~JS
     import { __jsr } from './utils'
     #{JsRoutes.generate_without_utils(include: /^admin_/)}
   JS
   write_file(Rails.root.join(path, 'admin_routes.js'), admin_routes)

   api_routes = <<~JS
     import { __jsr } from './utils'
     #{JsRoutes.generate_without_utils(include: /^api_/)}
   JS
   write_file(Rails.root.join(path, 'api_routes.js'), api_routes)
  end

  def write_file(path, output)
    File.open(path, 'w') do |f|
      f.write output
    end
  end
end

That is a rough example but hoping that helps explain our use-case 🙂

[bogdan]

ok, so I understand the problem about having utils deduplicated when generating multiple routes files.
I do agree this can not be achieved with current API.

The thing I don't want is exposure of any other methods than currently exposed: configure, config, serialize and r.
I didn't see the need for it in your use case, am I right?

If so, JsRoutes.generate_utils should be equal to:

JsRoutes.generate(include: %r{\A\z})

You can make it more flexible with:

const __jsr = <%= JsRoutes.generate(include: %r{\A\z}, module_type: nil) %>
export __jsr;

However, the direction I want it to go is to have a js package like rails-routes, so you can import it wherever you want.
It will:

• make sure utils can be used anywhere even non-rails project
• any generated code can import utils consistently
• utils are not part of the repo (the fact that they are reminds me JS of the early 2000s)

On other end, the only way making sure utils are shared is through something like:

JsRoutes.generate(package: true, **options)
# OR more flexibly
JsRoutes.generate(package: "require('rails-routes')")
# OR even not sure if it needs to be this crazy
jsRoutes.generate(package: JsRoutes.package(module_type: nil))

The difficulty with that is making that package completely static: no use of RubyVariables inside (see routes.ts).
I have a strategy avoiding any variable except MODULE_TYPE in that package.

MODULE_TYPE is a weird legacy this library has. It is only helpful in legacy applications, but some people find it more convenient to them to use nil module type when they want to avoid dealing with JS bundling bulls**t.

I hope we can make the package parameter usage ESM only.
But even then, supporting non-ESM module type would require a JS bundler to convert ESM js package to that module type which makes library build process for more complex.

Thoughts?

[phegman]

@bogdan Thanks for considering this change and the detailed comment. I like the direction you outlined and that would solve our use case. I think overall it adds flexibility to the package and makes it easier to split routes across multiple files but only include the utils once in the bundle.

Let me know if there is any way I can help to make this happen 🙂

[bogdan]

I am open to suggestion here or PR attempt that would cover your use cases with minimal effort but also maintain a general direction I described.