reroute-js 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+## [0.2.1](https://github.com/stewones/reroute/compare/v0.2.0...v0.2.1) (2025-11-04)
+
+### 📚 Documentation
+
+* fix typo ([080ee94](https://github.com/stewones/reroute/commit/080ee9423786e35256faf2094a957f1c3e515735))
+
+### 👷 Continuous Integration
+
+* add github releases [skip ci] ([de44be7](https://github.com/stewones/reroute/commit/de44be7a7edc28522730a2981f9873d5f6e4d74c))
+* fix bunx ([f9beb55](https://github.com/stewones/reroute/commit/f9beb5588d0b3cb035df02f1af44879dfbf0d693))
+
+## [0.2.0](https://github.com/stewones/reroute/compare/v0.1.0...v0.2.0) (2025-11-04)
+
+### ⚡ Performance Improvements
+
+* improve static cache ([ca13189](https://github.com/stewones/reroute/commit/ca13189025213d95e125ced4198e34956cac08d8))
+
+### 👷 Continuous Integration
+
+* add ci prefix as trigger ([5d9567a](https://github.com/stewones/reroute/commit/5d9567aede7ab17c3e3da244b2d0e8963ece0dc4))
+* disable tests for now ([45c0855](https://github.com/stewones/reroute/commit/45c08557cd9a436103e9ef0dd12fa239154dd2a5))
+* fix changelog ([00be21e](https://github.com/stewones/reroute/commit/00be21ed183061255e40c6fed51d8f885526573f))
+* fix code quality check ([fa09adb](https://github.com/stewones/reroute/commit/fa09adb5c88bc118839d322698974c7249e9a894))

package/README.md

@@ -1,6 +1,6 @@
 # Reroute
 
-A dead simple file-based routing framework for building fullstack React apps on Bun and Elysia. No extra dependencies are required.
+Reroute is a dead-simple file-based routing framework for building full-stack React apps on top of Bun and Elysia.
 
 ## ✨ Features
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "reroute-js",
-	"version": "0.1.0",
+	"version": "0.2.1",
 	"type": "module",
 	"scripts": {
 		"types": "tsc --noEmit",
@@ -42,7 +42,7 @@
 		}
 	},
 	"bin": {
-		"reroute": "./cli/bin.js"
+		"reroute": "./packages/cli/bin.ts"
 	},
 	"files": [
 		"_",
@@ -57,17 +57,19 @@
 		"@biomejs/biome": "^2.3.3",
 		"@semantic-release/changelog": "^6.0.3",
 		"@semantic-release/git": "^10.0.1",
+		"@semantic-release/github": "^12.0.1",
+		"@tailwindcss/cli": "^4.1.16",
 		"@types/bun": "latest",
 		"@types/react-dom": "^19.2.2",
 		"@vitest/coverage-v8": "^3.2.4",
+		"conventional-changelog-conventionalcommits": "^9.1.0",
 		"dedent": "^1.7.0",
 		"knip": "^5.66.3",
+		"react": "^19.2.0",
+		"react-dom": "^19.2.0",
 		"semantic-release": "^24.2.8",
 		"vite-tsconfig-paths": "^5.1.4",
-		"vitest": "^3.2.4",
-		"@tailwindcss/cli": "^4.1.16",
-		"react": "^19.2.0",
-		"react-dom": "^19.2.0"
+		"vitest": "^3.2.4"
 	},
 	"peerDependencies": {
 		"typescript": "^5",

package/packages/cli/README.md

@@ -0,0 +1,264 @@
+# Reroute CLI
+
+Command-line interface for the Reroute framework.
+
+## Status
+
+✅ **Available** - The `gen` and `init` commands are ready to use!
+
+## Installation
+
+### Local Usage (Recommended)
+
+Use with `bunx` without installation:
+
+```bash
+bunx reroute-js init my-app
+bunx reroute-js gen
+```
+
+### Global Installation
+
+```bash
+bun install -g reroute-js
+reroute gen
+```
+
+## Available Commands
+
+### `reroute init`
+
+Scaffold a new Reroute project with templates.
+
+**What it does:**
+
+1. Creates a new project directory with the specified name
+2. Scaffolds a complete Reroute application structure
+3. Sets up routing, server, and client entry points
+4. Installs all required dependencies
+5. Provides optional templates (basic, blog)
+
+**Usage:**
+
+```bash
+reroute init <project-name>
+reroute init <project-name> --template <template>
+```
+
+**Available Templates:**
+
+- `basic` (default) - Minimal Reroute application with basic routing
+- `blog` - Full-featured blog with content collections and layouts
+
+**Options:**
+
+- `--template <name>` - Template to use (basic, blog)
+- `-h, --help` - Show help
+
+**Examples:**
+
+```bash
+# Create basic project
+bunx reroute-js init my-app
+
+# Create blog project
+bunx reroute-js init my-blog --template blog
+
+# Or with global installation
+reroute init my-app
+reroute init my-blog --template blog
+```
+
+**What gets created:**
+
+```
+your-app/
+├── package.json
+├── .gitignore
+└── src/
+    ├── index.ts              # Server entry point with Elysia
+    └── client/
+        ├── App.tsx           # Root React component
+        ├── index.tsx         # Client entry point (hydration)
+        ├── index.html        # HTML template
+        ├── routes/           # File-based routes
+        │   ├── index.tsx     # Home page
+        │   ├── about.tsx     # About page
+        │   └── [404].tsx     # Not found page
+        └── components/       # React components
+```
+
+For the blog template, additional files are created:
+
+```
+    └── client/
+        ├── routes/
+        │   └── blog/
+        │       ├── index.tsx          # Blog listing
+        │       ├── [slug].tsx         # Dynamic blog post
+        │       ├── [layout].tsx       # Blog layout
+        │       ├── [404].tsx          # Blog not found
+        │       └── content/           # Blog posts
+        │           ├── hello-world.tsx
+        │           └── getting-started.tsx
+        └── components/
+            └── Counter.tsx
+```
+
+### `reroute gen`
+
+Generate content registry and static assets from your routes.
+
+**What it does:**
+
+1. Scans your routes directory for `.tsx` and `.ts` files
+2. Generates type-safe route patterns with dynamic parameters
+3. Builds content chunks with cache-busted filenames
+4. Creates collection-based content registries
+5. Exports layouts and route matching utilities
+
+**Usage:**
+
+```bash
+reroute gen
+reroute gen --watch
+```
+
+This command scans your `src/client/routes` directory and generates:
+
+- `.reroute/routes.ts` - Type-safe route definitions with pattern matching
+- `.reroute/content.ts` - Content registry with metadata and collections
+- `.reroute/collections/*.js` - Per-collection runtime ESM modules
+- `.reroute/chunks/**/*.js` - Bundled content components
+- `.reroute/index.ts` - Aggregated exports for framework integration
+
+**Options:**
+
+- `--watch`, `-w` - Watch for changes and regenerate automatically
+
+**Examples:**
+
+```bash
+# Generate once
+bunx reroute-js gen
+
+# Watch mode for development
+bunx reroute-js gen --watch
+
+# Or with global installation
+reroute gen
+reroute gen --watch
+```
+
+## Tailwind CSS v4 Integration
+
+The CLI automatically detects and integrates with Tailwind CSS v4 when:
+
+1. Both `tailwindcss` and `@tailwindcss/cli` are installed in your project dependencies
+2. An input CSS file exists at `src/client/theme.css` with `@import "tailwindcss"`
+
+When these conditions are met, the CLI will automatically:
+
+- Build Tailwind CSS when running `reroute gen`
+- Watch and rebuild Tailwind CSS in `reroute gen --watch` mode
+- Output compiled CSS to `.reroute/theme.css`
+
+### Setup
+
+1. Install Tailwind CSS v4:
+
+```bash
+bun add -d tailwindcss@next @tailwindcss/cli@next
+```
+
+2. Create your input CSS file at `src/client/theme.css`:
+
+```css
+@import "tailwindcss";
+
+@theme {
+  /* Custom colors */
+  --color-primary-500: #3b82f6;
+  --color-primary-600: #2563eb;
+
+  /* Custom shadows */
+  --shadow-card: 0 1px 3px 0 rgb(0 0 0 / 0.1);
+}
+
+@utility btn {
+  padding: 0.75rem 1.5rem;
+  border-radius: 0.5rem;
+  font-weight: 600;
+
+  &:hover {
+    opacity: 0.9;
+  }
+}
+```
+
+3. Run the generator in watch mode:
+
+```bash
+reroute gen --watch
+```
+
+The CLI will automatically detect Tailwind v4 and compile your styles alongside the route generation!
+
+### Why v4?
+
+Tailwind CSS v4 is a complete rewrite with:
+- **CSS-first configuration** using `@theme` directive (no JS config needed)
+- **5x faster** full builds with the new Oxide engine
+- **100x faster** incremental builds
+- **Native** `@utility` directive for custom utilities
+- Built-in support for modern CSS features
+
+## Integration
+
+The generated files are consumed by the Reroute framework in your project:
+
+```tsx
+import { RerouteProvider } from 'reroute-js/react';
+import { artifacts } from '../../.reroute';
+
+interface AppProps {
+	pathname?: string;
+}
+
+export default function App({ pathname }: AppProps = {}) {
+	return <RerouteProvider from={{ pathname, ...artifacts }} />;
+}
+```
+
+## Project Structure
+
+For the CLI to work correctly, your project should follow this structure:
+
+```
+your-app/
+├── src/
+│   └── client/
+│       └── routes/
+│           ├── index.tsx            # / route
+│           ├── about.tsx            # /about route
+│           ├── blog/
+│           │   ├── [slug].tsx       # /blog/:slug route
+│           │   └── content/
+│           │       ├── post-1.tsx   # Content files
+│           │       └── post-2.tsx
+│           └── [layout].tsx         # Layout wrapper
+└── .reroute/                        # Generated (gitignore this)
+    ├── routes.ts
+    ├── content.ts
+    ├── index.ts
+    ├── collections/
+    │   └── blog.js
+    └── chunks/
+        └── blog/
+            ├── post-1.abc123.js
+            └── post-2.def456.js
+```
+
+## License
+
+MIT

package/{cli/bin.d.ts → packages/cli/bin.ts}

@@ -1,3 +1,3 @@
 #!/usr/bin/env bun
+
 export * from './src/cli';
-//# sourceMappingURL=bin.d.ts.map

package/packages/core/README.md

@@ -0,0 +1,90 @@
+# Reroute Core
+
+Framework-agnostic core utilities for the Reroute framework.
+
+## Overview
+
+This package contains the core, framework-independent logic for Reroute, including:
+
+- **Bundler**: TypeScript/JSX transpilation and bundling utilities
+- **Content**: Content discovery, metadata extraction, and registry management
+- **SSR**: Server-side rendering utilities for React components
+- **Template**: HTML template processing and manipulation
+- **Utils**: Common utilities (compression, MIME types, path handling, caching)
+
+## Usage
+
+This package is typically not used directly by end users. Instead, it's consumed by framework-specific adapters like `@reroute/elysia`.
+
+However, if you're building a custom integration, you can import utilities directly:
+
+```typescript
+import {
+  transpileFile,
+  getBundleUrlsFor,
+  renderSSRDocument,
+  discoverCollections,
+  applyIndexTemplate,
+  gzipIfAccepted
+} from 'reroute-js/core';
+```
+
+## API
+
+### Bundler
+
+- `transpileFile(filePath, originalPath, options, bundleCache)` - Transpile and bundle a TypeScript/JSX file
+- `getBundleUrlsFor(modules, clientDir, prefix, options, bundleCache)` - Get hashed bundle URLs for modules
+- `generateContentHash(content)` - Generate SHA-256 hash for content versioning
+
+### Content
+
+- `discoverCollections(clientDir)` - Discover content collections in the routes directory
+- `buildContentDTOs(collectionPath, clientDir, prefix, isWatchMode)` - Build content item DTOs for a collection
+- `listContentFiles(dir, baseRel)` - Recursively list content files in a directory
+- `getContentMeta(absPath, isWatchMode)` - Extract metadata from a content file
+- `generateContentRegistry(cwd)` - Validate content registry existence
+
+### SSR
+
+- `renderSSRDocument(options)` - Render a React component to HTML with SSR
+- `seedSSRModuleForPath(pathname, clientDir, cwd, isWatchMode)` - Seed SSR module cache for a content path
+
+Per-page metadata: when a content module exports `meta` (or `frontmatter`) and/or `ssr`, SSR will automatically inject page `<head>` tags. Supported by default:
+
+- `meta.title` -> `<title>`
+- `meta.description` or `meta.excerpt` -> `<meta name="description">`
+- `ssr.head` (string or string[]) is appended verbatim.
+- `ssr.lang` overrides the `<html lang>` attribute for the response.
+
+### Template
+
+- `loadIndexHtml(clientDir)` - Load the index.html template
+- `applyIndexTemplate(templateHtml, appHtml, context)` - Apply SSR content to HTML template
+
+### Utils
+
+- `gzipIfAccepted(body, contentType, acceptEncoding)` - Compress response if client accepts gzip
+- `getMimeType(filePath)` - Get MIME type for a file
+- `isCompressible(contentType)` - Check if content type is compressible
+- `LRUCache<K, V>` - LRU cache implementation
+- Path utilities: `join`, `basename`, `extname`, `stripStart`, `stripEnd`
+
+## Types
+
+All TypeScript types are exported, including:
+
+- `Doc` - Generic document type
+- `TemplateContext` - HTML template context
+- `BundleInfo` - Bundle information with hash and code
+- `ContentMeta` - Content metadata
+- `ContentItemDTO` - Content item data transfer object
+- `CoreConfig` - Core configuration options
+- `BundleOptions` - Bundler options
+- `CompressionResult` - Compression result with headers
+- `SSRRenderOptions` - SSR rendering options
+- `SSRRenderResult` - SSR rendering result
+
+## License
+
+MIT

package/packages/elysia/README.md

@@ -0,0 +1,250 @@
+# Reroute Elysia
+
+Elysia adapter for the Reroute framework. This package provides an Elysia plugin that enables server-side rendering, static file serving, content management, and live reload for React applications.
+
+## Overview
+
+This package is a thin adapter layer that integrates Reroute's core functionality with the Elysia web framework. It handles:
+
+- **Server-Side Rendering (SSR)**: Automatic SSR for React components
+- **Static File Serving**: Optimized static asset delivery with compression
+- **Content Management**: File-based content collections with automatic discovery
+- **Live Reload**: Development mode with hot reload via SSE
+- **TypeScript/JSX Transpilation**: On-the-fly bundling with Bun
+- **Asset Optimization**: Content hashing, compression, and caching
+
+## Installation
+
+```bash
+bun add reroute-js elysia react react-dom
+```
+
+## Usage
+
+### Basic Setup
+
+```typescript
+import { Elysia } from 'elysia';
+import { reroute } from 'reroute-js/elysia';
+import { createElement } from 'react';
+import App from './App';
+
+const app = new Elysia()
+  .use(
+    reroute({
+      app: createElement(App),
+      assets: 'src/client',
+      prefix: '/',
+    })
+  )
+  .listen(3000);
+
+console.log(`Server running at http://localhost:3000`);
+```
+
+### With Collections
+
+Content collections are automatically discovered from your `routes` directory:
+
+```
+src/client/
+├── routes/
+│   ├── blog/
+│   │   └── content/
+│   │       ├── post-1.tsx
+│   │       └── post-2.tsx
+│   └── docs/
+│       └── content/
+│           └── guide.tsx
+├── index.html
+└── index.tsx
+```
+
+Collections are accessible at:
+- `/blog/post-1` - SSR rendered
+- `/blog/post-2` - SSR rendered
+- `/__content/blog` - JSON manifest with all blog posts
+
+## API
+
+### `reroute(options: RerouteOptions)`
+
+Creates an Elysia plugin with the provided configuration.
+
+#### Options
+
+##### SSR Options
+
+- **`app?: ReactElement`** - Root React component for SSR. When provided, enables automatic SSR for all routes.
+- **`head?: string`** - Additional HTML to inject into `<head>` (default: `''`)
+- **`lang?: string`** - HTML document language (default: `'en'`)
+- **`appId?: string`** - ID of the root element (default: `'root'`)
+- **`entrypoint?: string`** - Client-side entry file (default: `'index.tsx'`)
+
+##### Static Serving Options
+
+- **`assets?: string`** - Assets directory path (default: `'src/client'`)
+- **`prefix?: string`** - URL prefix for static files (default: `'/'`)
+- **`ignorePatterns?: (string | RegExp)[]`** - Files to ignore (default: `['.DS_Store', '.git', '.env', 'index.html', /favicon\.ico/, /\.well-known/]`)
+- **`staticHeaders?: Record<string, string>`** - Additional headers for static files
+- **`maxAge?: number`** - Cache max-age in seconds (default: `3600`)
+- **`directive?: string`** - Cache-Control directive (default: `'public'`)
+- **`indexHTML?: boolean`** - Serve index.html for directories (default: `true`)
+
+##### Build Options
+
+- **`minify?: boolean`** - Minify JavaScript bundles (default: `process.env.NODE_ENV === 'production'`)
+- **`sourcemap?: boolean`** - Generate sourcemaps (default: `true`)
+
+## Features
+
+### Automatic SSR
+
+When you provide a root component via the `app` option, Reroute automatically:
+
+1. Discovers content collections in your routes directory
+2. Registers SSR routes for each collection (e.g., `/blog/*`, `/docs/*`)
+3. Renders components on the server with React
+4. Sends fully hydrated HTML to the client
+5. Hydrates the client-side React app seamlessly
+
+### Content Collections
+
+Content files are TypeScript/TSX modules that export a React component and optional metadata:
+
+```tsx
+// src/client/routes/blog/content/my-post.tsx
+export const meta = {
+  title: 'My Blog Post',
+  excerpt: 'This is a great post',
+  date: '2024-01-15',
+};
+
+// Optional SSR extras per page
+export const ssr = {
+  // Extra tags appended verbatim into <head>
+  head: [
+    '<meta property="og:type" content="article" />',
+  ],
+  // Override document language for this page
+  lang: 'en',
+};
+
+export default function MyPost() {
+  return (
+    <article>
+      <h1>My Blog Post</h1>
+      <p>Content goes here...</p>
+    </article>
+  );
+}
+```
+
+Access via:
+- **Route**: `/blog/my-post` (SSR rendered)
+- **API**: `/__content/blog` (JSON manifest)
+
+During SSR, `meta.title` and `meta.description` (or `meta.excerpt`) are converted into `<title>` and `<meta name="description">`. Any `ssr.head` content is appended to `<head>`, and `ssr.lang` overrides the HTML `lang` attribute for that response.
+
+### Development Mode
+
+Run with `--watch` flag to enable live reload:
+
+```bash
+bun --watch src/server.ts
+```
+
+Features:
+- File watching with automatic rebuild
+- SSE-based live reload (no browser extension needed)
+- Fast hot module replacement
+- Source map support
+
+### Production Optimization
+
+In production:
+- JavaScript bundles are minified
+- Content is hashed for cache busting (e.g., `index.abc12345.js`)
+- Responses are gzip compressed
+- Aggressive caching headers for hashed assets
+- Preloading hints for content chunks
+
+## Routes
+
+The Elysia plugin registers these routes automatically:
+
+### Content Routes
+- `/__content/:collection` - JSON manifest of collection items
+
+### Development Routes (watch mode only)
+- `/__reroute_watch` - SSE endpoint for live reload
+- `/__reroute_watch.js` - Live reload client script
+- `/__reroute_preload` - Content chunk preloader
+
+### Artifact Routes
+- `/.reroute/*` - Generated content chunks and bundles
+
+### SSR Routes
+- `/:collection/:slug` - Server-rendered collection items
+- `/*` (fallback) - Catch-all SSR for unmatched routes
+
+### Static Routes
+- `${prefix}/*` - Static file serving with transpilation
+
+## Architecture
+
+This package is built on top of `reroute-js/core`, which provides framework-agnostic utilities. The Elysia adapter:
+
+1. Translates Elysia request/response objects
+2. Registers appropriate route handlers
+3. Handles errors with Elysia's `NotFoundError`
+4. Manages caches and live reload state
+
+This separation allows Reroute to support multiple frameworks (Hono, Fastify, etc.) by creating similar adapter packages.
+
+## Examples
+
+### Custom Ignore Patterns
+
+```typescript
+reroute({
+  ignorePatterns: [
+    '.DS_Store',
+    /\.test\.(ts|tsx|js|jsx)$/,
+    /^_/, // Ignore files starting with underscore
+  ],
+})
+```
+
+### Custom Headers
+
+```typescript
+reroute({
+  staticHeaders: {
+    'X-Custom-Header': 'value',
+    'Access-Control-Allow-Origin': '*',
+  },
+})
+```
+
+### Multiple Asset Directories
+
+You can mount multiple reroute instances with different prefixes:
+
+```typescript
+new Elysia()
+  .use(reroute({ assets: 'src/client', prefix: '/app' }))
+  .use(reroute({ assets: 'src/admin', prefix: '/admin' }))
+```
+
+## TypeScript
+
+All types are exported from the package:
+
+```typescript
+import type { RerouteOptions } from 'reroute-js/elysia';
+```
+
+## License
+
+MIT

package/packages/react/README.md

@@ -0,0 +1,3 @@
+# Reroute React
+
+React specific building blocks to enable the Reroute features.