olova 2.0.53 → 2.0.55

package/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-01-08
+
+### Added
+
+- Initial release of Olova
+- File-based routing with Next.js App Router conventions
+- `OlovaRouter` component for rendering routes
+- Vite plugin for automatic route generation
+- React hooks: `usePathname`, `useParams`, `useSearchParams`, `useRouter`
+- `Link` and `NavLink` components for client-side navigation
+- Error boundaries with `error.tsx` support
+- Loading states with `loading.tsx` support
+- 404 handling with `not-found.tsx` support
+- Dynamic routes with `[slug]` syntax
+- Catch-all routes with `[...slug]` syntax
+- Route groups with `(group)` syntax
+- Nested layouts support
+- TypeScript support with full type definitions
+- CLI for build commands
+
+### Known Limitations
+
+- SSG pre-rendering is not yet fully implemented
+- Parallel routes are experimental

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sera
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,34 +1,24 @@
 # Olova
 
-A Next.js-style React framework built on Vite with SSG, SSR, streaming, and progressive hydration.
+> Next.js-style file-based routing for Vite + React
+
+Olova brings the intuitive file-based routing conventions from Next.js App Router to your Vite + React applications. Build modern web apps with nested layouts, dynamic routes, loading states, and error boundaries - all through your file structure.
 
 ## Features
 
-- 🚀 **File-based routing** - Next.js-style pages directory
-- ⚡ **Vite-powered** - Lightning fast HMR and builds
-- 📄 **SSG & SSR** - Static generation and server-side rendering
-- 🌊 **Streaming SSR** - React 18 streaming with Suspense
-- 💧 **Progressive Hydration** - Flight format for efficient hydration
-- 🔗 **Link Prefetching** - Automatic route prefetching
-- 📱 **Dynamic Routes** - `[slug]`, `[...slug]`, `[[...slug]]` patterns
-- 🎯 **Route Groups** - `(group)` folders for organization
+- 📁 **File-based routing** - Create routes by adding files to your `app` directory
+- 🏗️ **Nested layouts** - Share UI between routes with layout components
+- 🔄 **Dynamic routes** - Support for `[slug]`, `[...catchAll]`, and route groups `(group)`
+- ⏳ **Loading states** - Per-route loading UI with `loading.tsx`
+- ❌ **Error boundaries** - Per-route error handling with `error.tsx`
+- 🔗 **Client-side navigation** - Seamless SPA navigation with `Link` component
+- 🪝 **React hooks** - `usePathname`, `useParams`, `useSearchParams`, `useRouter`
+- ⚡ **Vite plugin** - Automatic route generation at build time
 
 ## Installation
 
 ```bash
 npm install olova
-# or
-yarn add olova
-# or
-pnpm add olova
-```
-
-### Peer Dependencies
-
-Olova requires the following peer dependencies:
-
-```bash
-npm install react react-dom vite
 ```
 
 ## Quick Start
@@ -37,274 +27,295 @@ npm install react react-dom vite
 
 ```ts
 // vite.config.ts
-import { defineConfig } from 'vite';
-import react from '@vitejs/plugin-react';
-import { olova } from 'olova';
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import { olova } from "olova/plugin";
 
 export default defineConfig({
-  plugins: [react(), olova()],
+  plugins: [
+    react(),
+    olova({
+      appDir: "src/app", // Your app directory
+    }),
+  ],
 });
 ```
 
-### 2. Create Olova Config (Optional)
+### 2. Create your app structure
 
-```ts
-// olova.config.ts
-import { defineConfig } from 'olova';
+```
+src/app/
+├── layout.tsx       # Root layout
+├── page.tsx         # Home page (/)
+├── loading.tsx      # Loading state
+├── error.tsx        # Error boundary
+├── about/
+│   └── page.tsx     # About page (/about)
+├── blog/
+│   ├── layout.tsx   # Blog layout
+│   ├── page.tsx     # Blog index (/blog)
+│   └── [slug]/
+│       └── page.tsx # Blog post (/blog/:slug)
+└── (marketing)/
+    └── pricing/
+        └── page.tsx # Pricing (/pricing) - grouped route
+```
 
-export default defineConfig({
-  // Enable SSG globally
-  ssg: {
-    enabled: true,
-  },
-  // Configure experimental features
-  experimental: {
-    prefetch: true,
-  },
-});
+### 3. Set up the router
+
+```tsx
+// src/main.tsx
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { OlovaRouter } from "olova";
+import { routes } from "virtual:olova-routes";
+
+createRoot(document.getElementById("root")!).render(
+  <StrictMode>
+    <OlovaRouter routes={routes} />
+  </StrictMode>
+);
 ```
 
-### 3. Create Pages
+## File Conventions
 
-Create a `src` directory with page files:
+| File            | Purpose                                                |
+| --------------- | ------------------------------------------------------ |
+| `page.tsx`      | UI for the route (required for route to be accessible) |
+| `layout.tsx`    | Shared layout wrapping child routes                    |
+| `loading.tsx`   | Loading UI shown while page loads                      |
+| `error.tsx`     | Error UI shown when errors occur                       |
+| `not-found.tsx` | 404 UI for the route                                   |
+
+## Route Patterns
+
+### Static Routes
 
 ```
