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.
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.htmlSecond the partial.html, with injectable HTML provided or generated by the server:
wget https://raw.githubusercontent.com/litvinav/VSCRIPT/main/example/partial.htmlThis 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.htmlThis will allow Partial Hydration of whole pages via links.
And finally vscript itself:
wget https://raw.githubusercontent.com/litvinav/VSCRIPT/main/vscript.jsThe 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/
| 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>Add one of the following functions to your input or mouse events in order to load server side rendered HTML.
| 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>| 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>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>