Ramidus NPM | npm.io

Ramidus

Ramidus is a Single Page Application (SPA) template built for custom elements, bringing many of the benefits of frameworks like Next or Nuxt to vanilla sites. Unlike those frameworks, you're not locked into one way of doing things: all of the code is included in your project, and you are free to modify it however you wish.

Features

Instant SPA page loading using the <app-root> and <app-link> elements.
Pre-load high-profile pages after the first page loads.
Share templates between pages using the <app-layout> element.
Easily embed markdown and syntax-highlighted files using the <mark-down> element.
Familiar conventions, similar to Next or Nuxt.
No hidden code: customize anything exactly the way you like it.

Getting Started

Setup is easy and no tooling is required. You can scaffold your project using npx or simply download this zip file.

npx ramidus@latest && npm run dev

Project Structure

Global content like components, assets, layouts and your site's head are contained in the "@" folder. This naming convention keeps the folder first alphabetically so it's always easy to find.

@
- assets
- components
- css
- build.js
- main.js
- head.json
docs
- index.html
index.html

Pages

Each page must have its own folder containing an index.html file, i.e. /about/index.html. Shared page elements are contained in the <app-layout> custom element.

Every page must include the following markup.

<body>
  <app-layout>
    <!-- Page Content -->
  </app-layout>
  <script src="/@/main.js" type="module"></script>
</body>

You can include markdown on any page using the <mark-down> custom element.

<mark-down src="/README.md"></mark-down>

Linking to Pages

To enable SPA-style routing, just wrap links in an <app-link> element. You can set preload="true" if you want the linked page to be pre-fetched as soon as the current page loads.

<app-link><a href="/about">About Us</a></app-link>

Layout

A layout is a custom element containing the site's shared markup. Layouts should include the <app-root> element with a nested <slot> to load the page's content. Here is the default layout included with Ramidus.

<!-- /@/app-layout.js -->
<app-nav></app-nav>

<main>
  <app-root>
    <slot></slot>
  </app-root>
</main>

<app-footer></app-footer>

The layout can be updated dynamically based on the page you are on. When each page loads, the path and current page nesting level are added as classes to the <app-layout> element, i.e. class="about level-2". You can use these classes to style elements inside the layout element. In the template above, if you wanted to hide the footer on pages under the "about" path, you could use the following css in your layout.

:host(.about) app-footer {
  display: none;
}

Components

Global components go in the /@/components folder and are registered in /@/main.js. Ramidus's core components are built with Ardi, but you can use any custom element framework you like (or none).

Deployment

No build step is required to deploy this site: you can copy this project to a simple server and it will run just fine. You will probably still want to run npm run build before you deploy though.

Benefits of Building

The site's head is included with each page instead of being generated when the first page loads.
Building will make it so the first page visited fades in after the globally-registered components have loaded, preventing CLS.