reroute-js 0.11.5 → 0.13.0

package/README.md

@@ -45,15 +45,17 @@ Reroute is a dead-simple file-based routing framework for building full-stack Re
   - `useRouter()` - Access router state and utilities
 - 📚 **Content Hooks**:
   - `useContent()` - Load and manage content collections with sorting
+  - `useFeed()` - Discover RSS feed URLs for current route
 - 🧩 **Components**:
   - `<Link>` - Client-side navigation with automatic prefetching
   - `<Image>` - Optimized images with automatic format negotiation and lazy loading
   - `<Outlet>` - Render nested route components
   - `<ContentRoute>` - Dynamic content rendering with metadata injection
+  - `<ClientOnly>` - Client-side only rendering with optional layout preservation (className/style props)
 - 🎭 **Providers**:
-  - `<RouterProvider>` - Router context for the app
-  - `<ContentProvider>` - Content system context
-  - `<RerouteProvider>` - All-in-one provider wrapper
+  - `<RerouteProvider>` - **USE THIS** - All-in-one provider with routing + content + artifacts
+  - `<RouterProvider>` - Low-level router only (internal use, prefer RerouteProvider)
+  - `<ContentProvider>` - Content system context (internal use)
 - 🗂️ **SSR Data**:
   - `useData()` - Read route-level SSR data without loaders
   - `export const ssr = { data() {} }` - Route data function executed on server
@@ -116,6 +118,23 @@ Reroute is a dead-simple file-based routing framework for building full-stack Re
 - 🌍 **Language Attribute** - Dynamic `lang` attribute support
 - 🎯 **SEO Optimization** - Title, description, and custom meta tags
 
+### 🗺️ Sitemap Generation
+- 🔍 **Auto-Discovery** - Automatically discovers static routes, content collections, and ssr.data routes
+- 📄 **XML Generation** - Standards-compliant sitemap.xml following Google's specifications
+- 💾 **Smart Caching** - Generated on first request and cached according to maxAge
+- 📊 **Auto-Pagination** - Automatically splits into multiple files for sites with 50k+ URLs
+- 🎨 **Custom Extractors** - Content-agnostic URL and date extraction via configuration
+- 📅 **Metadata Support** - Includes lastmod, changefreq, and priority for each URL
+
+### 📰 RSS Feed Generation
+- 🔍 **Auto-Discovery** - Discovers content collections, route ssr.data, and layout ssr.data
+- 📄 **RSS & Atom Support** - Standards-compliant RSS 2.0 and Atom 1.0 formats
+- 📚 **Per-Collection Feeds** - Each collection gets its own feed (e.g., /blog/feed.xml)
+- 💾 **Smart Caching** - Generated on first request and cached according to maxAge
+- 🎨 **Custom Extractors** - Content-agnostic extraction for title, description, author, pubDate
+- 🔄 **Auto-Sorting** - Items sorted by publication date (newest first)
+- 📏 **Limit Control** - Configurable maximum items per feed (default: 50)
+
 ### 📦 Configuration Options
 - 🎯 **Custom Assets Directory** - Configure where your client files live
 - 🔧 **URL Prefix** - Deploy to subdirectories with custom prefixes
