svelte-on-rails 0.0.44 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e29d2736242589c4733b2fff2bd590cce4eff354ae529d049fe4a18f05c464a6
-  data.tar.gz: 79fa789cd334dc3fdd248a53156d4845fe893b089147dd91a559b0618654fb12
+  metadata.gz: af9b4125161ea52c5785989db9e7f4b250a4bbe993f49264403680c5aa5467fb
+  data.tar.gz: 1d21a733aa52d57f892159baeb88c162cb78f46fca648dd2f31b45e3db8819e0
 SHA512:
-  metadata.gz: e4cac68c628036a6bf53cae04e76523a1ee6ee91d645634b00097b3df8cd1b32c4b6b4d72fa8ede06542101922d9977a6546c86862ac013c97bc6625cb256e35
-  data.tar.gz: 20667b507cbdb4dba14e9a00b74ce780ba05bd169e888d73b0d292cb997294e6665050b9a76e248efd1a477cb4e83cb46783a04193bc5e15d4102a0e454a4cfb
+  metadata.gz: 72c0797453be3020409b6e28f5b7f472e8e0c1a22e010c401925ad2a81ac360c522612a7e52bac3d7a8da5a4c51f62668a68d46a33b3a955ed9e072366a567fd
+  data.tar.gz: 7f377d2c359daa8a9a2e18cd7c147187dd4249bbd0a8b5987f0feddb4a7b72020bc49591e04502055e4a7223e78e05b8e832c21c345dc93ac1d943440587dfc0

data/README.md

@@ -3,18 +3,22 @@
 Seamless and robust Svelte in Rails integration.
 
 By default, and when installed together with `@hotwired/turbo-rails`, it renders
-svelte components on first request server side («SSR») and for subsequent
-requests it provides a empty tag that will be mounted on the frontend by the associated npm package [@csedl/svelte-on-rails](https://www.npmjs.com/package/@csedl/svelte-on-rails) on the frontend.
+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 and it is maximum performance
-optimized. SSR compilation is handled by vite.
+this unpleasant «blink» on the frontend and is optimised for maximum 
+performance. SSR compilation is done by vite.
 
-
-This all is developed on Rails-7 together with `vite_rails`.
+All this is developed on Rails-7 together with `vite_rails`.
 
 Thanks to [shakacode](https://github.com/shakacode/react_on_rails)
-and [ElMassimo](https://github.com/ElMassimo) because they all helped me with theyr gems.
+and [ElMassimo](https://github.com/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. 
+It is not yet implemented on my customer projects, but this will follow soon.
 
 If you have issues, please open one and contributors are welcome!
 
@@ -30,9 +34,7 @@ If you have issues, please open one and contributors are welcome!
 
 ## Installation from cero
 
-together with haml, vite, svelte and turbo
-
-If you want to start from a new rails app, follow theese tutorials
+With haml, vite, svelte and turbo:
 
 ```bash
 rails new my-test-app --skip-javascript
@@ -71,14 +73,17 @@ And there is the option `--force` that would not ask you whether it should overw
 This means, if you want all, except haml, you can run:
 
 ```bash
-rails g svelte_on_rails:install --vite --turbo --svelte --hello-world --force
+rails g svelte_on_rails:install --vite --turbo --svelte --hello-world
 ```
 
-The installer is written carefully: It does not overwrite a file without asking.
-It tells you all what he is doing.
+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 component.
+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
 
@@ -111,34 +116,27 @@ Within the config file, there are mainly two important tags:
 
 ## Check if it all works
 
-Add a controller and a view with the helper `= svelte_component('HelloWorld', items: ['item1', 'item2'])`.
-On loading you will see
-
-- Rendered HelloWorld.svelte server-side: 0.075ms
+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. 
 
-On the rails console and you will see «Greetings from svelte»
-on your view with a styled «Increment» button.
-Styles you find within the svelte component.
-Click this button and see that the component is alive.
+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» html (no javascript is working).
 
-On [@csedl/svelte-on-rails](https://www.npmjs.com/package/@csedl/svelte-on-rails)
-are details how the frontend part is working.
+For check the **client side pipeline** you can pass the option `ssr: false` and
+`hydrate: true` to the view helper.
 
-Without the npm package installed,
-or by passing `ssr: true` and `hydrate: false` to the view helper,
-you would see the same html, and the styled button,
-but the increment button would not work.
-
-I inserted very detailed error messages on rails and on the
-npm package, for making sure that thisk setup  is working.
-So please check the logs on your browser.
+If both are looking similar, you are good to go. Then, remove theese options, the defaults are
+`ssr: :auto` and `hydrate: true`.
 
 ### Import statements
 
-For check which statements are working and actively tested, please check the
-[components folder](https://gitlab.com/sedl/svelte-on-rails/-/tree/main/spec/rails-vite-test-app/app/frontend/javascript/components?ref_type=heads) within the gem specs.
+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 there are
+Among others, working statements are:
 
 - `import svg from '../example.svg?raw'`
 - `<script lang="ts">` (svelte component with typescript syntax)
@@ -149,7 +147,7 @@ Among others there are
 
 Usual vite has a `vite.config.ts` file, that is used for the client side precompilation.
 
-By running this installer it adds a npm runner so that you can do `npm run build:ssr`
+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.
@@ -179,33 +177,6 @@ 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.
 
-## Styles
-
-For 99% of use cases you can just skip this chapter.
-
-You can simply work with global styles as well as styles within the svelte component.
-
-A server-side rendered svelte component has 2 states:
-
-#### Before hydration
-
-- The `svelte_component` view helper renders the styles contained within the component
-  into a style tag within the component's wrapper element. This has to be done this way because of Turbo.
-- In very, very rare cases, global styles are not applied in the same way as after hydration.
-
-#### After hydration
-
-- Svelte adds a style tag inside the header
-- Svelte renders the component again, which removes the style tag inside the component wrapper.
-
-#### If you notice a "blink"
-
-For the app to look stable, both states must appear in the same way.
-Normally this is the case. But if there are problems,
-or you want to see the state before hydration, for development purposes, you can pass
-the `hydrate: false` option to the view helper,
-and no hydration will happen for this component.
-
 ## More rake tasks
 
 This tasks are more for testing/playground purposes
@@ -222,19 +193,28 @@ rails svelte_on_rails:remove_hello_world
 
 Contributors welcome!
 
-After downloaded the gem, please run the task
+**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** you can set the
-`local_npm_package_path` (optional) and insert the path to the npm package on your local machine.
+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` and set 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.
+
 Tests are based on the included templates, like the `hello world template` and on the installer.
 
+Here I learned how to write tests! Testing installers is heavy, you will read about it in the
+test_helpers. But I have done my best to give all the code a clear structure.
+I hope you like it, and improvements are welcome.
+
 **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.
 
@@ -260,6 +240,47 @@ 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](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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: svelte-on-rails
 version: !ruby/object:Gem::Version
-  version: 0.0.44
+  version: 1.0.0
 platform: ruby
 authors:
 - Christian Sedlmair