Skip to content

A JavaScript library for building server side rendered (SSR) user interfaces without JavaScript.

Notifications You must be signed in to change notification settings

litvinav/vscript

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

5 Commits
 
 
 
 
 
 
 
 
 
 

Repository files navigation

VSCRIPT

A JavaScript library for building server side rendered (SSR) user interfaces. This library aims to be fast, minimal and language agnostic unlocking Island Architecture (Partial Hydration) with minimal JavaScript and code duplication.

It is best paired with a templating engine on the backend like text/template for Go or Tera for Rust. VSCRIPT will not protect you from XSS and expects HTML to be loaded from trusted sources without or sanitized user inputs.

You probably want to minimize and compress the modules used with your code.

Minimal example

The following shows a minimal VSCRIPT usage to demonstrate its purpose.

First download the landing page for the example:

wget https://raw.githubusercontent.com/litvinav/VSCRIPT/main/example/index.html

Second the partial.html, with injectable HTML provided or generated by the server:

wget https://raw.githubusercontent.com/litvinav/VSCRIPT/main/example/partial.html

This will allow Partial Hydration of some sections of your page.

And third, the page.html, which is similar to second file. It provides the hosted or generated HTML but expects the full body content and will route to this body via a anchor element:

wget https://raw.githubusercontent.com/litvinav/VSCRIPT/main/example/page.html

This will allow Partial Hydration of whole pages via links.

And finally vscript itself:

wget https://raw.githubusercontent.com/litvinav/VSCRIPT/main/vscript.js

The content of your folder should look like this:

.
├── index.html
├── page.html
├── vscript.js
└── partial.html

Now launch a server with python3 -m http.server and visit: http://localhost:8000/

How to use

State management

HTML tag description
v-data Create a global state to be used with VSCRIPT.
v-text Dynamic inner text from a JavaScript syntaxed output. Access to VSCRIPT state possible,
v-show Evaluated syntax will add display:none to the annotated element, if the provided JavaScript chunk returns true.
<html>
  <head>
    <script src="/vscript.min.js"></script>
  <head>
  <body>
    <section v-data="{ show: true, data: 'click the button to show/hide this text' }">
      <p v-show="show" v-text="data"></p>
      <button @click="show=!show">click me</button>
    </section>
  </body>
</html>

Injection

Add one of the following functions to your input or mouse events in order to load server side rendered HTML.

inject

HTML tag fallback description
@click.inject current window location This is where your HTML is loaded from. You can leave this attribute out and call the same URL. VSCRIPT will send a "V-Request: true" header for you in order to differentiate between a user visiting the page or a VSCRIPT injection.
v-target source of the event This is ether a HTML element identified by the targeted id or the source of the event. The target will be replaced by the response.
v-callback none Executes the provided JavaScript after the injection. Useful to hydrate the UI with clients data.
<html>
  <head>
    <script src="/vscript.min.js"></script>
  <head>
  <body>
    <button @click.inject="/partial.html" v-target="example">mount server side HTML</button>
    <section id="example"> <!-- replace this element --> </section>
  </body>
</html>

eject

HTML tag fallback description
@click.eject none Unmounts the event source or the targeted element from the DOM. No attribute value required.
v-target source of the event Ejects the content of the targeted element or the source as fallback and keeps only the HTML element and its id.
<html>
  <head>
    <script src="/vscript.min.js"></script>
  <head>
  <body>
    <button @click.eject v-target="example">unmount the targeted element</button>
    <section id="example"> <!-- removes inner content --> </section>
  </body>
</html>

Routing (boosting)

The routing layer will inject SSR chunks into the body element instead opening links in the current browser page. It is expected that you handle the v-request header on the server side and only render the body on v-request: true. If a request is send to the server without the v-request: true header, the request was not initiated by VSCRIPT and the browser expects the full page.

Also you should respond with a adequate caching header, depending on the duration of the client session browsing your website or web app. On cache hit VSCRIPT will inject the content of the previous response, skipping concurrent request to the same URL.

<html>
  <head>
    <script src="/vscript.min.js"></script>
  <head>
  <body>
    <!-- onclick client-side browsing to the href page and VSCRIPT injection -->
    <a @boost href="/page.html">link</a>
  </body>
</html>

About

A JavaScript library for building server side rendered (SSR) user interfaces without JavaScript.

Topics

Resources

Stars

Watchers

Forks