vjsrouter
Version:
A modern, file-system based router for vanilla JavaScript with SSR support.
142 lines (105 loc) • 4.41 kB
Markdown
# vjsrouter.js
**vjsrouter.js** is a simple, modern, and powerful file-system-based router for creating Single Page Applications (SPAs) with vanilla JavaScript. It brings the intuitive "pages" directory convention from popular frameworks like Next.js to the world of vanilla JS, with zero configuration required.
Created by **ctrotech**, this library is designed to be lightweight, fast, and incredibly easy to use.
---
## Core Features
- **File-System Routing:** Automatically generate routes from your file structure. `pages/about.js` becomes the `/about` route.
- **Dynamic Routes:** Create dynamic pages with ease. `pages/users/[id].js` handles URLs like `/users/123`.
- **Zero Configuration:** No complex setup. Just create your files, run the build tool, and your app is ready.
- **Lightweight & Fast:** A tiny footprint with no external dependencies, ensuring your application loads quickly.
- **Modern Tooling:** Comes with a built-in CLI to generate the necessary route manifest.
- **History API:** Uses the standard browser History API for seamless navigation without page reloads.
---
## How It Works
`vjsrouter` works in two parts:
1. A **CLI tool** that you run during development. It scans your `/pages` directory and creates a `routes.json` file that maps your files to URL paths.
2. A lightweight **client-side library** that you include in your HTML. It reads the `routes.json` manifest and automatically handles rendering the correct page and intercepting navigation.
---
## Getting Started
Follow these steps to create your first `vjsrouter` application.
### Step 1: Project Setup
Create your project directory with the following structure:
```
/my-awesome-app/
├── /pages/
│ ├── index.js
│ └── about.js
│
└── index.html
```
### Step 2: Create Your Pages
A page is a JavaScript file in the `/pages` directory that exports a default function. This function must return a DOM element.
**`pages/index.js`**
```javascript
export default function HomePage() {
const element = document.createElement('div');
element.innerHTML = `
<h1>Welcome Home!</h1>
<p>This is the home page.</p>
<a href="/about">Go to About Page</a>
`;
return element;
}
```
**`pages/about.js`**
```javascript
export default function AboutPage() {
const element = document.createElement('div');
element.innerHTML = `
<h1>About Us</h1>
<p>This is a simple SPA built with vjsrouter.js!</p>
<a href="/">Go back home</a>
`;
return element;
}
```
### Step 3: Create the Host HTML File
Your `index.html` is the single entry point for the entire application. It needs a container element (e.g., `<div id="app">`) and a script tag pointing to the `vjsrouter` library.
**`index.html`**
```html
<html lang="en">
<head>
<meta charset="UTF-8">
<title>My vjsrouter App</title>
</head>
<body>
<!-- Your entire application will be rendered here -->
<div id="app"></div>
<!-- Include the vjsrouter library -->
<!-- NOTE: Update the path to where you host the file -->
<script src="/dist/vjsrouter.umd.js"></script>
</body>
</html>
```
### Step 4: Generate the Route Manifest
Now, you need to generate the `routes.json` file. If you installed `vjsrouter` locally in a project with a `package.json`, you can run the CLI tool.
First, install the tool (if you haven't already):
```bash
npm install vjsrouter --save-dev
```
Then, run the build command:
```bash
npx vjsrouter build
```
This will create a `routes.json` file in your project root. Your application is now ready! Open `index.html` in a browser (using a local server) to see it in action.
---
## Dynamic Routes
To create a dynamic route, use brackets `[]` in your filename.
**`pages/users/[id].js`**
```javascript
// This will handle routes like /users/alice, /users/123, etc.
export default function UserProfilePage(params) {
// The router passes the dynamic parts of the URL as an object.
const userId = params.id;
const element = document.createElement('div');
element.innerHTML = `
<h1>User Profile</h1>
<p>Viewing profile for user: <strong>${userId}</strong></p>
`;
return element;
}
```
Run `npx vjsrouter build` again to update your manifest, and you can now navigate to `/users/any-name`.
## License
[MIT](LICENSE) © ctrotech