Actualizar Readme.md
This commit is contained in:
130
Readme.md
130
Readme.md
@@ -1,77 +1,131 @@
|
||||
# Svelte 5 Micro-Router (File-Based)
|
||||
# Svelte 5 File-Based Micro-Router
|
||||
|
||||
This is a lightweight, custom-built file-based router for **Svelte 5** that mimics the SvelteKit routing system for standalone Single Page Applications (SPA) powered by **Vite**.
|
||||
A lightweight, zero-dependency routing engine for **Svelte 5** and **Vite**. This project brings the "File-based Routing" experience of SvelteKit to standard Single Page Applications (SPA).
|
||||
|
||||
## 🚀 Features
|
||||
## 📖 What is it?
|
||||
|
||||
* **File-based Routing:** Automatically detects and maps `.svelte` files inside the `routes` directory.
|
||||
* **Dynamic Routes:** Full support for dynamic parameters using the `[id].svelte` syntax.
|
||||
* **Svelte 5 Native:** Built using **Runes** (`$state`, `$props`, `{@render}`) for reactive performance and modern syntax.
|
||||
* **Zero Dependencies:** No heavy routing libraries required; uses native Browser APIs.
|
||||
This is a **client-side router** that uses Vite’s dynamic scanning capabilities (`import.meta.glob`) to automatically turn your `.svelte` files into reachable URLs.
|
||||
|
||||
## 📁 Recommended Directory Structure
|
||||
* **No manual route definitions:** If the file exists in `/routes`, the URL exists.
|
||||
* **Svelte 5 Native:** Uses the new **Runes** system (`$state`, `$props`) for reactive route matching.
|
||||
* **Automatic Navigation:** Intercepts standard `<a>` tags to prevent page refreshes.
|
||||
|
||||
The router scans for files within `src/routes/`. Your project should look like this:
|
||||
---
|
||||
|
||||
```text
|
||||
src/
|
||||
├── routes/
|
||||
│ ├── index.svelte // Route: /
|
||||
│ ├── about-us.svelte // Route: /about-us
|
||||
│ └── post/
|
||||
│ └── [id].svelte // Route: /post/:id
|
||||
└── App.svelte // Import and use this Router here
|
||||
## ⚙️ Installation & Setup
|
||||
|
||||
### 1. Project Requirements
|
||||
|
||||
You must be using **Vite** and **Svelte 5**.
|
||||
|
||||
```bash
|
||||
npm install svelte@next
|
||||
|
||||
```
|
||||
|
||||
## 🛠️ How it Works
|
||||
### 2. Vite Configuration
|
||||
|
||||
### 1. Route Scanning
|
||||
Ensure your `vite.config.js` is configured to handle Svelte. No special router plugin is needed, but an alias is recommended for cleaner pathing:
|
||||
|
||||
The router uses `import.meta.glob` to analyze your file system at build time. It converts file paths into Regular Expressions:
|
||||
```javascript
|
||||
// vite.config.js
|
||||
import { defineConfig } from 'vite';
|
||||
import { svelte } from '@sveltejs/vite-plugin-svelte';
|
||||
import path from 'path';
|
||||
|
||||
* `index.svelte` ➔ `/`
|
||||
* `[id].svelte` ➔ `/(?<id>[^/]+)` (Captures the ID as a Regex group).
|
||||
export default defineConfig({
|
||||
plugins: [svelte()],
|
||||
resolve: {
|
||||
alias: {
|
||||
// Helps the router find your pages folder
|
||||
'$routes': path.resolve('./src/routes')
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
### 2. Navigation Interception
|
||||
```
|
||||
|
||||
The component attaches a global **Click Event Listener** to the `window`. When a user clicks an internal `<a>` tag:
|
||||
### 3. Router Placement
|
||||
|
||||
1. It prevents the default page reload (`e.preventDefault()`).
|
||||
2. It updates the URL via the **History API** (`pushState`).
|
||||
3. It triggers the `update()` function to swap the UI component.
|
||||
Save the router code as `src/lib/Router.svelte`.
|
||||
|
||||
### 4. Dynamic Rendering
|
||||
---
|
||||
|
||||
By using the `{#key CurrentPage}` block, the router ensures that components are properly destroyed and re-mounted when navigating between different instances of the same route (e.g., navigating from `/post/1` to `/post/2`).
|
||||
## 🚀 How to Use
|
||||
|
||||
## 💻 Usage in App.svelte
|
||||
### 1. Create your Pages
|
||||
|
||||
The router looks at `src/routes/`. Simply create files to define your website structure:
|
||||
|
||||
| File Path | Resulting URL | Type |
|
||||
| --- | --- | --- |
|
||||
| `src/routes/index.svelte` | `/` | Home |
|
||||
| `src/routes/about.svelte` | `/about` | Static |
|
||||
| `src/routes/post/[id].svelte` | `/post/:id` | Dynamic |
|
||||
|
||||
### 2. Initialize in App.svelte
|
||||
|
||||
Import and place the `<Router />` in your root component. This acts as the placeholder where your pages will be swapped.
|
||||
|
||||
```svelte
|
||||
<script>
|
||||
import Router from './lib/Router.svelte';
|
||||
</script>
|
||||
|
||||
<nav>
|
||||
<a href="/">Home</a>
|
||||
<a href="/about">About</a>
|
||||
</nav>
|
||||
|
||||
<main>
|
||||
<Router />
|
||||
</main>
|
||||
|
||||
```
|
||||
|
||||
### 3. Handling Dynamic Parameters
|
||||
|
||||
Inside a file like `[id].svelte`, the router automatically passes the URL parameters as **props**.
|
||||
|
||||
```svelte
|
||||
<script>
|
||||
// Receive the [id] from the filename as a prop
|
||||
let { id } = $props();
|
||||
</script>
|
||||
|
||||
<h1>Displaying Post: {id}</h1>
|
||||
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ Advanced Options
|
||||
|
||||
The Router supports **Snippets** for loading states and 404 errors:
|
||||
|
||||
```svelte
|
||||
<Router>
|
||||
{#snippet loading()}
|
||||
<div class="spinner">Loading page...</div>
|
||||
<div class="spinner">Fetching page...</div>
|
||||
{/snippet}
|
||||
|
||||
{#snippet fallback()}
|
||||
<div class="error">
|
||||
<h1>404</h1>
|
||||
<p>The page you are looking for does not exist.</p>
|
||||
<a href="/">Go back home</a>
|
||||
<p>Page not found.</p>
|
||||
</div>
|
||||
{/snippet}
|
||||
</Router>
|
||||
|
||||
```
|
||||
|
||||
## ⚠️ Current Limitations
|
||||
## ⚠️ Important: Production Deployment
|
||||
|
||||
* **Nesting:** Does not support nested `layout.svelte` files automatically (requires extra logic).
|
||||
* **Preloading:** Components are loaded only when the navigation occurs.
|
||||
* **Query Params:** While they won't break the app, they are currently ignored by the parameter parser.
|
||||
Since this is a **Client-Side Router (SPA)**, you must configure your hosting provider (Netlify, Vercel, or Nginx) to redirect all traffic to `index.html`.
|
||||
|
||||
---
|
||||
If you don't do this, refreshing the page on `/about` will result in a 404 error because the server looks for a physical file that doesn't exist.
|
||||
|
||||
* **Netlify (`_redirects`):** `/* /index.html 200`
|
||||
* **Vercel (`vercel.json`):** Use the `rewrites` configuration.
|
||||
|
||||
---
|
||||
Reference in New Issue
Block a user