-src/
-├── layout.tsx      # Root layout
-├── page.tsx        # Home page (/)
-├── about/
-│   └── page.tsx    # About page (/about)
-└── blog/
-    ├── page.tsx    # Blog index (/blog)
-    └── [slug]/
-        └── page.tsx # Blog post (/blog/:slug)
+app/about/page.tsx → /about
+app/contact/page.tsx → /contact
 ```
 
-### 4. Create Layout
+### Dynamic Routes
 
-```tsx
-// src/layout.tsx
-export default function Layout({ children }: { children: React.ReactNode }) {
-  return (
-    <html>
-      <body>{children}</body>
-    </html>
-  );
-}
+```
+app/blog/[slug]/page.tsx → /blog/:slug
+app/users/[id]/page.tsx → /users/:id
 ```
 
-### 5. Create a Page
+### Catch-all Routes
 
-```tsx
-// src/page.tsx
-import { Link } from 'olova';
+```
+app/docs/[...slug]/page.tsx → /docs/*
+```
 
-export const metadata = {
-  title: 'Home',
-  description: 'Welcome to my site',
-};
+### Route Groups
 
-export default function HomePage() {
-  return (
-    <div>
-      <h1>Welcome</h1>
-      <Link href="/about">About</Link>
-    </div>
-  );
-}
+Route groups `(folder)` organize files without affecting the URL:
+
+```
+app/(marketing)/pricing/page.tsx → /pricing
+app/(marketing)/about/page.tsx → /about
 ```
 
-## Routing
+## Components
 
-### Link Component
+### Link
+
+Client-side navigation with prefetching:
 
 ```tsx
 import { Link } from 'olova';
 
 <Link href="/about">About</Link>
-<Link href="/blog/hello" prefetch={false}>Blog Post</Link>
-<Link href="/dashboard" replace>Dashboard</Link>
+<Link href="/blog/my-post" replace>Blog Post</Link>
 ```
 
-### useRouter Hook
+### NavLink
+
+Navigation link with active state:
 
 ```tsx
-import { useRouter } from 'olova';
+import { NavLink } from "olova";
 
-function MyComponent() {
-  const router = useRouter();
-  
-  const handleClick = () => {
-    router.push('/dashboard');
-  };
-  
-  return <button onClick={handleClick}>Go to Dashboard</button>;
-}
+<NavLink href="/dashboard" activeClassName="text-blue-500" exact>
+  Dashboard
+</NavLink>;
 ```
 
-### useParams Hook
+## Hooks
+
+### usePathname
+
+Get the current pathname:
 
 ```tsx
-import { useParams } from 'olova';
+import { usePathname } from "olova";
 
-// In /blog/[slug]/page.tsx
-function BlogPost() {
-  const { slug } = useParams();
-  return <h1>Post: {slug}</h1>;
+function Component() {
+  const pathname = usePathname();
+  return <div>Current path: {pathname}</div>;
 }
 ```
 
-### usePathname Hook
+### useParams
+
+Access route parameters:
 
 ```tsx
-import { usePathname } from 'olova';
+import { useParams } from "olova";
 
-function Navigation() {
-  const pathname = usePathname();
-  return <nav>Current: {pathname}</nav>;
+function BlogPost() {
+  const { slug } = useParams<{ slug: string }>();
+  return <div>Reading: {slug}</div>;
 }
 ```
 
-### useSearchParams Hook
+### useSearchParams
+
+Access URL search parameters:
 
 ```tsx
-import { useSearchParams } from 'olova';
+import { useSearchParams } from "olova";
 
 function SearchPage() {
   const searchParams = useSearchParams();
-  const query = searchParams.get('q');
+  const query = searchParams.get("q");
   return <div>Searching for: {query}</div>;
 }
 ```
 
-## Static Generation
+### useRouter
 
-Mark pages for static generation with the `"use static"` directive:
+Programmatic navigation:
 
 ```tsx
-"use static";
+import { useRouter } from "olova";
+
+function Component() {
+  const router = useRouter();
 
-export default function AboutPage() {
-  return <h1>About Us</h1>;
+  return (
+    <button onClick={() => router.push("/dashboard")}>Go to Dashboard</button>
+  );
 }
 ```
 
-Or enable globally in `olova.config.ts`:
+Router methods:
 
-```ts
-export default defineConfig({
-  ssg: {
-    enabled: true,
-  },
-});
-```
+- `push(url)` - Navigate to URL
+- `replace(url)` - Navigate without adding to history
+- `back()` - Go back
+- `forward()` - Go forward
+- `refresh()` - Refresh current route
+- `prefetch(url)` - Prefetch a route
 
-## Head Management
+## Page Props
+
+Pages receive `params` and `searchParams`:
 
 ```tsx
-import { Head } from 'olova';
+// app/blog/[slug]/page.tsx
+interface PageProps {
+  params: { slug: string };
+  searchParams: Record<string, string>;
+}
 
-function MyPage() {
+export default function BlogPost({ params, searchParams }: PageProps) {
   return (
-    <>
-      <Head>
-        <title>My Page</title>
-        <meta name="description" content="Page description" />
-      </Head>
-      <div>Content</div>
-    </>
+    <article>
+      <h1>Post: {params.slug}</h1>
+    </article>
   );
 }
 ```
 
-Or use the `metadata` export:
+## Layout Props
+
+Layouts receive `children` and `params`:
 
 ```tsx
-export const metadata = {
-  title: 'My Page',
-  description: 'Page description',
-  openGraph: {
-    title: 'My Page',
-    description: 'Page description',
-  },
-};
+// app/blog/layout.tsx
+interface LayoutProps {
+  children: React.ReactNode;
+  params: { slug?: string };
+}
+
+export default function BlogLayout({ children }: LayoutProps) {
+  return (
+    <div className="blog-layout">
+      <nav>Blog Navigation</nav>
+      <main>{children}</main>
+    </div>
+  );
+}
 ```
 
-## Configuration Options
+## Error Handling
 
-```ts
-import { defineConfig } from 'olova';
+Create `error.tsx` to handle errors in a route segment:
 
-export default defineConfig({
-  // Output directory
-  outDir: '.olova/dist',
-  
-  // Base path for the app
-  basePath: '/',
-  
-  // Enable trailing slashes
-  trailingSlash: false,
-  
-  // SSG configuration
-  ssg: {
-    enabled: false,
-    prerender: ['/about', '/contact'],
-  },
-  
-  // Experimental features
-  experimental: {
-    prefetch: true,
-    serverComponents: false,
-  },
-  
-  // Static generation settings
-  staticGeneration: {
-    timeout: 30000,
-    fallback: 'blocking',
-  },
-  
-  // Custom Vite config
-  vite: {
-    // Vite options
-  },
-});
+```tsx
+// app/blog/error.tsx
+interface ErrorProps {
+  error: Error;
+  reset: () => void;
+}
+
+export default function BlogError({ error, reset }: ErrorProps) {
+  return (
+    <div>
+      <h2>Something went wrong!</h2>
+      <p>{error.message}</p>
+      <button onClick={reset}>Try again</button>
+    </div>
+  );
+}
 ```
 
-## Exports
+## Loading States
 
-### Main Entry (`olova`)
+Create `loading.tsx` for loading UI:
 
-- `olova` - Vite plugin
-- `defineConfig` - Configuration helper
-- `Link` - Navigation component
-- `Router` - Router component
-- `useRouter` - Router hook
-- `useParams` - Params hook
-- `usePathname` - Pathname hook
-- `useSearchParams` - Search params hook
-- `navigate` - Programmatic navigation
-- `replace` - Replace navigation
-- `Head` - Head management component
-- `HeadProvider` - Head context provider
-- `usePageData` - Page data hook
+```tsx
+// app/blog/loading.tsx
+export default function BlogLoading() {
+  return (
+    <div className="animate-pulse">
+      <div className="h-8 bg-gray-200 rounded w-3/4 mb-4" />
+      <div className="h-4 bg-gray-200 rounded w-full mb-2" />
+      <div className="h-4 bg-gray-200 rounded w-5/6" />
+    </div>
+  );
+}
+```
 
-### Client Entry (`olova/client`)
+## Plugin Options
+
+```ts
+olova({
+  // Directory containing routes (default: 'src/app')
+  appDir: "src/app",
 
-Client-side hydration and routing utilities.
+  // File extensions to look for (default: ['.tsx', '.ts', '.jsx', '.js'])
+  extensions: [".tsx", ".ts"],
 
-### Server Entry (`olova/server`)
+  // Base URL path (default: '/')
+  basePath: "",
 
-Server-side rendering and streaming utilities:
+  // Enable trailing slashes (default: false)
+  trailingSlash: false,
+});
+```
 
-- `renderToStream` - Streaming SSR
-- `renderToStringWithFlight` - SSG with Flight payload
-- `generateHtmlShell` - HTML shell generation
-- `createStreamingHeaders` - Streaming response headers
+## TypeScript
 
-### Plugin Entry (`olova/plugin`)
+Olova is fully typed. Import types for your pages and layouts:
 
-Direct access to the Vite plugin.
+```tsx
+import type { PageProps, LayoutProps, ErrorProps, LoadingProps } from "olova";
+```
 
 ## License
 
-MIT
+MIT © sera