svelte-on-rails 6.0.1 → 7.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6a07c9c33f2ef2d71acbd9986cc841fada803a3692abec84719648e9d5d94c79
-  data.tar.gz: 8677455b7ef6137269451b12f9ed8350ff7ba842198f89e2864f7e6c5615a20e
+  metadata.gz: 6b61dc717ae11cdc216f2ce8a35239826d075e7fdb04559ac36f124d912ec593
+  data.tar.gz: 9abd85b4352eda996544904ce4df984773ebedbdf580a1c8d4aec59ab31c1481
 SHA512:
-  metadata.gz: 9a97fd9a881d5fa6b32f4faacf87ded1210939984e01274b4fb334b6f5444624ede7dac476e8fa2daa83f960d2f34ecacdc49cbebb4d0ed548c05f5425900622
-  data.tar.gz: 1caab439e622e43009cbc1ff2ee193fa35e0bbc0b63128ca0c917787536a01d3e92910f52e110fcec38d17533e6e7c7415d05ce87970d07fd9f45287801c8355
+  metadata.gz: 44935ca3cca431137508364778578b588fb0bf3339315823b975c98995640c46e8fd67fe05bc92a5cea7233a1ea1be2bcd540bc1a0955513e667f3bda283fe38
+  data.tar.gz: a778b7fbc71ad035c93e08cf99ba559c67fc18c8bd6cb717583e35a092c57cef8bc8a99c97ce26ba0fc98fdbe53d907d5ef67a45a8bff5458f48ca963c18c96d

data/README.md

