Roselt.js is a vanilla JavaScript framework for building routed web apps with real HTML, reusable components, and file-based organization.
- File-based pages: Map routes directly to
pages/files, with optional same-name JavaScript and CSS sidecars. - Shell components: Keep headers, sidebars, footers, and shared UI mounted with regular components placed outside the routed page root.
- Platform-first runtime: Use HTML, CSS, custom elements, and the browser Navigation API instead of a heavyweight client runtime.
Learn more at www.roseltjs.org.
Roselt.js is designed for gradual adoption, so you can start with the workflow that matches your project:
- Scaffold a new app with
npm create roselt@latest my-app - Install the package into an existing setup with
npm install roselt-js - Use the prebuilt browser global from
dist/roselt.js
The recommended way to start a new project is:
npm create roselt@latest my-app
cd my-app
npm install
npm startOlder guides may still reference npm create roselt-js@latest my-app. That legacy alias is still published for backward compatibility, but npm create roselt@latest my-app is the current recommended command.
If you already created or cloned a fresh repository, you can scaffold directly into that repo root:
npm create roselt@latest .
npm install
npm startThat works when the directory only contains repo bootstrap files such as .git, .github, .gitignore, README*, or LICENSE*.
If you want the CLI directly, this works too:
npx roselt create my-appGenerated apps include a starter shell, a home route, a 404 route, and a local development server powered by roselt serve.
You can find the Roselt.js documentation on the website.
Start with Getting Started for a quick overview.
The documentation is divided into several sections:
- Getting Started
- Installation
- Project Structure
- Routing and Navigation
- Pages
- Shell Components
- Components
- Metadata and SEO
- API Reference
- FAQ
Here is the smallest Roselt.js app shape:
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>My Roselt App</title>
</head>
<body>
<site-header></site-header>
<main>
<roselt page="home" navigate></roselt>
</main>
<site-footer></site-footer>
<script src="https://cdn.jsdelivr.net/gh/ShaunRoselt/Roselt.js@main/dist/roselt.js"></script>
<script>
Roselt.start();
</script>
</body>
</html>Then create the first routed page:
<!-- pages/home.html -->
<section>
<h1>Home</h1>
<p>Roselt.js rendered this page from pages/home.html.</p>
<a href="?page=about">About</a>
</section>Then add the page it links to:
<!-- pages/about.html -->
<section>
<h1>About</h1>
<p>This page was rendered from pages/about.html.</p>
<a href="?page=home">Back home</a>
</section>For the default query router, a normal anchor such as <a href="?page=about">About</a> is enough to move between pages.
Shared shell UI is just another component file:
// components/site-header.js
Roselt.defineComponent(function () {
this.shadow = false;
this.render = () => `
<header>
<a href="?page=home">My app</a>
</header>
`;
});Shadow DOM is the default for lightweight components. Set this.shadow = false in a function definition, or shadow: false in an object definition, when the component should render into light DOM.
If you want to trigger navigation from JavaScript instead, Roselt also exposes:
Roselt.navigate("about");Most Roselt.js apps follow this structure:
index.html
pages/
home.html
home.js
home.css
docs/getting-started.html
components/
site-header.js
site-footer.js
ui-button.js
The default start path requires a roselt[page] element marked with navigate. If a document contains multiple roselt[page] elements, Roselt uses the one marked with navigate as the routed page root.
This repository includes working examples you can inspect directly:
examples/starter-app/is the official starter template used bynpm create roseltpackages/create-roselt/contains thenpm createentry pointpackages/create-roselt-js/keeps the legacynpm create roselt-jsalias working for existing guides and projects
The main purpose of this repository is to keep evolving Roselt.js as a small, platform-first app framework for modern browsers.
To work on the repository locally:
npm install
npm run build
npm run check
npm run serveThen open /docs/ locally for the public documentation site, or inspect the example apps under /examples/.
Roselt ships ES2022 output and currently targets the latest browsers with Navigation API support.
Roselt.js is MIT licensed.