Svelte on Rails

Seamless and robust Svelte in Rails integration.

By default, and when installed together with @hotwired/turbo-rails, it renders
svelte components on the first request server side («SSR») and for subsequent
requests it provides a empty tag which is mounted on the frontend
by the associated npm package @csedl/svelte-on-rails.

This way svelte works perfectly together with turbo. You will never notice
this unpleasant «blink» on the frontend and is optimised for maximum
performance. SSR compilation is done by vite.

All this is developed on Rails-7 together with vite_rails.

Thanks to shakacode
and ElMassimo for inspiring and helping me with their gems.

STATUS This gem is in early development but ready to use for curious developers.
It has a 100% test coverage, all tests pass when triggered indiviudally.
Running all tests together fails for some tests (ToDo).

If you have issues, please open one and contributors are welcome!

Requirements

  • actual node installed on the server
  • tested on ruby 3.2.2 and rails 7.1
  • vite_rails (the installer will install it by option –full or –vite)
  • svelte v5 (see: how to install svelte on rails/vite)
  • turbo (recommended / how to install turbo on rails)
  • if you use special packages (like pug) that requires commonjs, you may need
  • npm on latest versions

Installation from cero

together with haml, vite, svelte and turbo

If you want to start from a new rails app, follow theese tutorials

rails new my-test-app --skip-javascript

within the app add the gem

bundle add svelte-on-rails

and run the installer

rails g svelte_on_rails:install --full

The --full contains:

  • --vite
    • adds vite_rails gem and running the installer
  • --haml
    • adds the gem and converts existing views
  • svelte_on_rails
    • This is not a option, this is always done: Adds a config file and installs @csedl/svelte-on-rails by npm
  • --turbo
    • installs @hotwired/turbo-rails and adds import statement to application.js
  • --svelte
    • adds or updates svelte
  • --hello-world
    • adds a hello world component

You can also use the options you want instead of using --full.
And there is the option --force that would not ask you whether it should overwrite existing files, for automated processes like testing.

This means, if you want all, except haml, you can run:

rails g svelte_on_rails:install --vite --turbo --svelte --hello-world --force

The installer is written carefully: It does not overwrite a file without asking.
It tells you all what he is doing.

At the end, you just have to (re-) start your server
and you will see a Svelte component.

Then, you can run

rails svelte_on_rails:remove_hello_world

and start coding.

Minimal Installation

For example, within a existing app, add the gem and run the installer without any options

rails g svelte_on_rails:install

that does:

  • creating a config file.
  • installs the npm package

please follow the instructions on @csedl/svelte-on-rails
for setup the workflow

Within the config file, there are mainly two important tags:

  • frontend_folder (relative to Rails.root)
  • components_folder (relative to frontend_folder)

Check if it all works

Server Side Rendering (SSR) is a parallel pipeline to client side rendering.
Both should return the same html. And your global styles should be applied same way
for both cases. For 95% of use cases this is the case.

For check the ssr pipeline you can pass the options ssr: true and hydrate: false
to the view helper. That Way you will see a dead html (no javascript is working).

For check the client side pipeline you can pass the option ssr: false and
hydrate: true to the view helper.

If both are looking similar, you are good to go.

Import statements

The most importand import statements that are served by this gem are included in the
hello world component and by that they are also within the testing scope. So you can
be sure that they are working. If importand statements are missing there, pelase
tell me.

Among others, working statements are:

  • import svg from '../example.svg?raw'
  • “ (svelte component with typescript syntax)
  • import { someFunction } from '../customJavascript.js';
  • import Child from './Child.svelte';

Precompile assets

Usual vite has a vite.config.ts file, that is used for the client side precompilation.

By running this installer it adds vite-ssr.config.ts and a npm runner so that you can do npm run build:ssr
which does the server side precompilation.

The same job is triggered alongside rails assets:precompile for production environments.

On development, when watch_changes is configured, the precompilation is triggered
after any *.svelte file within the configured components_folder changed.

Option ssr: :auto

ssr: :auto is the default option, as set on config file and can be overridden on the view helper.

Works with hotwired/turbo only

By passing the ssr: :auto option to the view helper,
it checks if the request is an initial request (request header X-Turbo-Request-ID is present):

On Initial-Request, it adds the attribute data-svelte-on-rails-initialize-action="hydrate" and
returns a server side rendered component that will be hydrated on the frontend by the npm package.

Otherwise it adds mount instead of hydrate, and renders a empty element, but provided with the
necessary attributes for the npm package.

More details to this point you can find on the npm package.

This works perfectly with hotwired/turbo because the javascript is only
loaded on very first load to the frontend, then the most work is done
in frontend and the server is relieved, except on initial request.
You will see no unpleasant «blink» on the page.

More rake tasks

This tasks are more for testing/playground purposes

rails svelte_on_rails:add_hello_world

rails svelte_on_rails:remove_hello_world

Contributors Guide

Contributors welcome!

After downloaded the gem, please run the task

rake svelte_on_rails:create_contributor_configs_file

and define a generated_test_app_folder_path (required) for apps, generated for the testings.

For development of the npm package @csedl/svelte-on-rails you can set the
local_npm_package_path (optional) and insert the path to the npm package on your local machine.
This will cause the installer, to install the npm package from a local path instead from the npm registry.

Tests are based on the included templates, like the hello world template and on the installer.

Installer tests starting with completely destroy the rails app within the generated_test_app_path,
generating a new rails app and running the installer and test by playwright if the components are working.

component tests only checking if a rails server is alive, and if not, install and run a rails app.
For this is the testing helper start_rails_server_unless_ping. This step may only be slow on the
first run, then it is fast. And on every repeating the test it always overwrites the components
with the components from the template by the testing helper install_hello_world(
['rails_vite_hello_world'],
app_root: generated_rails_app_root,
force: true,
silent: true
). At the end of the test it leaves the rails server running.

On that way a developer can just edit the templates and run a test and see always the refreshed
content on the browser and on the app within the generated_test_app_path.

NOTE: Theese tests are dependend on your environment, including the running ruby version!
I am working on rvm. If you work on a different environment, some (not many) changes may be necessary.
Thats your part :)

The current test cases including (among others):

create a completely new rails app, running the full installer and check if a hello World component is visible and javascript is working.
run assets:precompile within a rails app and check if the gem does its precompiling too.

Understanding the process

Why not client and server rendering in one process?

That was my idea! application.js which is the usual entry point for the client
side could live on the same assets and manifest like svelte components that are
compiled as chunks which each is its own entry point. This failed:

  • The vite-plugin-ruby did not support this: it constrained all to one entry point.
  • See how fat the vite-ssr.config.ts. For the client side this is not necessary.

At the end, I decided to split the process. But that is not the last decision.

Why not compiling server side purely by rollup?

Advantages would be much slimmer packages and faster compilation. On the first
step i did this and i backed up a working and tested code on the branch rollup-ssr.

I decided to use Vite to bring the client and server side rendering
closer together.

But this, too, is not the last decision.

For now we proceed with vite.

How does it work now?

Client side rendering is done by vite like usual.

Server side rendering is triggered, similar to vite_rails
on assets:precompile, and, if watch_changes is configured,
which is default for development, it is triggered
on every change of a *.svelte file within the configured components_folder.

On the server side only the *.svelte files are served. Theyr included
assets are linked to the client side assets folder, which is mapped by manifest.json.

Then, vite has two output folders: vite-dev for development and vite for production.
Within vite-ssr.config.ts, by the RAILS_ENV variable, is decided which one is used.

Licence

License is MIT