@constela/start 1.2.23 → 1.2.24

package/README.md

@@ -8,118 +8,87 @@ Meta-framework for Constela applications with dev server, build tools, and SSG.
 npm install @constela/start
 ```
 
-## Overview
+## Quick Start
 
-This package provides a full-stack framework for building Constela applications:
-
-- **Dev Server** - Vite-powered development server with HMR
-- **Build** - Production builds with SSG support
-- **File Router** - File-based routing conventions
-- **Data Loading** - Glob, file, and API data sources
-- **MDX** - Markdown with JSX component support
-- **Layouts** - Nested layout composition
-- **API Routes** - Server-side API endpoints
-- **Middleware** - Request middleware chain
-- **Edge Adapters** - Deploy to Cloudflare, Vercel, Deno
-
-## CLI Usage
+1. Create a project:
 
 ```bash
-# Development server
-npx constela-start dev --port 3000
-
-# Production build
-npx constela-start build --outDir dist
-
-# Start production server
-npx constela-start start --port 3000
+mkdir my-app && cd my-app
+npm init -y
+npm install @constela/start
+mkdir -p src/routes
 ```
 
-## API Reference
-
-### createDevServer
+2. Create a page (`src/routes/index.json`):
 
-Creates a development server with hot reload.
-
-```typescript
-import { createDevServer } from '@constela/start';
-
-const server = await createDevServer({
-  port: 3000,
-  host: 'localhost',
-  routesDir: 'src/routes',
-  publicDir: 'public',
-  layoutsDir: 'src/layouts',
-  css: {
-    links: ['/styles/main.css'],
+```json
+{
+  "version": "1.0",
+  "state": {
+    "count": { "type": "number", "initial": 0 }
   },
-});
+  "actions": [
+    {
+      "name": "increment",
+      "steps": [{ "do": "update", "target": "count", "operation": "increment" }]
+    }
+  ],
+  "view": {
+    "kind": "element",
+    "tag": "button",
+    "props": { "onClick": { "event": "click", "action": "increment" } },
+    "children": [{ "kind": "text", "value": { "expr": "state", "name": "count" } }]
+  }
+}
 ```
 
-**DevServerOptions:**
-- `port?: number` - Server port (default: 3000)
-- `host?: string` - Server host (default: localhost)
-- `routesDir?: string` - Routes directory (default: src/routes)
-- `publicDir?: string` - Static files directory (default: public)
-- `layoutsDir?: string` - Layouts directory
-- `css?: { links?: string[] }` - CSS configuration
-
-### build
-
-Builds the application for production.
-
-```typescript
-import { build } from '@constela/start';
-
-const result = await build({
-  outDir: 'dist',
-  routesDir: 'src/routes',
-  publicDir: 'public',
-  layoutsDir: 'src/layouts',
-  css: { links: ['/styles/main.css'] },
-  target: 'node', // or 'edge'
-});
+3. Start development:
 
-console.log('Routes:', result.routes);
-console.log('Files:', result.files);
+```bash
+npx constela dev
 ```
 
-**BuildOptions:**
-- `outDir?: string` - Output directory (default: dist)
-- `routesDir?: string` - Pages directory
-- `publicDir?: string` - Static files directory
-- `layoutsDir?: string` - Layouts directory
-- `css?: { links?: string[] }` - CSS configuration
-- `target?: 'node' | 'edge'` - Build target
+Open http://localhost:3000 to see your app.
 
-### generateStaticPages
+## CLI Usage
 
-Generates static HTML pages for SSG.
+```bash
+# Development server
+npx constela dev --port 3000
 
-```typescript
-import { generateStaticPages } from '@constela/start';
+# Production build
+npx constela build --outDir dist
 
-const files = await generateStaticPages({
-  routesDir: 'src/routes',
-  outDir: 'dist',
-  layoutsDir: 'src/layouts',
-});
+# Start production server
+npx constela start --port 3000
 ```
 
-## File-Based Routing
-
-### scanRoutes
-
-Discovers routes from the file system.
-
-```typescript
-import { scanRoutes } from '@constela/start';
+## Project Structure
 
-const routes = await scanRoutes('src/routes');
-// [{ path: '/', file: 'index.json', type: 'page' }, ...]
+```
+project/
+  src/
+    routes/           # Page files (.json)
+      index.json      # / route
+      about.json      # /about route
+      users/
+        [id].json     # /users/:id route
+    layouts/          # Layout files
+      main.json
+      docs.json
+    components/       # Component files
+      header.json
+      footer.json
+    data/             # Data files
+      config.json
+      navigation.json
+  content/            # Content files (MDX)
+    blog/
+      *.mdx
+  public/             # Static assets
 ```
 
-**Routing Conventions:**
+## File-Based Routing
 
 | File | Route |
 |------|-------|
@@ -127,44 +96,13 @@ const routes = await scanRoutes('src/routes');
 | `about.json` | `/about` |
 | `users/[id].json` | `/users/:id` |
 | `docs/[...slug].json` | `/docs/*` |
-| `api/users.ts` | `/api/users` (API route) |
-| `_middleware.ts` | Middleware |
-
-### filePathToPattern
 
-Converts file paths to route patterns.
+## Data Sources
 
-```typescript
-import { filePathToPattern } from '@constela/start';
-
-filePathToPattern('users/[id].json'); // '/users/:id'
-filePathToPattern('docs/[...slug].json'); // '/docs/*'
-```
+Load data at build time:
 
-## Data Loading
+### Glob Pattern
 
-### DataLoader
-
-Loads data from various sources.
-
-```typescript
-import { DataLoader } from '@constela/start';
-
-const loader = new DataLoader('src/routes');
-
-// Glob pattern
-const posts = await loader.loadGlob('content/blog/*.mdx', 'mdx');
-
-// Single file
-const config = await loader.loadFile('data/config.json');
-
-// API endpoint
-const users = await loader.loadApi('https://api.example.com/users');
-```
-
-### Data Source Types
-
-**Glob Pattern:**
 ```json
 {
   "data": {
@@ -177,7 +115,8 @@ const users = await loader.loadApi('https://api.example.com/users');
 }
 ```
 
-**File:**
+### File
+
 ```json
 {
   "data": {
@@ -189,7 +128,8 @@ const users = await loader.loadApi('https://api.example.com/users');
 }
 ```
 
-**API:**
+### API
+
 ```json
 {
   "data": {
@@ -201,44 +141,54 @@ const users = await loader.loadApi('https://api.example.com/users');
 }
 ```
 
-### Transforms
+**Transforms:** `mdx`, `yaml`, `csv`
 
-- `mdx` - Markdown with JSX to Constela nodes
-- `yaml` - YAML to JSON
-- `csv` - CSV to array of objects
+## Layouts
 
-## MDX Support
+Define reusable layouts:
 
-### mdxToConstela
+```json
+{
+  "version": "1.0",
+  "type": "layout",
+  "state": {
+    "theme": { "type": "string", "initial": "light" }
+  },
+  "view": {
+    "kind": "element",
+    "tag": "div",
+    "children": [
+      { "kind": "component", "name": "Header" },
+      { "kind": "element", "tag": "main", "children": [{ "kind": "slot" }] },
+      { "kind": "component", "name": "Footer" }
+    ]
+  }
+}
+```
 
-Transforms MDX content to Constela view nodes.
+Use layout in pages:
 
-```typescript
-import { mdxToConstela } from '@constela/start';
-
-const result = await mdxToConstela(mdxContent, {
-  components: {
-    Callout: {
-      params: { type: { type: 'string' } },
-      view: { kind: 'element', tag: 'div', ... },
-    },
-  },
-});
+```json
+{
+  "route": {
+    "path": "/docs/:slug",
+    "layout": "docs",
+    "layoutParams": {
+      "title": { "expr": "data", "name": "doc", "path": "title" }
+    }
+  }
+}
 ```
 
-**Supported Markdown:**
-- Headings, paragraphs, emphasis, strong
-- Links, images, lists (ordered/unordered)
-- Blockquotes, tables (GFM)
-- Code blocks with language
-- Horizontal rules, line breaks
+**Named Slots:**
+
+```json
+{ "kind": "slot", "name": "sidebar" }
+```
 
-**MDX Extensions:**
-- JSX elements
-- Custom components (PascalCase)
-- Expression interpolation
+## Static Paths
 
-### Static Paths with MDX
+Generate static pages for dynamic routes:
 
 ```json
 {
@@ -261,215 +211,116 @@ const result = await mdxToConstela(mdxContent, {
 }
 ```
 
-## Layout System
+## MDX Support
 
-### LayoutResolver
+Markdown files with JSX components:
 
-Manages layout discovery and composition.
+```mdx
+---
+title: Getting Started
+---
 
-```typescript
-import { LayoutResolver } from '@constela/start';
+# Welcome
 
-const resolver = new LayoutResolver('src/layouts');
-await resolver.scan();
-
-if (resolver.has('docs')) {
-  const layout = await resolver.load('docs');
-}
+<Callout type="info">
+  This is an info callout.
+</Callout>
 ```
 
-### Layout Definition
-
-```json
-{
-  "version": "1.0",
-  "type": "layout",
-  "view": {
-    "kind": "element",
-    "tag": "div",
-    "children": [
-      { "kind": "component", "name": "Header" },
-      { "kind": "slot" },
-      { "kind": "component", "name": "Footer" }
-    ]
-  }
-}
-```
-
-**Named Slots:**
-```json
-{ "kind": "slot", "name": "sidebar" }
-```
+## Configuration
 
-### Page with Layout
+Create `constela.config.json`:
 
 ```json
 {
-  "route": {
-    "path": "/docs/:slug",
-    "layout": "docs",
-    "layoutParams": {
-      "title": { "expr": "data", "name": "doc", "path": "title" }
-    }
-  }
+  "adapter": "node",
+  "css": "src/styles/globals.css",
+  "layoutsDir": "src/layouts"
 }
 ```
 
-## API Routes
+**Adapters:** `cloudflare`, `vercel`, `deno`, `node`
 
-### createAPIHandler
+## Internal API
 
-Creates an API route handler.
+> For framework developers only. End users should use the CLI.
+
+### createDevServer
 
 ```typescript
-import { createAPIHandler } from '@constela/start';
+import { createDevServer } from '@constela/start';
 
-const handler = createAPIHandler({
-  GET: async (ctx) => {
-    return new Response(JSON.stringify({ users: [] }), {
-      headers: { 'Content-Type': 'application/json' },
-    });
-  },
-  POST: async (ctx) => {
-    const body = await ctx.request.json();
-    // ...
-  },
+const server = await createDevServer({
+  port: 3000,
+  routesDir: 'src/routes',
+  layoutsDir: 'src/layouts',
 });
 ```
 
-**APIContext:**
-```typescript
-interface APIContext {
-  params: Record<string, string>;
-  query: URLSearchParams;
-  request: Request;
-}
-```
-
-**Supported Methods:** GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS
-
-## Middleware
-
-### createMiddlewareChain
-
-Creates a middleware chain for request processing.
+### build
 
 ```typescript
-import { createMiddlewareChain } from '@constela/start';
-
-const chain = createMiddlewareChain([
-  async (ctx, next) => {
-    console.log('Request:', ctx.url);
-    const response = await next();
-    console.log('Response:', response.status);
-    return response;
-  },
-  async (ctx, next) => {
-    ctx.locals.user = await getUser(ctx.request);
-    return next();
-  },
-]);
-```
+import { build } from '@constela/start';
 
-**MiddlewareContext:**
-```typescript
-interface MiddlewareContext {
-  request: Request;
-  params: Record<string, string>;
-  url: URL;
-  locals: Record<string, unknown>;
-}
+const result = await build({
+  outDir: 'dist',
+  routesDir: 'src/routes',
+  target: 'node',
+});
 ```
 
-## Edge Adapters
-
-### createAdapter
-
-Creates an adapter for edge deployment.
+### DataLoader
 
 ```typescript
-import { createAdapter } from '@constela/start';
-
-const adapter = createAdapter({
-  platform: 'cloudflare', // or 'vercel', 'deno', 'node'
-  routes: scannedRoutes,
-  fallback: notFoundProgram,
-});
+import { DataLoader } from '@constela/start';
 
-// Cloudflare Workers
-export default {
-  fetch: adapter.fetch,
-};
+const loader = new DataLoader('src/routes');
+const posts = await loader.loadGlob('content/blog/*.mdx', 'mdx');
+const config = await loader.loadFile('data/config.json');
 ```
 
-**Platforms:**
-- `cloudflare` - Cloudflare Workers
-- `vercel` - Vercel Edge Functions
-- `deno` - Deno Deploy
-- `node` - Node.js
-
-## Page Types
-
-### Static Page
+### LayoutResolver
 
 ```typescript
-// pages/about.ts
-import type { CompiledProgram } from '@constela/compiler';
-
-const page: CompiledProgram = {
-  version: '1.0',
-  state: {},
-  actions: {},
-  view: { kind: 'element', tag: 'div', ... },
-};
+import { LayoutResolver } from '@constela/start';
 
-export default page;
+const resolver = new LayoutResolver('src/layouts');
+await resolver.scan();
+const layout = await resolver.load('docs');
 ```
 
-### Dynamic Page
+### API Routes
 
 ```typescript
-// pages/users/[id].ts
-import type { PageExportFunction, StaticPathsResult } from '@constela/start';
-
-export const getStaticPaths = async (): Promise<StaticPathsResult> => ({
-  paths: [
-    { params: { id: '1' } },
-    { params: { id: '2' } },
-  ],
-});
-
-const page: PageExportFunction = async (params) => {
-  const user = await fetchUser(params.id);
-  return compileUserPage(user);
+// src/routes/api/users.ts
+export const GET = async (ctx) => {
+  return new Response(JSON.stringify({ users: [] }), {
+    headers: { 'Content-Type': 'application/json' },
+  });
 };
-
-export default page;
 ```
 
-## Configuration
-
-### ConstelaConfig
+### Middleware
 
 ```typescript
-interface ConstelaConfig {
-  adapter?: 'cloudflare' | 'vercel' | 'deno' | 'node';
-  ssg?: {
-    routes?: string[];
-  };
-}
+// src/routes/_middleware.ts
+export default async (ctx, next) => {
+  console.log('Request:', ctx.url);
+  return next();
+};
 ```
 
-## Exports
-
-### Runtime Entry Points
+### Edge Adapters
 
 ```typescript
-// Client-side hydration
-import '@constela/start/client';
+import { createAdapter } from '@constela/start';
+
+const adapter = createAdapter({
+  platform: 'cloudflare',
+  routes: scannedRoutes,
+});
 
-// Server-side rendering
-import { render } from '@constela/start/server';
+export default { fetch: adapter.fetch };
 ```
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constela/start",
-  "version": "1.2.23",
+  "version": "1.2.24",
   "description": "Meta-framework for Constela applications",
   "type": "module",
   "main": "./dist/index.js",
@@ -43,11 +43,11 @@
     "postcss": "^8.5.0",
     "@tailwindcss/postcss": "^4.0.0",
     "tailwindcss": "^4.0.0",
-    "@constela/compiler": "0.7.1",
-    "@constela/core": "0.7.0",
-    "@constela/runtime": "0.10.3",
-    "@constela/server": "3.0.1",
-    "@constela/router": "8.0.0"
+    "@constela/compiler": "0.8.0",
+    "@constela/core": "0.8.0",
+    "@constela/server": "4.0.0",
+    "@constela/runtime": "0.11.0",
+    "@constela/router": "9.0.0"
   },
   "devDependencies": {
     "@types/mdast": "^4.0.4",