{"id":13515076,"url":"https://github.com/eliias/isorun","last_synced_at":"2025-03-06T03:10:36.838Z","repository":{"id":62122764,"uuid":"553548126","full_name":"eliias/isorun","owner":"eliias","description":"Run JavaScript applications embedded in your Rails application.","archived":false,"fork":false,"pushed_at":"2025-02-20T12:29:22.000Z","size":25492,"stargazers_count":41,"open_issues_count":24,"forks_count":0,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-02-27T02:16:23.787Z","etag":null,"topics":["javascript","rails","react","ruby","ssr","vue"],"latest_commit_sha":null,"homepage":"https://eliias.github.io/isorun","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/eliias.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-10-18T11:39:49.000Z","updated_at":"2025-02-20T12:29:02.000Z","dependencies_parsed_at":"2022-10-26T20:00:33.235Z","dependency_job_id":"5da0d29c-73b0-41dd-b816-7f4b99f9827d","html_url":"https://github.com/eliias/isorun","commit_stats":{"total_commits":131,"total_committers":2,"mean_commits":65.5,"dds":0.3893129770992366,"last_synced_commit":"203d976db6bc7a2ca777615db146979888a3c8f4"},"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eliias%2Fisorun","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eliias%2Fisorun/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eliias%2Fisorun/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eliias%2Fisorun/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eliias","download_url":"https://codeload.github.com/eliias/isorun/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242138875,"owners_count":20078006,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["javascript","rails","react","ruby","ssr","vue"],"created_at":"2024-08-01T05:01:06.025Z","updated_at":"2025-03-06T03:10:36.818Z","avatar_url":"https://github.com/eliias.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"isorun\" src=\"./docs/assets/logo.png\" width=\"200\" /\u003e\n\u003c/p\u003e\n\n---\n\n\u003e Run JavaScript applications in your Rails application.\n\n## Features\n\n* Import JavaScript functions, objects, or just values and use them in Ruby\n* An EMCAScript like Ruby DSL to load modules and import items\n* Automatically converts arguments and return values\n* Send messages between *JavaScript*\u003c-\u003e*Ruby* (allows to intercept network requests and avoid network round-trips for e.g. API calls)\n* Automatically reload modules when updated in development\n* Automatically extracts state (Apollo) and hydrates client-side \n* Supports server-side rendering of multiple apps on a single page\n* Examples for [React](./examples/rails-react-app), [Vue](./examples/rails-vue-app), [D3](./examples/rails-d3-app) and a [multi-app](./examples/rails-multi-app) setup\n\n## How to\n\n### Plain JavaScript\n\n```js\n// module.js\nexport function say(word) {\n  return word;  \n}\n```\n\n```ruby\ncontext = Isorun::Context.new\n\n# import `export function say` from module \nsay = context.import(:say).from(\"./module.js\")\nsay.call(\"Hello!\") # \"Hello!\"\n```\n\n### Simple React app\n\n```bash\nrails new myproject --javascript esbuild\ncd myproject\n```\n\n```js\n// package.json\n{\n  \"scripts\": {\n    \"build\": \"esbuild app/javascript/app.jsx --bundle --sourcemap --outdir=app/assets/builds --public-path=assets\",\n    \"build-server\": \"esbuild app/javascript/app-server.jsx --bundle --sourcemap --outdir=app/assets/builds --public-path=assets --format=esm\"\n  }\n}\n```\n\n```bash\n# Procfile.dev\nweb: bin/rails server -p 3000\njs: yarn build --watch\nssr: yarn build-server --watch\n```\n\n```ruby\n# config/initializers/isorun.rb\nIsorun.configure do\n  # …configure isorun\nend\n```\n\n```jsx\n// app/javascript/my_app.jsx\nimport * as React from \"react\";\nimport {hydrateRoot} from \"react-dom/client\";\n\nimport {App} from \"./my_app/App.jsx\";\n\nconst container = document.querySelector('#my_app');\nhydrateRoot(container, \u003cApp/\u003e);\n\n```\n\n```jsx\n// app/javascript/my_app-server.jsx\nimport * as React from \"react\";\nimport * as Server from \"react-dom/server\";\n\nimport {App} from \"./my_app/App.jsx\";\n\nexport default async function() {\n  return Server.renderToString(\u003cApp/\u003e);\n}\n```\n\n```erb\n\u003c!--my_view.html.erb--\u003e\n\u003c%= isorun_app(\"my_app\") %\u003e\n```\n\n## Ruby and platform support\n\nRuby versions:\n  - `2.7`\n  - `3.0`\n  - `3.1`.\n\nPlatforms and architectures:\n  - `x86_64-linux`\n  - `x86_64-apple`\n  - `arm64-apple` \n\n## Demo\n\nYou can also check out this demo video on YouTube. It shows how you can utilize\n*isorun* to render SVGs with Ruby on the server, utilizing JavaScript and the\nD3 library.\n\n[![How to use d3 in Ruby](./docs/assets/how-to-use-d3-in-ruby.png)](https://www.youtube.com/watch?v=EPHX4po4X4g)\n\n## Why server-side rendering (SSR)?\n\nThe fastest way to deliver an application to the user is streaming HTML directly\nto the browser. The slowest way to deliver an application, is downloading a\nJavaScript file first, parse and execute it on the client side.\n\nServer-side rendering is taking advantage of the fact that we can render a\nJavaScript application directly on the server, and stream the resulting HTML\ndirectly to the browser.\nThen we fetch the JavaScript file and eventually the application will\n(re-)hydrate the already rendered user interface.\n\nYou can take this concept even further and make your application work without\nJavaScript at all, but still use React or Vue (or any other view-controller\nlibrary) to define your user interface.\n\nRead\nmore: [Netflix functions without client-side React, and it's a good thing](https://jakearchibald.com/2017/netflix-and-react/).\n\nServer-side rendering has a few challenges:\n\n1. You need something that can compile and run JavaScript\n1. You need to be able to integrate the app with your preferred framework\n1. You need to deal with the reality of frontend clients making network requests and managing state\n\n**isorun** aims to make it as simple as possible to integrate a\nJavaScript application into your server-side development and deployment\nworkflow, without changing the development workflow for frontend engineers.\n\nThis gem provides a helper that can render a JavaScript application directly in\nyour Ruby process, embedding Google's *v8* library via [*deno_core*](https://crates.io/crates/deno_core).\nYou can think of it as running a headless JavaScript browser directly in your\nRuby process (threads). Using *v8* allows us to completely separate the\nexecution environments between individual renders and therefore prevent any\npotential [Cross-Request State Pollution](https://vuejs.org/guide/scaling-up/ssr.html#cross-request-state-pollution).\nIt is essentiallly the same as opening many tabs in one browser.\n\n## Why SSR for Ruby (on Rails)?\n\nI personally enjoy and use *Ruby on Rails* a lot, but I like to use some\nVue and React for frontend work. The integration of frontend and backend always\nfelt a bit off, and I wanted something that \"just works\" for most of my use\ncases.\n\nOne goal of **isorun** is that server-side rendering should feel naturally in\nRuby and Rails. A simple tag helper should be enough to render, deliver, and\nhydrate your complex JavaScript application. And if we want to do something\nnice with visualization libraries, it should be possible to run any JavaScript\nprogram and return the result to the user without spinning up a separate\nservice.\n\n### Alternatives\n\n#### \"No\" JavaScript\n\nIf you want to go all-in on the server side, I highly recommend taking a look at\n[HTML over the Wire](https://hotwired.dev/), and [StimulusReflex](https://docs.stimulusreflex.com/).\n\n#### Run a Node.js, deno, or  bun service\n\n**isorun** does SSR a bit different from how you would do it in a regular\nNode.js service. In addition to being able to render the application, it also\nsupports more powerful features like network intercepts. This means, that you\ncan directly call into the Ruby process from the JavaScript application and\ne.g. fetch data from the database. This is helpful for applications that\nutilize APIs to fetch their data.\nEven when server-side rendered, these applications issue network requests\nagainst the production API endpoints to get access to data. In a lot of cases,\nwe can accelerate this process by forwarding the network requests directly to\nthe target controller/action in Rails.Instead of fetching \n\n**Example** A React applications queries a Rails GraphQL API\n\nWe can override the HttpLink `fetch` method and utilize the `@isorun/rails`\npackage to send the HTTP request for the GraphQL API directly to the Ruby\nprocess, instead of sending it over the network.\n\n```js\nimport {apollo} from \"@isorun/rails\";\n\nimport {App} from \"../my_app/App.jsx\";\n\nconst apolloClient = new ApolloClient({\n  ssrMode: true,\n  cache: new InMemoryCache(),\n  link: new HttpLink({\n    uri: 'http://localhost:3000/graphql',\n    fetch: apollo.fetch\n  })\n});\n```\n\n```ruby\nIsorun.configure do\n  receiver do |request|\n    query, variables, context, operation_name = parse(request)\n    \n    RailsAppSchema.execute(\n      query,\n      variables: variables,\n      context: context,\n      operation_name: operation_name\n    )\n  end\nend\n```\n\n## Installation\n\nInstall the gem and add to the application's Gemfile by executing:\n\n    $ bundle add isorun\n\nIf bundler is not being used to manage dependencies, install the gem by\nexecuting:\n\n    $ gem install isorun\n\n## Development\n\nAfter checking out the repo, run `bin/setup` to install dependencies. Then, run\n`rake spec` to run the tests. You can also run `bin/console` for an interactive\nprompt that will allow you to experiment.\n\nTo install this gem onto your local machine, run `bundle exec rake install`. To\nrelease a new version, update the version number in `version.rb`, and then run\n`bundle exec rake release`, which will create a git tag for the version, push\ngit commits and the created tag, and push the `.gem` file to\n[rubygems.org](https://rubygems.org).\n\n### Examples\n\nWhen running examples, make sure you are on the exact same Ruby version that you\nused to build `isorun` with `rake compile`. If you are on a different Ruby\nversion you might get weird segfaults, encoding issues, etc. that are impossible\nto debug.\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at\nhttps://github.com/eliias/isorun.\n\n## License\n\nThe gem is available as open source under the terms of the\n[MIT License](https://opensource.org/licenses/MIT).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feliias%2Fisorun","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feliias%2Fisorun","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feliias%2Fisorun/lists"}