@@ -11,27 +11,27 @@ Realizing [DHH's vision](https://rubyonrails.org/2021/12/15/Rails-7-fulfilling-a
 
 Svelte offers the simplest and most elegant soulution to building reactive, high-performance front-end components.
 
-- **Seamless Integration**
-  - Works flawlessly with Hotwired/Turbo
-  - Enhances Hotwire’s capabilities
-- **Developer-Friendly**
-  - Simple to learn, intuitive, and powerful
-  - Lightning-fast performance
 - **Compared to Single Page Apps (SPAs)**
   - Full-stack development delivers maximum value:
     - Unified testing from database to frontend
     - Single-source system delivery
   - For the most HTML Hotwired is enough
+- **Compared to integrated React or Vue**
+    - No virtual DOM, resulting in leaner packages and faster performance
+        - See Rich Harris’ [Rethinking Reactivity](https://svelte.dev/blog/svelte-3-rethinking-reactivity) (3:50–6:40) for a compelling comparison
+    - Easier to learn
+    - While React and Vue have larger communities, Svelte’s ecosystem is robust and growing, ideal for Rails integration
 - **Compared to Hotwired**
-  - Stimulus is not a tool for frontend-apps
+  - Stimulus is a initializer, but not a tool for frontend-apps!
   - Svelte eliminates redundant HTML initial state logic
   - Consolidates component logic into a single file
   - Offloads rendering to JavaScript by Frontend, Server side Rendering only where necessary, reducing server load
-- **Compared to React/Vue**
-  - No virtual DOM, resulting in leaner packages and faster performance
-    - See Rich Harris’ [Rethinking Reactivity](https://svelte.dev/blog/svelte-3-rethinking-reactivity) (3:50–6:40) for a compelling comparison
-  - Easier to learn
-  - While React and Vue have larger communities, Svelte’s ecosystem is robust and growing, ideal for Rails integration
+- **Seamless Integration**
+    - Works flawlessly with Hotwired/Turbo
+    - Enhances Hotwire’s capabilities
+- **Developer-Friendly**
+    - Simple to learn, intuitive, and powerful
+    - Lightning-fast performance
 
 Svelte empowers Rails’ full-stack vision with modern, efficient front-end integration.
 
@@ -46,112 +46,34 @@ Svelte empowers Rails’ full-stack vision with modern, efficient front-end inte
 
 see [issues](https://gitlab.com/sedl/svelte-on-rails/-/issues)
 
-# Svelte on Rails 👍
-
-Rock-solid and seamless integration of Svelte Components into Rails views, based on `vite_rails`.
-
-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](https://www.npmjs.com/package/@csedl/svelte-on-rails).
-
-This way svelte works perfectly together with turbo. You will never notice
-this unpleasant «blink» on the frontend while the whole process is maximum
-performance optimized.
+# Description 👍
 
-Thanks to [shakacode](https://github.com/shakacode/react_on_rails)
-and [ElMassimo](https://github.com/ElMassimo) for inspiring and helping me with their gems.
+Renders Svelte components server-side and, together with [@csedl/svelte-on-rails](https://www.npmjs.com/package/@csedl/svelte-on-rails),
+hydrates the component on the frontend.
 
-**STATUS:** This gem is in the early stages of development, but is ready for use.
-It has nearly 100% test coverage, with all tests passing. It has been in use since May/June 2025
-on the systems of my two biggest customers.
+Together with `turbo-rails` or `turbolinks`, if configured, it renders server-side only on initial requests
+and delivers a empty tag that will be rendered by frontend.
 
 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
-  - ruby 2.7.5 and rails 6.1
-  - vite@6 (v7 not supported, see issues)
-  - turbolinks and hotwired/turbo
+- tested on
+    - ruby 3.2.2 and rails 7.1
+    - ruby 2.7.5 and rails 6.1
+    - vite@6 (v7 not supported, see issues)
+    - turbolinks and hotwired/turbo
 - vite_rails (the installer will install it by option --full or --vite)
-- svelte@5, vite-plugin-svelte@5 (see: [how to install svelte on rails/vite](https://dev.to/chmich/setup-inertia-and-svelte-on-rails-7-3glk))
+- svelte@5, @sveltejs/vite-plugin-svelte@5 (see: [how to install svelte on rails/vite](https://dev.to/chmich/setup-inertia-and-svelte-on-rails-7-3glk))
 - turbo (recommended / [how to install turbo on rails](https://github.com/hotwired/turbo-rails?tab=readme-ov-file#installation))
-- if you use special packages (like pug) that requires commonjs, you may need
 - npm on latest versions
-- actual node installed. 
-  - if `nvm` is installed it gets the path to the node-binary from there.
-    - When `.nvmrc` is present on projects root, it is respected
-  - If node is not included on the PATH you can configure your node path by environment variable `SVELTE_ON_RAILS_NODE_BIN`
+- actual node installed.
+    - if `nvm` is installed it gets the path to the node-binary from there.
+        - When `.nvmrc` is present on projects root, it is respected
+    - If node is not included on the PATH you can configure your node path by environment variable `SVELTE_ON_RAILS_NODE_BIN`
 
-## Installation from cero ⚙️
 
-```bash
-rails new my-test-app --skip-javascript
-```
-
-within the app add the gem
-
-```bash
-bundle add svelte-on-rails
-```
-
-and run the installer
-
-```bash
-rails g svelte_on_rails:install --full
-```
-
-You have done it! 👍
-
-Start the server and you will see a svelte hello world component rendered on the browser.
-
-**Explanation:**
-
-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:
-
-```bash
-rails g svelte_on_rails:install --vite --turbo --svelte --hello-world
-```
-
-The installer is written carefully: It does not overwrite a file without asking
-and tells you all what he is doing.
-
-At the end, you just have to (re-) start your server
-and you will see a Svelte Hello World component.
-
-This hello world has a second page where the most common import statements are demonstrated,
-separated for server and client side rendering.
-
-Then, you can run
-
-```bash
-rails svelte_on_rails:remove_hello_world
-```
-
-and start coding.
-
-## Installation on a existing app ⚙️
+## Installation
 
 Required: `vite_rails` must be installed, it wants a `app/frontend` folder.
 
@@ -182,533 +104,12 @@ Restart the server, add a hello world component `app/frontend/javascript/HelloWo
 Add it to the view
 
 ```erb
-<%= svelte_component('HelloWorld', title: 'Hello World') %>
+<%= svelte_component('HelloWorld', {title: 'Hello World'}) %>
 ```
 
-
 And you should see "Svelte Hello World" on the browser! 👍  🤗
 
-**Explanation**
-
-this Minimal installer does:
-
-- add `app/frontend/initializers/svelte.js`
-- Adds a import statement for that initializer to `application.js`
-- add `app/frontend/ssr/ssr.js`
-- add `config/svelte_on_rails.yml`
-- add `vite-ssr.config.ts`
-- add command `npm run build:ssr` to package.json
-- installs or updates npm packages to the latest:
-  - `@csedl/svelte-on-rails`
-  - `typescript`
-  - `@types/node`
-
-**Troubleshooting**
-
-In the first step, the installer runs the backend parts that are unlikely to fail.
-Then it installs the npm packages that are more likely to fail because of dependencies. 
-If so, just check that all the
-packages are installed on the latest versions and you should be fine. 🤓
-
-The most importand rule is to firstly check all npm packages installed and passing before changing your view logik.
-
-## 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 normal use cases this is. 
-
-For check the **ssr pipeline** you can pass the options `ssr: true` and `hydrate: false`
-to the view helper. This way you will see a «dead» backend rendered HTML with no javascript applied.
-
-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. Then, remove theese options, the defaults are
-`ssr: :auto` and `hydrate: true`.
-
-### 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'`
-- `<script lang="ts">` (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.
-
-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 // configurable by `non_ssr_request_header`):
-
-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.
-
-**Turbolinks**
-
-If you are working on turbolinks, you can config the header or set something like 
- 
-```
-document.addEventListener('turbolinks:request-start', (event) => {
-    var xhr = event.data.xhr
-    xhr.setRequestHeader("X-Turbo-Request-ID", "any-content-for-skip-svelte-ssr")
-});
-```
-
-to your javascript file.
-
-
-**Tip: Performance optimisation for dropdowns**
-
-For example, with dropdowns, you will never see the unpleasant «blink» effect because
-the Svelte component is not visible for the first moment after rendering.
-Server-side rendering is unnecessary here. You can pass 'ssr: false' to the view helper.
-This relieves the server and reduces loading time.
-
-**Tip: Testing**
-
-Consider setting `ssr: false` for testing only for performance reasons.
-Yo can override this on a attribute on the view-helper for specific components.
-But, in normal cases it should not be neccessary testing ssr explicitly.
-
-## ActiveRecord helpers
-
-Adds the `#to_svelte` helper to your models, example: 
-
-```ruby
-@book.to_svelte(
-  :name,
-  :calculation_method,
-  author: [:name],
-  editions: [
-    :date, 
-    offset: 2, 
-    limit: 1
-  ]
-)
-```
-
-would result in something like this: 
-
-```ruby
-{
-  "values" => {
-    "name" => "Learning Ruby",
-    "calculation_method": "any-result",
-    "author" => {
-      "name" => "Michael Hartl"
-    },
-    "editions" => [
-      {
-        date: "2025-02-03"
-      }
-    ]
-  },
-  "book_labels" => {
-    "name" => "Name", # translated by human_attribute_name
-    "calculation_method" => "Calculation method",
-    "author" => "Author"
-  },
-  "author_labels": {
-    "name" => "Name" 
-  },
-  "edition_labels" => {
-    "date" => "Date"
-  }
-}
-```
-
-This should ease transferring data you need within the component mostly.
-
-The same method is applicable for:
-
-- The model itself
-  - It returns only the labels: Same result like above, but without the `values` key
-- `ActiveRecord::Relation`
-  - Same result like above, but `values` then is a Array.
-
-If a association returns a empty result, the labels are still calculated.
-
-`offset` and `limit` are reserved keys, so, columns with the same name would be ignored.
-
-**Caching:** 
-
-Caching Capability is not implemented on this method, you easily can wrap it by `Redis`
-
-If used on the `cached_svelte_component` view helper, 
-the component's attributes are used to generate a checksum, which serves as the 
-cache key for efficient storage and retrieval. So, this method is meant to 
-make it easier to exactly filter out only the information that is needed
-on the component.
-
-## Caching
-
-Caching only is relevant for `ssr`
-
-When using the `cached_svelte_component` helper you must have the `redis` gem installed.
-
-This caches on a key like `svelte-on-rails:development:SvelteOnRailsHelloWorld.svelte-1xq5tnu-User1:fscyhz-18bm76a` which includes:
-
-- Namespace, if configured, otherwise the default is gem-name and environment
-- component filename
-- checksum of the file-path
-- `cache_key` if given as argument to the view-helper
-  - can be a array of active-record objects or strings or a single element instead of a array
-- checksum of the last modification timestamp of the component (only when `watch_changes` is set to true)
-- checksum of the given attributes
-
-**Configuration**
-
-Like usually you can configure your cache store on your environment by something like:
-
-```ruby
-  config.cache_store = :redis_cache_store, { url: 'redis://localhost:6379/2',
-                                             expires_in: 90.minutes,
-                                             namespace: 'my-example-app' }
-```
-
-And you can override this by
-
-```yaml
-redis_cache_store:
-  expires_in: 2.hours
-```
-
-on the svelte-on-rails config file or pass the `expires_in` as argument to the view helper.
-
-**Check if it works**
-
-Pass `debug: true` to the helper and you will see on the logs how your configuration works.
-
-## ActionCable vs. TurboStream
-
-There are two ways that the server can talk to the client over Websocket:
-
-- **ActionCable** transmits directly to the frontends javascript
-- **TurboStreams** is a wrapper around ActionCable
-  - You always need a html part for communication by secured channels
-  - Makes sense when you want to transfer confidential data or separate onto privileged user channels
-  - Has [compatibility issues with Rails-UJS](https://github.com/hotwired/turbo-rails?tab=readme-ov-file#compatibility-with-rails-ujs)
-
-    
-## SvelteOnRails::ActionCable
-
-**Setup**
-
-Add `app/channels/svelte_on_rails_channel.rb`
-
-```ruby
-class SvelteOnRailsChannel < ApplicationCable::Channel
-  def subscribed
-    stream_from "svelte_on_rails_channel"
-  end
-
-  def unsubscribed
-    # Any cleanup needed when channel is unsubscribed
-  end
-end
-```
-
-config
-
-```yaml
-action_cable:
-  channel: "svelte_on_rails_channel"
-```
-
-javascript
-
-```shell
-npm i @rails/actioncable
-```
-
-Add to `application.js`
-
-```javascript
-import { createConsumer } from "@rails/actioncable"
-import { SvelteOnRails, dispatchSvelteStreamEvent, actionCableDebugLog } from '@csedl/svelte-on-rails'
-SvelteOnRails.debug = true
-
-const consumer = createConsumer()
-
-consumer.subscriptions.create("SvelteOnRailsChannel", {
-    connected() {
-        actionCableDebugLog("Connected to SvelteOnRailsChannel")
-    },
-    disconnected() {
-        actionCableDebugLog("Disconnected from SvelteOnRailsChannel")
-    },
-    received(data) {
-        actionCableDebugLog("Received:", data)
-        dispatchSvelteStreamEvent(data)
-    }
-})
-```
-
-**What dispatchSvelteStreamEvent does**
-
-- Without the attribute `component` given,
-  it searches for all elements with the class `svelte-component` and fires the event `channel-action`
-    - When `selector` is given, it searches for all matching elements within each component.
-    - The event can be overriden by the argument `event`
-
-**Usage**
-
-`app/frontend/javascript/components/folder/MyComponent.svelte`
-
-```sveltehtml
-<script>
-  import {addComponentStreamListener} from '@csedl/svelte-on-rails/src/componentStreamListener'
-
-  function handleCableEvent(event) {
-      console.log('Event received by Turbo Stream', event.detail)
-  }
-</script>
-<!--on ANY element:-->
-<h1 use:addComponentStreamListener={handleCableEvent}>Test TurboStreams Channel</h1>
-```
-
-The `addComponentStreamListener` adds the eventListener `stream-action` on the wrapping Element.
-The «wrapping Element» is the Element from the view helper `svelte_component` with the class `svelte-component`.
-
-Now you can dispatch events on the component by:
-
-```ruby
-SvelteOnRails::ActionCable.dispatch(
-  'folder/MyComponent',
-  { message: "greetings from Server: äöü🤣🌴🌍漢字" }
-)
-```
-
-And you will find the object, with the message key on the browser logs.
-
-Without any arguments, just by `SvelteOnRails::ActionCable.dispatch` it would fire the `stream-action` event on all components.
-
-The **#dispatch_by_selector** does not go over the component, it searches for any matching selector just
-on the whole `document` and fires the given event there.
-
-# SvelteOnRails::TurboStream
-
-**Setup**
-
-Please setup the `turbo-rails` gem and follow the chapter [Come alive with Turbo Streams](https://github.com/hotwired/turbo-rails?tab=readme-ov-file#come-alive-with-turbo-streams), which mainly is:
-
-```shell
-bundle add turbo-rails
-rails turbo:install
-```
-
-make sure that `import "@hotwired/turbo-rails"` is on your application.js and set the view helper
-`<%= turbo_stream_from 'authenticated' if current_user %>` to your view.
-
-If a channel (e.g.: `authenticated`) is active and you have an HTML element with a HTML-ID (e.g.: `svelte-on-rails-stream-actions-box`),
-you can test it by:
-
-```ruby
-     Turbo::StreamsChannel.send(
-        "broadcast_append_to",
-        'authenticated',
-        target: 'svelte-on-rails-stream-actions-box',
-        content: "<div>Turbo-Streams are working!</div>"
-      )
-```
-
-When this works you are good to go.
-
-**Configs**
-
-Check the regarding keys and their commends on the [config file](https://gitlab.com/sedl/svelte-on-rails/-/blob/main/templates/config_base/config/svelte_on_rails.yml?ref_type=heads).
-From there, you just need:
-
-```yaml
-turbo_stream:
-  target_html_id: 'svelte-on-rails-stream-actions-box'
-  channel: 'public'
-```
-
-**Minimal Usage Example**
-
-And call this by:
-
-```ruby
-    SvelteOnRails::TurboStream.dispatch
-```
-**What it does**
-
-- A Stimulus controller is pushed to all subscribers of the configured channel.
-    - You can override the channel name by passing `channel` to the method.
-
-**Usage Example, more detailed**
-
-If you want to fire a event on a specific element within the component, you do not need `addComponentStreamListener`. 
-Just do something like:
-
-```sveltehtml
-<script>
-    function logStreamMessage(event) {
-        console.log(event.detail.message)
-    }
-</script>
-<button class="counter-button" onclick="{logStreamMessage}">Show Contents</button>
-```
-
-within the svelte component.
-
-Then, call it by:
-
-```ruby
-      SvelteOnRails::TurboStream.dispatch(
-        channel: 'my-custom-stream',
-        component: '/javascript/components/TurboStreamsChannel',
-        selector: '.counter-button',
-        event: 'click',
-        event_detail: { message: "Greetings from Server: äöü🤣🌴🌍漢字" }
-      )
-```
-
-The **#dispatch_by_selector** does not go over the component, it searches for any matching selector just
-on the whole `document` and fires the given event there.
-
-## More rake tasks
-
-This tasks are more for testing/playground purposes
-
-```bash
-rails svelte_on_rails:add_hello_world
-```
-
-```bash
-rails svelte_on_rails:remove_hello_world
-```
-
-## Deploy
-
-For example, by deploying with capistrano, you may add a step like 
-
-```ruby
-before 'deploy:assets:precompile', 'deploy:npm:install'
-namespace :deploy do
-  namespace :npm do
-    desc 'Install Node.js dependencies'
-    task :install do
-      on roles(:app) do
-        within release_path do
-          execute :npm, 'install'
-        end
-      end
-    end
-  end
-end
-```
-
-to `deploy.rb` for making sure the ssr compilation is working.
-
-## Contributors Guide
-
-Contributors welcome!
-
-**Download the code and run the tests**
-
-Download the source code from the repository, and within the project folder run:
-
-```bash 
-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** (optional) please download the source code of the
-npm package and set `local_npm_package_path` on the config file to 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.
-
-Then run the tests and start contributing.
-
-**RUN THE FIRST TEST (!)**: Testing is complex here because of the design based on the installer test. 
-On Problems, i always run the `Installer > destroy and create rails app > FIRST TEST > [...] check if javascript works`.
-If there are problems, open the generated app on a IDE and check errors there.
-
-When this passes, all the others passing mostly. 
-
-At the end of the most tests it leaves the rails server running, so that you can see the result on `localhost:3000`.
-
-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` is. For the client side this is not necessary.
-
-At the end, I decided to split the process. For now it is cleaner. 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](https://gitlab.com/sedl/svelte-on-rails/-/blob/rollup-ssr/BRANCH_INFO.md?ref_type=heads).
-
-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](https://vite-ruby.netlify.app/guide/deployment.html)
-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
+Copyright © 2025-2028 sedlmair.ch. Distributed by [MIT License](https://svelte-on-rails-docs-51acfa.gitlab.io/license.html)

data/lib/generators/svelte_on_rails/install/install_generator.rb

@@ -141,7 +141,7 @@ module SvelteOnRails
       end
 
       def haml_and_convert
-        return unless options[:full] || options[:haml]
+        return unless options[:haml]
 
         puts '-' * 80
         puts ' ▶︎▶︎▶︎ INSTALLING Haml and converting existing .erb files to .haml'

data/lib/svelte_on_rails/active_record_extensions.rb

@@ -8,32 +8,33 @@ module SvelteOnRails
     # end
 
     # Returns a hash of attributes, methods, and associations formatted for Svelte components
-    def to_svelte(*attributes)
+    def to_svelte(*attributes, **associations)
       @to_svelte ||= begin
 
-                               cl = SvelteOnRails::Lib::SvelteAttributes
-                               cl.new.calculate_instance(self, attributes)
+                       cl = SvelteOnRails::Lib::SvelteAttributes
+                       r = cl.new.calculate_instance(self, attributes, associations)
+                       r.first.merge({self.class.to_s.underscore => r[1]})
 
-                             end
+                     end
     end
 
   end
 
   module ActiveRecordClassExtensions
-    def to_svelte(*attributes)
+    def to_svelte(*attributes, **associations)
       @to_svelte ||= begin
-                               cl = SvelteOnRails::Lib::SvelteAttributes
-                               cl.new.calculate_class(self, attributes)
-                             end
+                       cl = SvelteOnRails::Lib::SvelteAttributes
+                       cl.new.calculate_class(self, attributes, associations)
+                     end
     end
   end
 
   module ActiveRecordRelationExtensions
-    def to_svelte(*attributes)
+    def to_svelte(*attributes, **associations)
       @to_svelte ||= begin
-                               cl = SvelteOnRails::Lib::SvelteAttributes
-                               cl.new.calculate_relation(self, attributes)
-                             end
+                       cl = SvelteOnRails::Lib::SvelteAttributes
+                       cl.new.calculate_relation(self, attributes, associations)
+                     end
     end
   end
 

data/lib/svelte_on_rails/lib/to_svelte.rb

@@ -6,7 +6,7 @@ module SvelteOnRails
         @labels = {}
       end
 
-      def calculate_instance(record, attributes, call_stack: 0, offset: nil, limit: nil)
+      def calculate_instance(record, attributes, associations, call_stack: 0, offset: nil, limit: nil)
 
         next_stack = call_stack + 1
 
@@ -26,10 +26,10 @@ module SvelteOnRails
                     record
                   end
 
-          set_labels(record.first, attributes)
+          # set_labels(record.first, attributes)
 
           values = recs2.map do |rec|
-            calculate_instance(rec, attributes, call_stack: next_stack)
+            calculate_instance(rec, attributes, associations, call_stack: next_stack)
           end
 
         else
@@ -38,81 +38,82 @@ module SvelteOnRails
 
           values = {}
 
-          set_labels(record, attributes)
+          set_labels(record, attributes, associations)
 
           attributes.each do |attr|
+            raise 'Invalid attribute' unless [Symbol, String].include?(attr.class)
+            raise "[svelte-on-rails:to_svelte] #{record.class} does not respond to: #{attr}" unless record.respond_to?(attr)
+            _key = attr.to_s
 
-            if attr.is_a? Hash
-
-              # we have associations
-              attr.each do |key, value|
-                next if ['offset', 'limit'].include?(key.to_s)
-                raise "[svelte-on-rails:to_svelte] #{record.class} does not respond to: #{key}" unless record.respond_to?(key)
-                _offset, _limit, _value = extract_limit(value)
-
-                _key = key.to_s
-
-                # inspect association and set_labels
-
-                reflect = record.class.reflect_on_association(_key)
-                raise "invalid association: #{_key}" unless reflect
-                set_labels(reflect, value)
-
-                # values
+            values[_key] = record.send(_key)
+          end
 
-                recs = record.send(_key)
-                if recs.present?
-                  if recs.respond_to?(:each)
-                    values[_key] = calculate_instance(
-                      recs,
-                      value,
-                      call_stack: next_stack,
-                      offset: _offset,
-                      limit: _limit
-                    )
-                  else
-                    values[_key] = calculate_instance(
-                      recs,
-                      value,
-                      call_stack: next_stack
-                    )
-                  end
+          associations.each do |key, val|
+
+            # we have associations
+            val.each do |_key|
+              next if ['offset', 'limit'].include?(_key.to_s)
+              raise "[svelte-on-rails:to_svelte] #{record.class} does not respond to: #{key}" unless record.respond_to?(key)
+              _offset, _limit, _value = extract_limit(val)
+
+              _key = key.to_s
+
+              # inspect association and set_labels
+
+              reflect = record.class.reflect_on_association(_key)
+              raise "invalid association: #{_key}" unless reflect
+              set_labels(reflect, val)
+
+              # values
+
+              recs = record.send(_key)
+              if recs.present?
+                if recs.respond_to?(:each)
+                  values[_key] = calculate_instance(
+                    recs,
+                    val.reject{|v|v.is_a?(Hash)},
+                    {},
+                    call_stack: next_stack,
+                    offset: _offset,
+                    limit: _limit
+                  )
+                else
+                  values[_key] = calculate_instance(
+                    recs,
+                    val,
+                    {},
+                    call_stack: next_stack
+                  )
                 end
               end
-
-            else
-              # we have attributes
-              raise 'Invalid attribute' unless [Symbol, String].include?(attr.class)
-              raise "[svelte-on-rails:to_svelte] #{record.class} does not respond to: #{attr}" unless record.respond_to?(attr)
-              _key = attr.to_s
-
-              values[_key] = record.send(_key)
             end
-
           end
         end
 
         if call_stack >= 1
           values
         else
-          { 'values' => values }.merge(@labels)
+          [
+            @labels,
+            values
+          ]
         end
 
       end
 
-      def calculate_class(model, attributes, call_stack: 0)
+      def calculate_class(model, attributes, associations, call_stack: 0)
 
         next_stack = call_stack + 1
 
-        set_labels(model, attributes)
+        set_labels(model, attributes, associations)
 
-        hash = attributes.find { |element| element.is_a?(Hash) } || {}
-        hash.each do |key, value|
+        associations.each do |key, value|
           reflect = model.reflect_on_association(key.to_s)
           if reflect
             calculate_class(
               reflect,
               value,
+              {},
               call_stack: next_stack
             )
           end
@@ -123,14 +124,16 @@ module SvelteOnRails
         end
       end
 
-      def calculate_relation(relation, attributes, call_stack: 0)
+      def calculate_relation(relation, attributes, associations)
         set_labels(relation.klass, attributes)
-        values = relation.map do |rec|
-          calculate_instance(rec, attributes)['values']
+        r = relation.map do |rec|
+          calculate_instance(rec, attributes, associations, call_stack: 1)
         end
-        {
-          'values' => values
-        }.merge(@labels)
+
+        @labels.merge({
+                        relation.klass.to_s.underscore.pluralize => r
+                      })
+
       end
 
       private
@@ -164,11 +167,9 @@ module SvelteOnRails
         ]
       end
 
-      def set_labels(record, keys)
+      def set_labels(record, keys, assoc = {})
 
-        first_hash = keys.find { |element| element.is_a?(Hash) }
-        _keys = keys.reject { |element| element.is_a?(Hash) }
-        _keys += first_hash.keys if first_hash
+        _keys = keys.reject { |element| element.is_a?(Hash) } + assoc.keys
 
         _keys.each do |attr|
           unless attr.respond_to?(:each)

data/lib/svelte_on_rails/lib/view_helper_support.rb

@@ -3,19 +3,23 @@ module SvelteOnRails
 
   module Lib
     class ViewHelperSupport
-      attr_reader :filename, :helper_options, :html_options, :request, :conf
+      attr_reader :filename, :options, :html_options, :request, :conf
 
-      def initialize(file, args, request, caching = false)
+      def initialize(file, props, html_options, options, request, caching = false)
 
         @start_time = Time.now
         @conf = SvelteOnRails::Configuration.instance
         utils = SvelteOnRails::Lib::Utils
         utils.validate_filename(file) if @conf.watch_changes?
         @filename = (file.match(/\.svelte$/) ? file[0..-8] : file)
-        @args_checksum = Zlib.crc32(args.to_json).to_s(36)
-        @helper_options, @html_options, @svelte_props = split_props(
-          args,
-          %i[class id style],
+        @args_checksum = [
+          Zlib.crc32(props.to_json).to_s(36),
+          Zlib.crc32(options.to_json).to_s(36)
+        ].join('-')
+        @svelte_props = props ||= {}
+        @options, @html_options = prepare_options(
+          options,
+          html_options,
           %i[ssr hydrate debug cache_key expires_in]
         )
         @request = request
@@ -32,8 +36,8 @@ module SvelteOnRails
         if caching
           raise '[svelte-on-rails] Caching required but Redis is not defined' unless defined?(Redis)
         else
-          raise '[svelte-on-rails] :expires_in is not allowed for this helper' if @helper_options.key?(:expires_in)
-          raise '[svelte-on-rails] :cache_key is not allowed for this helper' if @helper_options.key?(:cache_key)
+          raise '[svelte-on-rails] :expires_in is not allowed for this helper' if @options.key?(:expires_in)
+          raise '[svelte-on-rails] :cache_key is not allowed for this helper' if @options.key?(:cache_key)
           return
         end
 
@@ -42,11 +46,11 @@ module SvelteOnRails
       end
 
       def debug?
-        @helper_options[:debug]
+        @options[:debug]
       end
 
       def redis_expiration_seconds
-        (conf.redis_cache_store[:expires_in] || @helper_options[:expires_in] || 1.hour).to_i
+        (conf.redis_cache_store[:expires_in] || @options[:expires_in] || 1.hour).to_i
       end
 
       def elapsed_milliseconds
@@ -89,8 +93,8 @@ module SvelteOnRails
       end
 
       def custom_cache_key
-        if @helper_options[:cache_key]
-          k2 = (@helper_options[:cache_key])
+        if @options[:cache_key]
+          k2 = (@options[:cache_key])
           keys = k2.is_a?(Array) ? k2 : [k2]
           keys.map do |k|
             if k.is_a?(ActiveRecord::Base)
@@ -109,13 +113,13 @@ module SvelteOnRails
       private
 
       def determine_ssr
-        _ssr = if @helper_options.key?(:ssr)
+        _ssr = if @options.key?(:ssr)
                  if @conf.watch_changes?
-                   unless [true, false, :auto].include?(@helper_options[:ssr])
+                   unless [true, false, :auto].include?(@options[:ssr])
                      raise "Only true, false, or :auto are allowed for the argument #ssr"
                    end
                  end
-                 @helper_options[:ssr]
+                 @options[:ssr]
                else
                  @conf.ssr
                end
@@ -147,32 +151,36 @@ module SvelteOnRails
 
       end
 
-      def split_props(args, html_options, helper_options)
-        prp = {}
-        hlp_opts = {}
-        ht_opts = {
-          data: {
-            svelte_component: "/#{conf.components_folder + filename}",
-            controller: 'svelte-on-rails',
+      def prepare_options(options, html_options, available_options)
+
+        # html options
+
+        ht_opts = html_options.dup.deep_merge(
+          {
+            data: {
+              svelte_component: "/#{conf.components_folder + filename}",
+              controller: 'svelte-on-rails'
+            }
           }
-        }
+        )
+        ht_opts[:class] = "#{ht_opts[:class]} svelte-component".strip
+        ht_opts[:data][:props] = @svelte_props.to_json
+        ht_opts[:data][:svelte_status] = 'do-not-hydrate-me' if options[:hydrate] == false
 
-        args.each do |k, v|
+        # render options
+
+        opts = {}
+        options.each do |k, v|
           _k = k.to_sym
-          if helper_options.include?(_k)
-            hlp_opts[_k] = v
-          elsif html_options.include?(_k)
-            ht_opts[_k] = v
+          if available_options.include?(_k)
+            opts[_k] = v
           else
-            prp[_k] = v
+            raise("Unknown option: #{k}")
           end
         end
 
-        ht_opts[:class] = "#{ht_opts[:class]} svelte-component".strip
-        ht_opts[:data][:props] = prp.to_json
-        ht_opts[:data][:svelte_status] = 'do-not-hydrate-me' if hlp_opts[:hydrate] == false
-
-        [hlp_opts, ht_opts, prp]
+        
+        [opts, ht_opts]
       end
 
     end

data/lib/svelte_on_rails/view_helpers.rb

@@ -2,11 +2,11 @@
 module SvelteOnRails
   module ViewHelpers
 
-    def svelte_component(filename, props = {})
+    def svelte_component(path, props = {}, html: {}, options: {})
 
-      support = SvelteOnRails::Lib::ViewHelperSupport.new(filename, props, request, false)
+      support = SvelteOnRails::Lib::ViewHelperSupport.new(path, props, html, options, request, false)
 
-      support.debug_log("Rendering component: #{filename}")
+      support.debug_log("Rendering component: #{path}")
       log_message = '?'
 
       log_message = "Rendered #{support.filename}.svelte #{'as empty element that will be mounted on the client side' unless support.ssr?}"
@@ -18,9 +18,9 @@ module SvelteOnRails
 
     end
 
-    def cached_svelte_component(filename, props = {})
+    def cached_svelte_component(path, props = {}, html: {}, options: {})
 
-      support = SvelteOnRails::Lib::ViewHelperSupport.new(filename, props, request, true)
+      support = SvelteOnRails::Lib::ViewHelperSupport.new(path, props, html, options, request, true)
 
       log_message = '?'
       redis = support.conf.redis_instance

data/templates/all_features_test/app/views/svelte_on_rails_hello_world/backend_frontend_rendered.html.erb

@@ -23,7 +23,7 @@
 <h3>Always rendered server side</h3>
 <div class="ssr-only">
   <% components.each do |component| %>
-    <%= svelte_component(component, ssr: true, hydrate: false, title: component) %>
+    <%= svelte_component(component, {title: component}, options: {ssr: true, hydrate: false}) %>
   <% end %>
 </div>
 
@@ -32,6 +32,6 @@
 <p>Here you will see a unpleasant «blink» on the initial request.</p>
 <div class="client-only">
   <% components.each do |component| %>
-    <%= svelte_component(component, ssr: false, hydrate: true, title: component) %>
+    <%= svelte_component(component, {title: component}, options: {ssr: false, hydrate: true}) %>
   <% end %>
 </div>

data/templates/all_features_test/app/views/svelte_on_rails_hello_world/index.html.erb

@@ -6,4 +6,4 @@
 
 <h1>Svelte is here</h1>
 
-<%= svelte_component "SvelteOnRailsHelloWorld", items: ['attributes', 'are', 'parsed'] %>
+<%= svelte_component "SvelteOnRailsHelloWorld", { items: ['attributes', 'are', 'parsed'] } %>

data/templates/all_features_test/app/views/svelte_on_rails_hello_world/ssr_auto_rendered.html.erb

@@ -20,7 +20,7 @@
 <h3>Rendered server side only on initial request</h3>
 <div class="ssr-auto">
   <% components.each do |component| %>
-    <%= svelte_component(component, title: component) %>
+    <%= svelte_component(component, { title: component }) %>
   <% end %>
 </div>
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: svelte-on-rails
 version: !ruby/object:Gem::Version
-  version: 6.0.1
+  version: 7.0.1
 platform: ruby
 authors:
 - Christian Sedlmair
@@ -78,13 +78,13 @@ files:
 - templates/config_base/app/frontend/ssr/ssr.js
 - templates/config_base/config/svelte_on_rails.yml
 - templates/config_base/vite-ssr.config.ts
-homepage: https://gitlab.com/sedl/svelte-on-rails
+homepage: https://svelte-on-rails-docs-51acfa.gitlab.io/
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://gitlab.com/sedl/svelte-on-rails
-  source_code_uri: https://gitlab.com/sedl/svelte-on-rails
-  changelog_uri: https://gitlab.com/sedl/svelte-on-rails
+  homepage_uri: https://svelte-on-rails-docs-51acfa.gitlab.io/
+  source_code_uri: https://svelte-on-rails-docs-51acfa.gitlab.io/
+  changelog_uri: https://svelte-on-rails-docs-51acfa.gitlab.io/
   post_install: ruby -r svelte_on_rails/install -e 'SvelteOnRails::Install.run'
 rdoc_options: []
 require_paths: