@muryp/router-dom
Version:
spa in astro or native/vanilla js
105 lines (73 loc) • 4 kB
Markdown
## Introducing @muryp/router-dom - A Router and SPA Library for Astro JS
[](https://www.npmjs.com/package/@muryp/router-dom)
[](https://www.npmjs.com/package/@muryp/router-dom)
[](https://github.com/muryp/router-dom/blob/main/LICENSE)
A lightweight and powerful routing library designed for Vanilla JS and Astro JS projects. Build Single Page Applications (SPAs) efficiently with modern features like **Nested Layouts**, **Recursive Async Middleware**, and **Automated Path Resolution**.
### ✨ Key Features
- **Router & SPA Support:** Smooth navigation and dynamic content loading without page refreshes.
- **Nested Layouts:** Wrap components with multiple layers of layouts (e.g., Global Layout > Blog Sidebar > Post Content).
- **Sequential Async Middleware:** Execute security or data checks layer-by-layer from root to leaf before rendering.
- **Path Auto-Converter:** Write flat paths like `blog/post/:id`; the router automatically transforms them into a nested object tree.
- **Base URL Support:** Perfectly handles sub-directory deployments (e.g., `domain.com/foo/`).
### 🚀 Usage
Simply define your routes and execute the router. It is designed to be triggered on initial load and every URL change.
```typescript
import router from './src/example/router';
// this will be render after load if isFirstRender true
router();
```
### 🏗 Core Concepts
#### 1. Nested Layouts
Layouts are functions that receive `context` and `children`. Content from child routes is injected into the `${children}` placeholder.
```typescript
// Example Layout
const MainLayout = (ctx, children) => `
<nav>Navbar</nav>
<main>${children}</main> <footer>Footer</footer>
`;
```
#### 2. Async Middleware Chain
Middlewares are executed sequentially. If any middleware returns `false` (or a Promise resolving to `false`), the rendering process stops, and the user is redirected to the Home page.
```typescript
{
'/admin': {
middleware: async (ctx) => {
const session = await checkSession();
return session.isValid; // If false, the sub-routes below won't render
},
'/settings': {
component: AdminSettings
}
}
}
```
### 🔍 Full Example
For a complete implementation including:
✅ **@404** and **@home** handling
✅ **Dynamic Parameters** (`/:id`)
✅ **Nested Layouts** (MainBlog & BlogPost)
✅ **Script Execution** post-rendering
Please refer directly to the example file:
👉 **[`src/example/router.ts`](https://www.google.com/search?q=./src/example/router.ts)**
### ⚙️ Global Settings
Configure the router behavior via the `settings` object:
| Property | Description |
| --------------- | --------------------------------------------------------------------- |
| `id` | Target DOM element ID where content will be rendered (e.g., `'app'`). |
| `rootUrl` | The base path for your app (e.g., `/foo` for `domain.com/foo/#/`). |
| `middleware` | Global async function executed before every navigation. |
| `script` | Global function executed after the DOM has been updated. |
| `isFirstRender` | Set to `true` to force rendering on the first load. |
### 🛠 Installation
```bash
npm install @muryp/router-dom
# or
pnpm add @muryp/router-dom
```
### 🧪 Requirements
- **Node.js v20 LTS** or later.
- **TypeScript** is highly recommended for full type safety.
### Contributing
Contributions are welcome! If you encounter issues or have suggestions, please visit the [GitHub repository](https://github.com/muryp/router-dom).
### License
Released under the [MIT License](https://github.com/muryp/router-dom/blob/main/LICENSE).