loly 0.1.0

package/README.md

@@ -0,0 +1,374 @@
+# loly
+
+![npm](https://img.shields.io/npm/v/loly)
+![license](https://img.shields.io/npm/l/loly)
+
+Modern full-stack web framework with streaming SSR, async server components, islands architecture, and fine-grained reactivity.
+
+## Installation
+
+```bash
+npm install loly
+# or
+yarn add loly
+# or
+pnpm add loly
+```
+
+## Quick Start
+
+Create a new project structure:
+
+```
+my-app/
+├── src/
+│   └── app/
+│       ├── layout.tsx
+│       └── page.tsx
+└── package.json
+```
+
+**src/app/layout.tsx:**
+```tsx
+import type { LayoutProps } from "loly";
+
+export default function Layout({ children }: LayoutProps) {
+  return (
+    <>
+      <nav>Navigation</nav>
+      <main>{children}</main>
+    </>
+  );
+}
+```
+
+**src/app/page.tsx:**
+```tsx
+export default function Home() {
+  return <h1>Hello, loly!</h1>;
+}
+```
+
+Start the development server:
+
+```bash
+npx loly dev
+```
+
+## Core Concepts
+
+### File-based Routing
+
+loly uses a file-based routing system similar to Next.js. Routes are defined by the file structure in `src/app/`:
+
+```
+src/app/
+├── layout.tsx          # Root layout
+├── page.tsx            # Home page (/)
+├── about/
+│   └── page.tsx       # /about
+└── users/
+    └── [id]/
+        └── page.tsx   # /users/:id
+```
+
+**Dynamic routes:**
+- `[id]` - Single dynamic segment
+- `[...slug]` - Catch-all route
+- `[[...slug]]` - Optional catch-all
+- `(group)` - Route groups (not in URL)
+
+**Route files:**
+- `page.tsx` - Page component
+- `layout.tsx` - Layout component (wraps child routes)
+- `route.ts` - API route handler
+
+### SSR and Streaming
+
+loly supports two rendering strategies:
+
+**SSR Strategy** - Full page streaming:
+```tsx
+import { renderPageStream } from "loly";
+
+const result = await renderPageStream({
+  pathname: "/",
+  searchParams: {},
+  params: {},
+}, routeConfig, appDir);
+```
+
+**RSC Strategy** - SPA navigation with partial updates:
+```tsx
+import { renderPageContent } from "loly";
+
+const result = await renderPageContent({
+  pathname: "/",
+  searchParams: {},
+  params: {},
+}, routeConfig, appDir);
+```
+
+### Islands Architecture
+
+Use islands to selectively hydrate components on the client:
+
+```tsx
+import { defineIsland, state } from "loly-jsx";
+
+const CounterIsland = defineIsland("Counter", function Counter() {
+  const [count, setCount] = state(0);
+  return <button onClick={() => setCount(count + 1)}>{count}</button>;
+});
+
+// In your page
+export default function Page() {
+  return (
+    <div>
+      <h1>Server-rendered content</h1>
+      <CounterIsland client:load />
+    </div>
+  );
+}
+```
+
+## Features
+
+### Development Server
+
+Start a development server with hot reload:
+
+```bash
+loly dev [dir] [port]
+```
+
+The dev server:
+- Watches for file changes
+- Supports hot module replacement
+- Provides error overlays
+- Handles TypeScript/JSX automatically
+
+### Build System
+
+Build your application for production:
+
+```bash
+loly build [dir] [--out-dir=<path>] [--dev]
+```
+
+The build process:
+- Scans routes from `src/app/`
+- Builds client bundle with rspack
+- Builds server files with esbuild
+- Generates route manifests
+- Optimizes assets
+
+### API Routes
+
+Create API endpoints using `route.ts` files:
+
+**src/app/api/users/route.ts:**
+```tsx
+import type { Request, Response } from "express";
+
+export async function GET(req: Request, res: Response) {
+  const users = await fetchUsers();
+  return res.json(users);
+}
+
+export async function POST(req: Request, res: Response) {
+  const data = await req.json();
+  const user = await createUser(data);
+  return res.json(user);
+}
+```
+
+Routes support: `GET`, `POST`, `PUT`, `DELETE`, `PATCH`, `HEAD`, `OPTIONS`
+
+### Image Optimization
+
+Use the `Image` component for optimized images:
+
+```tsx
+import { Image } from "loly";
+
+export default function Page() {
+  return (
+    <Image
+      src="/hero.jpg"
+      alt="Hero image"
+      width={800}
+      height={600}
+      quality={90}
+    />
+  );
+}
+```
+
+Features:
+- Automatic format optimization (WebP, AVIF)
+- Responsive images
+- Lazy loading
+- Image caching
+
+### Client Bootstrap
+
+Bootstrap your client application:
+
+```tsx
+import { bootstrapClient } from "loly/client";
+
+bootstrapClient({
+  routes: [
+    { path: "/", component: () => import("./app/page") },
+    { path: "/about", component: () => import("./app/about/page") },
+  ],
+});
+```
+
+## Project Structure
+
+```
+my-app/
+├── src/
+│   ├── app/              # App directory (routes)
+│   │   ├── layout.tsx    # Root layout
+│   │   ├── page.tsx      # Home page
+│   │   └── [routes]/     # Route segments
+│   ├── components/       # Shared components
+│   └── globals.css       # Global styles
+├── public/               # Static assets
+├── .loly/               # Build output (generated)
+│   ├── dist/            # Production build
+│   └── client/          # Client bundle
+└── package.json
+```
+
+## API Reference
+
+### Server
+
+- `startDevServer(options)` - Start development server
+- `startProdServer(options)` - Start production server
+- `renderPageStream(context, config, appDir)` - Render page with streaming
+- `renderPageContent(context, config, appDir)` - Render page content (RSC)
+- `BaseServer` - Base server class for custom implementations
+
+### Router
+
+- `scanRoutes(appDir)` - Scan routes from app directory
+- `matchRoute(pathname, config)` - Match route by pathname
+- `extractParams(pathname, route)` - Extract route parameters
+
+### Build
+
+- `buildProject(options)` - Build project for production
+- `generateRoutesManifest(config, projectDir, appDir)` - Generate route manifest
+- `generateBootstrap(projectDir, routes)` - Generate client bootstrap
+
+### Client
+
+- `bootstrapClient(options)` - Bootstrap client application
+- `navigate(to, options?)` - Navigate programmatically
+
+### Components
+
+- `Image` - Optimized image component
+
+### Utilities
+
+- `getEnv(key)` - Get environment variable
+- `getPublicEnv()` - Get public environment variables
+- `generatePublicEnvScript()` - Generate script tag for public env
+
+## CLI Commands
+
+```bash
+# Development
+loly dev [dir] [port]
+
+# Build
+loly build [dir] [--out-dir=<path>] [--dev]
+
+# Production server
+loly start [dir] [port]
+```
+
+## Environment Variables
+
+Create a `.env` file in your project root:
+
+```env
+# Public variables (exposed to client)
+# Use any prefix you want, e.g. LOLY_PUBLIC_API_URL or VITE_API_URL
+LOLY_PUBLIC_API_URL=https://api.example.com
+
+# Private variables (server only)
+DATABASE_URL=postgresql://...
+API_SECRET=secret
+```
+
+Access in your code:
+
+```tsx
+import { getEnv, getPublicEnv } from "loly";
+
+// Server only
+const dbUrl = getEnv("DATABASE_URL");
+
+// Public (available on client)
+const apiUrl = getPublicEnv().PUBLIC_API_URL;
+```
+
+## Examples
+
+### Page with Layout
+
+**src/app/layout.tsx:**
+```tsx
+import type { LayoutProps } from "loly";
+
+export default function Layout({ children }: LayoutProps) {
+  return (
+    <>
+      <nav>Navigation</nav>
+      <main>{children}</main>
+    </>
+  );
+}
+```
+
+**src/app/page.tsx:**
+```tsx
+export default function Home() {
+  return <h1>Home Page</h1>;
+}
+```
+
+### Dynamic Route
+
+**src/app/users/[id]/page.tsx:**
+```tsx
+import type { PageProps } from "loly";
+
+export default function UserPage({ params }: PageProps) {
+  return <h1>User {params.id}</h1>;
+}
+```
+
+### API Route
+
+**src/app/api/hello/route.ts:**
+```tsx
+import type { Request, Response } from "express";
+
+export async function GET(req: Request, res: Response) {
+  return res.json({ message: "Hello" });
+}
+```
+
+## Links
+
+- [Repository](https://github.com/MenvielleValen/loly)
+- [Homepage](https://loly.dev)
+