@@ -152,10 +171,19 @@ import { useData, useParams } from 'reroute-js/react';
 import { getProduct } from '../lib/api';
 
 export const ssr = {
-  async data({ params }: { params: { id?: string } }) {
+  async data({ params, set }: { params: { id?: string }; set: { status: number } }) {
     const id = Number.parseInt(params.id || '');
-    if (!Number.isFinite(id)) return { product: null };
+    if (!Number.isFinite(id)) {
+      set.status = 404;  // Set HTTP status code
+      return { product: null };
+    }
+    
     const product = await getProduct(id);
+    if (!product) {
+      set.status = 404;
+      return { product: null };
+    }
+    
     return { product };
   },
 };
@@ -171,6 +199,47 @@ Notes:
 - Works with Bun + Elysia, no client loaders needed for initial render
 - Data is injected as `window.__REROUTE_DATA__` and read during hydration
 - Use with existing content features (useContent); both can be seeded in the same page
+- **HTTP Status Control:** Use `set.status` to set response status codes (follows Elysia's API). Non-200 responses are not cached
+
+## 🎭 Client-Only Rendering
+
+The `ClientOnly` component prevents hydration mismatches for browser-specific code and supports layout preservation to prevent flickering:
+
+```tsx
+import { ClientOnly } from 'reroute-js/react';
+
+// Basic usage - prevent hydration mismatch
+<ClientOnly fallback={<div>Loading...</div>}>
+  <CountdownTimer />
+</ClientOnly>
+
+// Prevent layout shift with height preservation
+<ClientOnly 
+  fallback={<PricingSkeleton />}
+  className="min-h-screen"
+>
+  <PricingSection />
+</ClientOnly>
+
+// With inline styles
+<ClientOnly 
+  fallback={<Loader />}
+  style={{ minHeight: '600px' }}
+>
+  <DashboardContent />
+</ClientOnly>
+```
+
+**When to use:**
+- Components using browser APIs (`window`, `localStorage`, `navigator`)
+- Dynamic values (`Date.now()`, `Math.random()`)
+- Time-sensitive data that differs between server and client
+- Large lazy-loaded components (use `className`/`style` to preserve height)
+
+**Props:**
+- `fallback` - Content to show during SSR and before hydration
+- `className` - Optional className for wrapper div (useful for layout preservation)
+- `style` - Optional inline styles for wrapper div (useful for layout preservation)
 
 ## 🔐 Environment Variables
 
@@ -391,6 +460,210 @@ export default function MyPage() {
 - **Optional**: Only bundle dependencies you actually use
 
 
+## 🗺️ Sitemap & RSS Feed Generation
+
+Reroute provides automatic sitemap and RSS feed generation with zero configuration required.
+
+### Sitemap Generation
+
+Generate standards-compliant XML sitemaps for search engines.
+
+#### Quick Start
+
+```typescript
+// reroute.config.ts
+import { defineConfig } from 'reroute-js/core';
+
+export default defineConfig({
+  sitemap: {
+    enabled: true,  // opt-in (default: false)
+    baseUrl: 'https://your-domain.com',
+  },
+});
+```
+
+Your sitemap is now available at `/sitemap.xml`!
+
+#### What Gets Included
+
+All three sources are automatically discovered:
+
+1. **Static Routes** - Pages in `routes/` folder (e.g., `/`, `/about`, `/contact`)
+2. **Content Collections** - Items in `routes/[collection]/content/` with metadata
+3. **Route SSR Data** - Dynamic data from route `ssr.data` exports
+
+
+
+#### Custom Configuration
+
+For non-standard data structures:
+
+```typescript
+sitemap: {
+  enabled: true,
+  baseUrl: 'https://your-domain.com',
+  
+  // Extract URL segment from ssr.data items
+  extractUrl: (item, routePattern) => {
+    // Products use SKU instead of slug
+    if (routePattern === '/products' && item.sku) {
+      return item.sku;  // /products/laptop-pro-2024
+    }
+    return null; // fall back to defaults (slug, id, name, key)
+  },
+  
+  // Extract lastmod date
+  extractLastmod: (item) => item.updatedAt || item.date,
+  
+  // Default settings
+  changefreq: 'weekly',   // or 'daily', 'monthly', etc.
+  priority: 0.5,          // 0.0 to 1.0
+}
+```
+
+#### Features
+
+- **Runtime generation** - Generated on first request, cached according to `maxAge`
+- **Auto-pagination** - Sites with 50k+ URLs automatically split into multiple files with sitemap index
+- **SEO-friendly** - Includes `<lastmod>`, `<changefreq>`, and `<priority>` tags
+- **Content-agnostic** - Works with any data structure via custom extractors
+- **Smart caching** - Respects your `maxAge` configuration
+
+### RSS Feed Generation
+
+Generate RSS 2.0 and Atom 1.0 feeds for content syndication.
+
+#### Quick Start
+
+```typescript
+// reroute.config.ts
+import { defineConfig } from 'reroute-js/core';
+
+export default defineConfig({
+  rss: {
+    enabled: true,  // opt-in (default: false)
+    baseUrl: 'https://your-domain.com',
+    title: 'My Blog',
+    description: 'Latest posts and updates',
+  },
+});
+```
+
+Your feeds are automatically available at:
+- `/feed.xml` - Main feed (combines all sources below)
+- `/blog/feed.xml` - Blog collection (from `routes/blog/content/`)
+- `/changelog/feed.xml` - Changelog route (from route's `ssr.data`)
+- `/announcements/feed.xml` - Announcements (from layout's `ssr.data`)
+
+Pattern:
+- `/[collection]/feed.xml` - For any content collection
+- `/[route]/feed.xml` - For any route/layout with `ssr.data`
+
+#### What Gets Included
+
+All three sources are automatically discovered:
+
+1. **Content Collections** - Items from `routes/[collection]/content/` folders
+   - Example: Blog posts with metadata (title, description, date)
+   
+2. **Route SSR Data** - Arrays returned by route `ssr.data` functions
+   - Example: Changelog versions fetched from API
+   - Must export `ssr.data` that returns object containing arrays
+   
+3. **Layout SSR Data** - Arrays returned by layout `ssr.data` functions
+   - Example: Site-wide announcements fetched in layout
+   - Must export `ssr.data` in `[layout].tsx` that returns object containing arrays
+
+**Important:** For ssr.data discovery, the data must contain arrays. Nested arrays (e.g., `{ user: { notifications: [...] } }`) are automatically found via recursive discovery.
+
+#### Custom Configuration
+
+```typescript
+rss: {
+  enabled: true,
+  baseUrl: 'https://your-domain.com',
+  title: 'My Blog',
+  description: 'Latest updates',
+  limit: 50,           // max items per feed (default: 50)
+  format: 'rss',       // 'rss' (RSS 2.0) or 'atom' (Atom 1.0)
+  
+  // Extract URL segment from ssr.data items
+  extractUrl: (item, routePattern) => {
+    // Changelog uses version field
+    if (routePattern === '/changelog' && item.version) {
+      return item.version;  // /changelog/1.2.0
+    }
+    return null; // fall back to defaults (slug, id, name, key)
+  },
+  
+  // Extract publication date
+  extractPubDate: (item) => item.publishedAt || item.date || item.createdAt,
+  
+  // Extract author
+  extractAuthor: (item) => item.author || item.authorName,
+  
+  // Extract full content (optional, for full-text feeds)
+  extractContent: (item) => item.body || item.content,
+}
+```
+
+#### Features
+
+- **Multi-source** - Combines content collections, route ssr.data, and layout ssr.data
+- **Per-collection feeds** - Each collection gets `/[collection]/feed.xml`
+- **Per-route feeds** - Routes with ssr.data get `/[route]/feed.xml`
+- **RSS & Atom** - Choose RSS 2.0 or Atom 1.0 format
+- **Auto-sorting** - Items sorted by pubDate (newest first)
+- **Smart caching** - Generated on first request, cached according to `maxAge`
+- **Recursive discovery** - Finds arrays even in nested data (e.g., `user.notifications`)
+- **Content-agnostic** - Works with any data structure via custom extractors
+
+#### Discovering Feeds in Your UI
+
+Use the `useFeed()` hook to automatically discover and link to RSS feeds:
+
+```tsx
+import { useFeed } from 'reroute-js/react';
+
+function Header() {
+  const feed = useFeed();
+  
+  return (
+    <header>
+      {/* Show collection/route-specific feed if available */}
+      {feed.hasFeed && (
+        <a href={feed.feedUrl!} target="_blank">
+          Subscribe to {feed.collection}
+        </a>
+      )}
+      
+      {/* Main feed always available */}
+      <a href={feed.mainFeedUrl}>RSS Feed</a>
+    </header>
+  );
+}
+```
+
+Returns:
+- `feedUrl` - URL of the specific feed (`/blog/feed.xml`, `/changelog/feed.xml`, etc.) or `null`
+- `mainFeedUrl` - Main feed URL (always `/feed.xml`)
+- `collection` - Collection/route name (`'blog'`, `'changelog'`, etc.) or `null`
+- `hasFeed` - Boolean indicating if current route has a specific feed
+
+#### SPA Navigation Support
+
+**Important:** When using layout `ssr.data`, use `<Link>` components (not `<a>` tags) for proper client-side navigation:
+
+```tsx
+import { Link } from 'reroute-js/react';
+
+// ✅ Good - prefetches layout data on hover
+<Link to="/announcements">Announcements</Link>
+
+// ❌ Bad - full page reload, no prefetch
+<a href="/announcements">Announcements</a>
+```
+
 ## 📖 Learn More
 
 - [Examples](./examples) - Example projects to get started

package/_/basic/package.json

@@ -3,12 +3,13 @@
 	"description": "A Reroute application",
 	"version": "0.0.0",
 	"scripts": {
-		"types": "tsc --noEmit",
-		"gen": "reroute gen",
-		"start": "reroute start",
-		"dev": "reroute dev",
-		"build": "reroute build",
-		"analyze": "reroute analyze --prod --open"
+	"types": "tsc --noEmit",
+	"gen": "reroute gen",
+	"start": "reroute start --prod",
+	"dev": "reroute dev",
+	"build": "reroute build",
+	"kill": "bunx kill-port 3000",
+	"analyze": "reroute analyze --prod --open"
 	},
 	"private": true,
 	"dependencies": {

package/_/basic/reroute.config.ts

@@ -3,10 +3,5 @@ import { defineConfig } from 'reroute-js/core';
 export default defineConfig({
 	options: {
 		app: './src/client/App',
-		maxAge: 3600,
-		compression: true
-	},
-	streaming: {
-		enabled: true,
 	},
 });

package/_/basic/src/index.ts

@@ -5,7 +5,10 @@ const app = new Elysia()
 	.use(
 		reroute(),
 	)
-	.get('/api/message', () => ({ message: 'Hello from server' }))
+	.get('/api/message', () => {
+	console.log('[api] log from my api')
+	return { message: 'Hello from server' }
+	})
 	.listen(Number(Bun.env.PORT || '3000'));
 
-console.log(`[reroute] Running at ${app.server?.hostname}:${app.server?.port}`);
+console.log(`[app] Running at ${app.server?.hostname}:${app.server?.port}`);

package/_/blog/package.json

@@ -3,12 +3,13 @@
 	"description": "A Reroute application",
 	"version": "0.0.0",
 	"scripts": {
-		"types": "tsc --noEmit",
-		"gen": "reroute gen",
-		"start": "reroute start",
-		"dev": "reroute dev",
-		"build": "reroute build",
-		"analyze": "reroute analyze --prod --open"
+	"types": "tsc --noEmit",
+	"gen": "reroute gen",
+	"start": "PORT=3001 reroute start --prod",
+	"dev": "PORT=3001 reroute dev",
+	"build": "reroute build",
+	"kill": "bunx kill-port 3001",
+	"analyze": "reroute analyze --prod --open"
 	},
 	"private": true,
 	"dependencies": {

package/_/blog/src/index.ts

@@ -9,8 +9,8 @@ const app = new Elysia()
 		console.log('[api] log from my api');
 		return { message: 'Hello from server' };
 	})
-	.listen(Number(Bun.env.PORT || '3000'));
+	.listen(Number(Bun.env.PORT || '3001'));
 
 console.log(
-	`[reroute] Blog running at ${app.server?.hostname}:${app.server?.port} on ${Bun.env.NODE_ENV || 'development'}`,
+	`[app] Blog running at ${app.server?.hostname}:${app.server?.port} on ${Bun.env.NODE_ENV || 'development'}`,
 );

package/_/redirects/package.json

@@ -4,12 +4,13 @@
 	"description": "A Reroute application",
 	"private": true,
 	"scripts": {
-		"types": "tsc --noEmit",
-		"gen": "reroute gen",
-		"start": "reroute start",
-		"dev": "reroute dev",
-		"build": "reroute build",
-		"analyze": "reroute analyze --prod --open"
+	"types": "tsc --noEmit",
+	"gen": "reroute gen",
+	"start": "PORT=3002 reroute start --prod",
+	"dev": "PORT=3002 reroute dev",
+	"build": "reroute build",
+	"kill": "bunx kill-port 3002",
+	"analyze": "reroute analyze --prod --open"
 	},
 	"dependencies": {
 		"reroute-js": "latest",

package/_/rss/package.json

@@ -0,0 +1,28 @@
+{
+	"name": "{{PROJECT_NAME}}",
+	"version": "0.0.0",
+	"description": "A Reroute application",
+	"private": true,
+	"scripts": {
+	"types": "tsc --noEmit",
+	"gen": "reroute gen",
+	"start": "PORT=3003 reroute start --prod",
+	"dev": "PORT=3003 reroute dev",
+	"build": "reroute build",
+	"kill": "bunx kill-port 3003",
+	"analyze": "reroute analyze --prod --open"
+	},
+	"dependencies": {
+		"reroute-js": "latest",
+		"elysia": "^1.4.12",
+		"react": "^19.2.0",
+		"react-dom": "^19.2.0",
+		"sharp": "^0.34.4"
+	},
+	"devDependencies": {
+		"@types/bun": "latest",
+		"@types/react": "^19.2.2",
+		"@types/react-dom": "^19.2.2",
+		"typescript": "^5"
+	}
+}

package/_/rss/reroute.config.ts

@@ -0,0 +1,23 @@
+import { defineConfig } from 'reroute-js/core';
+
+export default defineConfig({
+	options: {
+		app: './src/client/App',
+		maxAge: 3600,
+		compression: true,
+	},
+	sitemap: {
+		enabled: true,
+		baseUrl: 'http://localhost:3003',
+		// Test pagination with small page size (default 50k)
+		// maxUrlsPerPage: 5,
+		// Custom URL extractor - products use SKU instead of default fields
+		extractUrl: (item, routePattern) => {
+			if (routePattern === '/products' && item.sku) {
+				return item.sku;
+			}
+			return null; // fall back to defaults (slug, id, name, etc.)
+		},
+		extractLastmod: (item) => item.updatedAt || item.date,
+	},
+});

package/_/rss/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "isolatedModules": true,
+    "baseUrl": ".",
+    "rootDir": ".",
+    "declaration": true,
+    "declarationMap": true,
+    "outDir": "dist/types",
+    "emitDeclarationOnly": true,
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "jsx": "react-jsx",
+    "types": ["bun", "node"]
+  },
+  "include": ["**/*.ts", "**/*.tsx"],
+  "exclude": ["node_modules", "dist"]
+}

package/_/sitemap/package.json

@@ -0,0 +1,28 @@
+{
+	"name": "{{PROJECT_NAME}}",
+	"version": "0.0.0",
+	"description": "A Reroute application",
+	"private": true,
+	"scripts": {
+	"types": "tsc --noEmit",
+	"gen": "reroute gen",
+	"start": "PORT=3004 reroute start --prod",
+	"dev": "PORT=3004 reroute dev",
+	"build": "reroute build",
+	"kill": "bunx kill-port 3004",
+	"analyze": "reroute analyze --prod --open"
+	},
+	"dependencies": {
+		"reroute-js": "latest",
+		"elysia": "^1.4.12",
+		"react": "^19.2.0",
+		"react-dom": "^19.2.0",
+		"sharp": "^0.34.4"
+	},
+	"devDependencies": {
+		"@types/bun": "latest",
+		"@types/react": "^19.2.2",
+		"@types/react-dom": "^19.2.2",
+		"typescript": "^5"
+	}
+}

package/_/sitemap/reroute.config.ts

@@ -0,0 +1,23 @@
+import { defineConfig } from 'reroute-js/core';
+
+export default defineConfig({
+	options: {
+		app: './src/client/App',
+		maxAge: 3600,
+		compression: true,
+	},
+	sitemap: {
+		enabled: true,
+		baseUrl: 'http://localhost:3003',
+		// Test pagination with small page size (default 50k)
+		// maxUrlsPerPage: 5,
+		// Custom URL extractor - products use SKU instead of default fields
+		extractUrl: (item, routePattern) => {
+			if (routePattern === '/products' && item.sku) {
+				return item.sku;
+			}
+			return null; // fall back to defaults (slug, id, name, etc.)
+		},
+		extractLastmod: (item) => item.updatedAt || item.date,
+	},
+});

package/_/sitemap/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "isolatedModules": true,
+    "baseUrl": ".",
+    "rootDir": ".",
+    "declaration": true,
+    "declarationMap": true,
+    "outDir": "dist/types",
+    "emitDeclarationOnly": true,
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "jsx": "react-jsx",
+    "types": ["bun", "node"]
+  },
+  "include": ["**/*.ts", "**/*.tsx"],
+  "exclude": ["node_modules", "dist"]
+}

package/_/store/package.json

@@ -4,12 +4,13 @@
 	"description": "A Reroute store application with Tailwind CSS v4",
 	"private": true,
 	"scripts": {
-		"types": "tsc --noEmit",
-		"gen": "reroute gen",
-		"start": "reroute start",
-		"dev": "reroute dev",
-		"build": "reroute build",
-		"analyze": "reroute analyze --prod --open"
+	"types": "tsc --noEmit",
+	"gen": "reroute gen",
+	"start": "PORT=3005 reroute start --prod",
+	"dev": "PORT=3005 reroute dev",
+	"build": "reroute build",
+	"kill": "bunx kill-port 3005",
+	"analyze": "reroute analyze --prod --open"
 	},
 	"dependencies": {
 		"reroute-js": "latest",

package/_/store/src/index.ts

@@ -1,13 +1,10 @@
 import { Elysia } from 'elysia';
 import { reroute } from 'reroute-js/elysia';
 
-
 const app = new Elysia()
-	.use(
-		reroute(),
-	)
-	.listen(Number(Bun.env.PORT || '3001'));
+	.use(reroute())
+	.listen(Number(Bun.env.PORT || '3005'));
 
 console.log(
-	`[reroute] Store running at ${app.server?.hostname}:${app.server?.port} on ${Bun.env.NODE_ENV || 'development'}`,
+	`[app] Store example running at ${app.server?.hostname}:${app.server?.port} on ${Bun.env.NODE_ENV || 'development'}`,
 );

package/_/streaming/package.json

@@ -4,12 +4,13 @@
 	"description": "A Reroute application",
 	"private": true,
 	"scripts": {
-		"types": "tsc --noEmit",
-		"gen": "reroute gen",
-		"start": "reroute start",
-		"dev": "reroute dev",
-		"build": "reroute build",
-		"analyze": "reroute analyze --prod --open"
+	"types": "tsc --noEmit",
+	"gen": "reroute gen",
+	"start": "PORT=3006 reroute start --prod",
+	"dev": "PORT=3006 reroute dev",
+	"build": "reroute build",
+	"kill": "bunx kill-port 3006",
+	"analyze": "reroute analyze --prod --open"
 	},
 	"dependencies": {
 		"reroute-js": "latest",

package/cli/bin.d.ts

@@ -1,5 +1,5 @@
 /**
- * reroute-js v0.11.5
+ * reroute-js v0.13.0
  *
  * @license MIT
  * @copyright 2025 stewones <hi@stewan.io>