server-side-rendering-ssr.md

Server Side Rendering (SSR)

To utilize HyperCloud's server side rendering, you need to define pages and components, and in a route, you can simply render the page by its name response.render('pageName'). Let's dive in.

---

Files Syntax

When defining pages or components, there's a syntax that you must follow in order for the renderer to detect and register your defined pages and components.

• Pages: *.page.js. For example: home.page.js.
• Components: *.comp.js or *.component.js. Example: header.comp.js or header.component.js.

---

Project Structure

To follow common practices, our project will look like this:

my-ssr-project/
├── src/
│   ├── assets/
│   │   ├── components/
│   │   │   ├── header/
│   │   │   │   ├── header.ejs              // Header component template
│   │   │   │   ├── header.comp.js          // Header component definition
│   │   │   │   ├── style.css               // Header component styles (optional)
│   │   │   │   └── script.js               // Header component scripts (optional)
│   │   │   ├── footer/
│   │   │   │   ├── footer.ejs              // Footer component template
│   │   │   │   ├── footer.component.js     // Footer component definition
│   │   │   │   ├── style.css               // Footer component styles (optional)
│   │   │   │   └── script.js               // Footer component scripts (optional)
│   │   ├── pages/
│   │   │   ├── home/
│   │   │   │   ├── home.ejs                // Home page template
│   │   │   │   ├── home.page.js            // Home page definition
│   │   │   │   ├── styles1.css             // Home page styles 1
│   │   │   │   ├── styles2.css             // Home page styles 2
│   │   │   │   ├── script1.js              // Home page script 1
│   │   │   │   └── script2.js              // Home page script 2
│   │   ├── global/
│   │   │   │   ├── global.css              // A global CSS file
│   │   │   │   └── site.js                 // A global JavaScript file
│   |
│   └── server.js

In this example, we need to create three files: header.comp.js and footer.component.js for the header and footer components, and home.page.js for the home page.

---

How it works

1- Defining Components & Pages

The first step is to define the components and pages.

Defining Components

To define a component, follow these steps:

1. Import the Component class from the package:

import { Component } from '@nasriya/hypercloud';

2. Create an instance of the component:

const comp = new Component('header');   // Where `header` is the component name

3. Set either a component template or a render handler.

// Set a templete
comp.template.path.set(path.join(import.meta.dirname, 'header.ejs'));

// Set a rendering handler
comp.onRender.set(locals => {
    return `
        <header>
            <img src="${locals.logo.src}">
            <nav>
                <ul>
                    ${locals.nav.map(nav => {
                        return `<a href="${nav.href ? nav.href : '#'}"><li>${nav.label}</li></a>`
                    })}
                </ul>
            </nav>
        </header>
    `
})

Notes:

• Only one method is required in order to render the component.
• If both the onRender handler and a template have been set, the template will be ignored.
• The onRenderHandler should either return a string or Promise<string>.

4. Specify the paths of the assets (optional)

comp.stylesheet.set(path.join(import.meta.dirname, 'style.css'));
comp.script.set(path.join(import.meta.dirname, 'script.js'));

5. Export the component

export default comp;

Defining Pages

To define a page, follow these steps:

1. Import the Page class from the package:

import { Page } from '@nasriya/hypercloud';

2. Create an instance of the component:

const page = new Page('home');   // Where `home` is the page name

3. Specify the path of the component template

page.template.path.set(path.join(import.meta.dirname, 'home.ejs'));

4. Specify the paths of the assets (optional)

page.stylesheets.link.internal(path.join(import.meta.dirname, 'style1.css'));
page.stylesheets.link.internal(path.join(import.meta.dirname, 'style2.css'));

page.scripts.link.internal(path.join(import.meta.dirname, 'script1.js'));
page.scripts.link.internal(path.join(import.meta.dirname, 'script2.js'));

5. Export the page

export default page;

2- Register Assets

After creating the assets (pages and components), we need to register them on the server.

Registering Pages & Components

To register our pages and components, we tell the server where it can find them by providing the containing folder.

// Register the pages folder
server.rendering.pages.register(path.join(import.meta.dirname, './assets/pages'));

// Register the components folder
server.rendering.components.register(path.join(import.meta.dirname, './assets/components'));

Register Global Assets

Global assets are files that must be included in each and every page. This can save you lots of time and headache during development.

// Add global CSS
server.rendering.assets.stylesheets.link.internal(path.resolve(import.meta.dirname, 'global/global.css'));
server.rendering.assets.stylesheets.link.external('https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@24,400,0,0');

// Add global JavaScript
server.rendering.assets.scripts.link.internal(path.resolve(import.meta.dirname, 'global/site.js'));

Enable Caching

Enable caching allows HyperCloud to store your assets in memory (RAM), resulting in faster rendering since it doesn't need to read from storage each and every time a page or a component is needed.

To enable all assets:

server.rendering.cache.enableFor.everything();