chore: migrate from qonsole-rails gem to @epimorphics/qonsole npm package

[joescottdave]

Background

The qonsole-rails gem embeds a SPARQL query console as a Rails engine. The functionality has been rewritten as a standalone Web Component in the @epimorphics/qonsole npm package, which removes the dependency on Rails, jQuery, Bootstrap, and several other gem dependencies.

This migration is blocked on epimorphics/qonsole#62 being approved and a v2 release published.

Acceptance criteria

• gem 'qonsole_rails' removed from Gemfile
• Engine mount removed from config/routes.rb
• @epimorphics/qonsole added as a yarn dependency
• config/qonsole.json content converted to <epi-qonsole> HTML attributes
• A Rails proxy action added to forward SPARQL queries to the endpoint, so all traffic is observable and rate-limiting/monitoring can be applied
• <epi-qonsole> wired to the proxy via a custom service property (see migration guide Option B)
• Direct browser-to-endpoint requests confirmed blocked (endpoint should not be exposed publicly)
• Styles updated to use CSS custom properties in place of Bootstrap overrides
• Unused gem dependencies removed (font-awesome-rails, haml-rails, jquery-rails, jquery-datatables-rails, lodash-rails, modulejs-rails, faraday stack if not used elsewhere)

References

• feat: rewrite as Vue 3 web component qonsole#62 — v2 PR (must be merged and released before this work begins)

---

Migrating from qonsole-rails to @epimorphics/qonsole

1. Remove the gem

In Gemfile, remove:

gem 'qonsole_rails'

In config/routes.rb, remove:

mount QonsoleRails::Engine, at: '/qonsole'

You can also drop any gem dependencies that were only there for qonsole: font-awesome-rails, haml-rails, jquery-rails, jquery-datatables-rails, lodash-rails, modulejs-rails, and the faraday stack (unless used elsewhere).

2. Install the npm package

Add to .yarnrc.yml:

npmScopes:
  epimorphics:
    npmRegistryServer: "https://npm.pkg.github.com"
    npmAuthToken: "YOUR_GITHUB_TOKEN"

Then:

yarn add @epimorphics/qonsole

Import it in your JS bundle entry point:

import '@epimorphics/qonsole'

3. Convert config/qonsole.json to HTML attributes

The gem loaded config/qonsole.json on the server. With the web component, you pass that same data as inline attributes. The page that previously rendered at /qonsole (via the mounted engine) becomes a simple HTML page you own:

<epi-qonsole
  endpoints='{"default": "https://your-sparql-endpoint/sparql"}'
  prefixes='{"rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#", ...}'
  queries='[{"name": "Example query", "query": "SELECT * WHERE { ?s ?p ?o } LIMIT 10"}]'
></epi-qonsole>

4. Decide how to handle SPARQL query execution

This is the key architectural choice. The gem ran queries server-side through a Rails controller (which handled CORS, timeouts, and endpoint whitelisting). The npm component sends queries directly from the browser.

Option A — Direct to endpoint (simplest): Works if the SPARQL endpoint allows CORS from your domain. No backend needed.

Option B — Route through a thin Rails proxy (matches existing behaviour): Keep a minimal Rails action and wire it via a custom service property:

document.querySelector('epi-qonsole').service = {
  execute(query, { url, format, success, error }) {
    fetch('/sparql/query', {
      method: 'POST',
      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
      body: new URLSearchParams({ query, output: format, endpoint: url })
    })
    .then(r => r.text())
    .then(success)
    .catch(error)
  }
}

Option B is worth doing if you need server-side endpoint validation (the gem had a whitelist check), want to keep credentials/endpoint URLs off the client, or need to preserve the Faraday retry/timeout behaviour.

5. Update styles

The gem used Bootstrap classes and global SCSS. The web component is shadow-DOM encapsulated — global styles won't bleed in. Use CSS custom properties on the element to match your brand:

epi-qonsole {
  --qonsole-color: #333;
  --qonsole-accent-color: #0056b3;
  --qonsole-accent-text-color: #fff;
  --qonsole-font-family: sans-serif;
}

Summary

	qonsole-rails gem	@epimorphics/qonsole
SPARQL query config	config/qonsole.json	HTML attributes
Query execution	Rails controller + Faraday	Browser fetch (or custom service)
Routing	Mounted engine at /qonsole	Your own page/route
Styling	Bootstrap + global SCSS	CSS custom properties
HTML markup	Haml template from engine	Just <epi-qonsole ...>
Endpoint security	Server-side whitelist	Must re-implement if needed (Option B above)