@constela/start 1.2.1 → 1.2.3

package/README.md

@@ -0,0 +1,477 @@
+# @constela/start
+
+Meta-framework for Constela applications with dev server, build tools, and SSG.
+
+## Installation
+
+```bash
+npm install @constela/start
+```
+
+## Overview
+
+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
+
+```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
+```
+
+## API Reference
+
+### createDevServer
+
+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'],
+  },
+});
+```
+
+**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'
+});
+
+console.log('Routes:', result.routes);
+console.log('Files:', result.files);
+```
+
+**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
+
+### generateStaticPages
+
+Generates static HTML pages for SSG.
+
+```typescript
+import { generateStaticPages } from '@constela/start';
+
+const files = await generateStaticPages({
+  routesDir: 'src/routes',
+  outDir: 'dist',
+  layoutsDir: 'src/layouts',
+});
+```
+
+## File-Based Routing
+
+### scanRoutes
+
+Discovers routes from the file system.
+
+```typescript
+import { scanRoutes } from '@constela/start';
+
+const routes = await scanRoutes('src/routes');
+// [{ path: '/', file: 'index.json', type: 'page' }, ...]
+```
+
+**Routing Conventions:**
+
+| File | Route |
+|------|-------|
+| `index.json` | `/` |
+| `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.
+
+```typescript
+import { filePathToPattern } from '@constela/start';
+
+filePathToPattern('users/[id].json'); // '/users/:id'
+filePathToPattern('docs/[...slug].json'); // '/docs/*'
+```
+
+## Data Loading
+
+### 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": {
+    "posts": {
+      "type": "glob",
+      "pattern": "content/blog/*.mdx",
+      "transform": "mdx"
+    }
+  }
+}
+```
+
+**File:**
+```json
+{
+  "data": {
+    "config": {
+      "type": "file",
+      "path": "data/config.json"
+    }
+  }
+}
+```
+
+**API:**
+```json
+{
+  "data": {
+    "users": {
+      "type": "api",
+      "url": "https://api.example.com/users"
+    }
+  }
+}
+```
+
+### Transforms
+
+- `mdx` - Markdown with JSX to Constela nodes
+- `yaml` - YAML to JSON
+- `csv` - CSV to array of objects
+
+## MDX Support
+
+### mdxToConstela
+
+Transforms MDX content to Constela view nodes.
+
+```typescript
+import { mdxToConstela } from '@constela/start';
+
+const result = await mdxToConstela(mdxContent, {
+  components: {
+    Callout: {
+      params: { type: { type: 'string' } },
+      view: { kind: 'element', tag: 'div', ... },
+    },
+  },
+});
+```
+
+**Supported Markdown:**
+- Headings, paragraphs, emphasis, strong
+- Links, images, lists (ordered/unordered)
+- Blockquotes, tables (GFM)
+- Code blocks with language
+- Horizontal rules, line breaks
+
+**MDX Extensions:**
+- JSX elements
+- Custom components (PascalCase)
+- Expression interpolation
+
+### Static Paths with MDX
+
+```json
+{
+  "data": {
+    "docs": {
+      "type": "glob",
+      "pattern": "content/docs/*.mdx",
+      "transform": "mdx"
+    }
+  },
+  "route": {
+    "path": "/docs/:slug",
+    "getStaticPaths": {
+      "source": "docs",
+      "params": {
+        "slug": { "expr": "get", "base": { "expr": "var", "name": "item" }, "path": "slug" }
+      }
+    }
+  }
+}
+```
+
+## Layout System
+
+### LayoutResolver
+
+Manages layout discovery and composition.
+
+```typescript
+import { LayoutResolver } from '@constela/start';
+
+const resolver = new LayoutResolver('src/layouts');
+await resolver.scan();
+
+if (resolver.has('docs')) {
+  const layout = await resolver.load('docs');
+}
+```
+
+### 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" }
+```
+
+### Page with Layout
+
+```json
+{
+  "route": {
+    "path": "/docs/:slug",
+    "layout": "docs",
+    "layoutParams": {
+      "title": { "expr": "data", "name": "doc", "path": "title" }
+    }
+  }
+}
+```
+
+## API Routes
+
+### createAPIHandler
+
+Creates an API route handler.
+
+```typescript
+import { createAPIHandler } 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();
+    // ...
+  },
+});
+```
+
+**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.
+
+```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();
+  },
+]);
+```
+
+**MiddlewareContext:**
+```typescript
+interface MiddlewareContext {
+  request: Request;
+  params: Record<string, string>;
+  url: URL;
+  locals: Record<string, unknown>;
+}
+```
+
+## Edge Adapters
+
+### createAdapter
+
+Creates an adapter for edge deployment.
+
+```typescript
+import { createAdapter } from '@constela/start';
+
+const adapter = createAdapter({
+  platform: 'cloudflare', // or 'vercel', 'deno', 'node'
+  routes: scannedRoutes,
+  fallback: notFoundProgram,
+});
+
+// Cloudflare Workers
+export default {
+  fetch: adapter.fetch,
+};
+```
+
+**Platforms:**
+- `cloudflare` - Cloudflare Workers
+- `vercel` - Vercel Edge Functions
+- `deno` - Deno Deploy
+- `node` - Node.js
+
+## Page Types
+
+### Static Page
+
+```typescript
+// pages/about.ts
+import type { CompiledProgram } from '@constela/compiler';
+
+const page: CompiledProgram = {
+  version: '1.0',
+  state: {},
+  actions: {},
+  view: { kind: 'element', tag: 'div', ... },
+};
+
+export default page;
+```
+
+### Dynamic Page
+
+```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);
+};
+
+export default page;
+```
+
+## Configuration
+
+### ConstelaConfig
+
+```typescript
+interface ConstelaConfig {
+  adapter?: 'cloudflare' | 'vercel' | 'deno' | 'node';
+  ssg?: {
+    routes?: string[];
+  };
+}
+```
+
+## Exports
+
+### Runtime Entry Points
+
+```typescript
+// Client-side hydration
+import '@constela/start/client';
+
+// Server-side rendering
+import { render } from '@constela/start/server';
+```
+
+## License
+
+MIT

package/dist/{chunk-6AN7W7KZ.js → chunk-U6CTMEFX.js}

@@ -1880,7 +1880,7 @@ import { analyzeLayoutPass, transformLayoutPass, composeLayoutWithPage } from "@
 var DEFAULT_PORT = 3e3;
 var DEFAULT_HOST = "localhost";
 var DEFAULT_PUBLIC_DIR = "public";
-var DEFAULT_ROUTES_DIR = "src/pages";
+var DEFAULT_ROUTES_DIR = "src/routes";
 function matchRoute(url, routes) {
   const normalizedUrl = url === "/" ? "/" : url.replace(/\/$/, "");
   const urlSegments = normalizedUrl.split("/").filter(Boolean);
@@ -2001,7 +2001,7 @@ async function createDevServer(options = {}) {
       return actualPort;
     },
     async listen() {
-      return new Promise((resolve4, reject) => {
+      return new Promise((resolve5, reject) => {
         httpServer = createServer(async (req, res) => {
           const url = new URL(req.url ?? "/", `http://${req.headers.host}`);
           const pathname = url.pathname;
@@ -2138,7 +2138,7 @@ h1 { color: #666; }
           if (address) {
             actualPort = address.port;
           }
-          resolve4();
+          resolve5();
         });
       });
     },
@@ -2147,9 +2147,9 @@ h1 { color: #666; }
         await viteServer.close();
         viteServer = null;
       }
-      return new Promise((resolve4, reject) => {
+      return new Promise((resolve5, reject) => {
         if (!httpServer) {
-          resolve4();
+          resolve5();
           return;
         }
         httpServer.closeAllConnections();
@@ -2158,7 +2158,7 @@ h1 { color: #666; }
             reject(err);
           } else {
             httpServer = null;
-            resolve4();
+            resolve5();
           }
         });
       });
@@ -2170,7 +2170,7 @@ h1 { color: #666; }
 // src/build/index.ts
 import { existsSync as existsSync7, readFileSync as readFileSync5 } from "fs";
 import { mkdir as mkdir2, writeFile, cp, readdir } from "fs/promises";
-import { join as join9, dirname as dirname5, relative as relative2, basename as basename4 } from "path";
+import { join as join9, dirname as dirname5, relative as relative2, basename as basename4, isAbsolute as isAbsolute2, resolve as resolve4 } from "path";
 
 // src/build/bundler.ts
 import * as esbuild from "esbuild";
@@ -2207,6 +2207,7 @@ async function bundleRuntime(options) {
 }
 
 // src/build/index.ts
+var DEFAULT_PUBLIC_DIR2 = "public";
 function isDynamicRoute(pattern) {
   return pattern.includes(":") || pattern.includes("*");
 }
@@ -2440,7 +2441,7 @@ function validateJsonPage(content, filePath) {
 async function build2(options) {
   const outDir = options?.outDir ?? "dist";
   const routesDir = options?.routesDir ?? "src/routes";
-  const publicDir = options?.publicDir;
+  const publicDir = options?.publicDir ?? DEFAULT_PUBLIC_DIR2;
   const layoutsDir = options?.layoutsDir;
   const generatedFiles = [];
   await mkdir2(outDir, { recursive: true });
@@ -2470,8 +2471,11 @@ async function build2(options) {
     };
   }
   const runtimePath = await bundleRuntime({ outDir });
+  const absoluteRoutesDir = isAbsolute2(routesDir) ? routesDir : resolve4(routesDir);
+  const projectRoot = dirname5(dirname5(absoluteRoutesDir));
   for (const route of jsonPages) {
-    const relPath = relative2(routesDir, route.file);
+    const relPathFromRoutesDir = relative2(absoluteRoutesDir, route.file);
+    const relPathFromProjectRoot = relative2(projectRoot, route.file);
     const content = readFileSync5(route.file, "utf-8");
     const page = validateJsonPage(content, route.file);
     if (isDynamicRoute(route.pattern)) {
@@ -2485,8 +2489,8 @@ async function build2(options) {
       for (const pathEntry of staticPaths.paths) {
         const params = pathEntry.params;
         const outputPath = paramsToOutputPath(route.pattern, params, outDir);
-        const loader = new JsonPageLoader(routesDir);
-        let pageInfo = await loader.loadPage(relPath);
+        const loader = new JsonPageLoader(projectRoot);
+        let pageInfo = await loader.loadPage(relPathFromProjectRoot);
         if (layoutsDir) {
           pageInfo = await processLayouts(pageInfo, layoutsDir);
         }
@@ -2503,9 +2507,9 @@ async function build2(options) {
         routes.push(routePath);
       }
     } else {
-      const outputPath = getOutputPath(relPath, outDir);
-      const loader = new JsonPageLoader(routesDir);
-      let pageInfo = await loader.loadPage(relPath);
+      const outputPath = getOutputPath(relPathFromRoutesDir, outDir);
+      const loader = new JsonPageLoader(projectRoot);
+      let pageInfo = await loader.loadPage(relPathFromProjectRoot);
       if (layoutsDir) {
         pageInfo = await processLayouts(pageInfo, layoutsDir);
       }
@@ -2527,6 +2531,47 @@ async function build2(options) {
   };
 }
 
+// src/config/config-loader.ts
+import { existsSync as existsSync8, readFileSync as readFileSync6 } from "fs";
+import { join as join10 } from "path";
+var CONFIG_FILENAME = "constela.config.json";
+async function loadConfig(projectRoot) {
+  const configPath = join10(projectRoot, CONFIG_FILENAME);
+  if (!existsSync8(configPath)) {
+    return {};
+  }
+  let content;
+  try {
+    content = readFileSync6(configPath, "utf-8");
+  } catch (error) {
+    throw new Error(`Failed to read config file: ${configPath}`);
+  }
+  try {
+    return JSON.parse(content);
+  } catch {
+    throw new Error(`Invalid JSON in config file: ${configPath}`);
+  }
+}
+async function resolveConfig(fileConfig, cliOptions) {
+  if (!cliOptions) {
+    return { ...fileConfig };
+  }
+  const result = { ...fileConfig };
+  if (cliOptions.css !== void 0) result.css = cliOptions.css;
+  if (cliOptions.layoutsDir !== void 0) result.layoutsDir = cliOptions.layoutsDir;
+  if (cliOptions.routesDir !== void 0) result.routesDir = cliOptions.routesDir;
+  if (cliOptions.publicDir !== void 0) result.publicDir = cliOptions.publicDir;
+  if (cliOptions.outDir !== void 0) {
+    result.build = { ...result.build, outDir: cliOptions.outDir };
+  }
+  if (cliOptions.port !== void 0 || cliOptions.host !== void 0) {
+    result.dev = { ...result.dev };
+    if (cliOptions.port !== void 0) result.dev.port = cliOptions.port;
+    if (cliOptions.host !== void 0) result.dev.host = cliOptions.host;
+  }
+  return result;
+}
+
 export {
   filePathToPattern,
   scanRoutes,
@@ -2549,5 +2594,7 @@ export {
   loadLayout,
   LayoutResolver,
   createDevServer,
-  build2 as build
+  build2 as build,
+  loadConfig,
+  resolveConfig
 };

package/dist/cli/index.js

@@ -1,54 +1,13 @@
 import {
   build,
-  createDevServer
-} from "../chunk-6AN7W7KZ.js";
+  createDevServer,
+  loadConfig,
+  resolveConfig
+} from "../chunk-U6CTMEFX.js";
 import "../chunk-PUTC5BCP.js";
 
 // src/cli/index.ts
 import { Command } from "commander";
-
-// src/config/config-loader.ts
-import { existsSync, readFileSync } from "fs";
-import { join } from "path";
-var CONFIG_FILENAME = "constela.config.json";
-async function loadConfig(projectRoot) {
-  const configPath = join(projectRoot, CONFIG_FILENAME);
-  if (!existsSync(configPath)) {
-    return {};
-  }
-  let content;
-  try {
-    content = readFileSync(configPath, "utf-8");
-  } catch (error) {
-    throw new Error(`Failed to read config file: ${configPath}`);
-  }
-  try {
-    return JSON.parse(content);
-  } catch {
-    throw new Error(`Invalid JSON in config file: ${configPath}`);
-  }
-}
-async function resolveConfig(fileConfig, cliOptions) {
-  if (!cliOptions) {
-    return { ...fileConfig };
-  }
-  const result = { ...fileConfig };
-  if (cliOptions.css !== void 0) result.css = cliOptions.css;
-  if (cliOptions.layoutsDir !== void 0) result.layoutsDir = cliOptions.layoutsDir;
-  if (cliOptions.routesDir !== void 0) result.routesDir = cliOptions.routesDir;
-  if (cliOptions.publicDir !== void 0) result.publicDir = cliOptions.publicDir;
-  if (cliOptions.outDir !== void 0) {
-    result.build = { ...result.build, outDir: cliOptions.outDir };
-  }
-  if (cliOptions.port !== void 0 || cliOptions.host !== void 0) {
-    result.dev = { ...result.dev };
-    if (cliOptions.port !== void 0) result.dev.port = cliOptions.port;
-    if (cliOptions.host !== void 0) result.dev.host = cliOptions.host;
-  }
-  return result;
-}
-
-// src/cli/index.ts
 var devHandler = async (options) => {
   const port = parseInt(options.port, 10);
   const host = options.host ?? "localhost";

package/dist/index.d.ts

@@ -522,4 +522,35 @@ declare class DataLoader {
     getCacheSize(): number;
 }
 
-export { type APIContext, type APIModule, type BuildOptions, type ComponentDef$1 as ComponentDef, type ConstelaConfig, DataLoader, type DevServerOptions, type GenerateStaticPagesOptions, type GlobResult, type LayoutInfo, LayoutResolver, type MDXToConstelaOptions, type MdxGlobResult, type Middleware, type MiddlewareContext, type MiddlewareNext, type PageExportFunction, type PageModule, type ScannedLayout, type ScannedRoute, type StaticFileResult, type StaticPath, type StaticPathEntry, type StaticPathsProvider, type StaticPathsResult, build, createAPIHandler, createAdapter, createDevServer, createMiddlewareChain, filePathToPattern, generateStaticPages, generateStaticPaths, getMimeType, isPageExportFunction, isPathSafe, loadApi, loadComponentDefinitions, loadFile, loadGlob, loadLayout, mdxContentToNode, mdxToConstela, resolveLayout, resolvePageExport, resolveStaticFile, scanLayouts, scanRoutes, transformCsv, transformMdx, transformYaml };
+interface ConstelaConfigFile {
+    css?: string | string[];
+    layoutsDir?: string;
+    routesDir?: string;
+    publicDir?: string;
+    build?: {
+        outDir?: string;
+    };
+    dev?: {
+        port?: number;
+        host?: string;
+    };
+}
+interface CLIOptions {
+    css?: string | undefined;
+    layoutsDir?: string | undefined;
+    routesDir?: string | undefined;
+    publicDir?: string | undefined;
+    outDir?: string | undefined;
+    port?: number | undefined;
+    host?: string | undefined;
+}
+/**
+ * Load config from constela.config.json in project root
+ */
+declare function loadConfig(projectRoot: string): Promise<ConstelaConfigFile>;
+/**
+ * Merge file config with CLI options (CLI takes precedence)
+ */
+declare function resolveConfig(fileConfig: ConstelaConfigFile, cliOptions?: CLIOptions): Promise<ConstelaConfigFile>;
+
+export { type APIContext, type APIModule, type BuildOptions, type CLIOptions, type ComponentDef$1 as ComponentDef, type ConstelaConfig, type ConstelaConfigFile, DataLoader, type DevServerOptions, type GenerateStaticPagesOptions, type GlobResult, type LayoutInfo, LayoutResolver, type MDXToConstelaOptions, type MdxGlobResult, type Middleware, type MiddlewareContext, type MiddlewareNext, type PageExportFunction, type PageModule, type ScannedLayout, type ScannedRoute, type StaticFileResult, type StaticPath, type StaticPathEntry, type StaticPathsProvider, type StaticPathsResult, build, createAPIHandler, createAdapter, createDevServer, createMiddlewareChain, filePathToPattern, generateStaticPages, generateStaticPaths, getMimeType, isPageExportFunction, isPathSafe, loadApi, loadComponentDefinitions, loadConfig, loadFile, loadGlob, loadLayout, mdxContentToNode, mdxToConstela, resolveConfig, resolveLayout, resolvePageExport, resolveStaticFile, scanLayouts, scanRoutes, transformCsv, transformMdx, transformYaml };

package/dist/index.js

@@ -9,11 +9,13 @@ import {
   isPathSafe,
   loadApi,
   loadComponentDefinitions,
+  loadConfig,
   loadFile,
   loadGlob,
   loadLayout,
   mdxContentToNode,
   mdxToConstela,
+  resolveConfig,
   resolveLayout,
   resolveStaticFile,
   scanLayouts,
@@ -21,7 +23,7 @@ import {
   transformCsv,
   transformMdx,
   transformYaml
-} from "./chunk-6AN7W7KZ.js";
+} from "./chunk-U6CTMEFX.js";
 import {
   generateHydrationScript,
   renderPage,
@@ -332,11 +334,13 @@ export {
   isPathSafe,
   loadApi,
   loadComponentDefinitions,
+  loadConfig,
   loadFile,
   loadGlob,
   loadLayout,
   mdxContentToNode,
   mdxToConstela,
+  resolveConfig,
   resolveLayout,
   resolvePageExport,
   resolveStaticFile,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constela/start",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "description": "Meta-framework for Constela applications",
   "type": "module",
   "main": "./dist/index.js",
@@ -41,10 +41,10 @@
     "unified": "^11.0.0",
     "vite": "^6.0.0",
     "@constela/compiler": "0.7.0",
-    "@constela/router": "8.0.0",
-    "@constela/runtime": "0.10.1",
     "@constela/core": "0.7.0",
-    "@constela/server": "3.0.0"
+    "@constela/server": "3.0.0",
+    "@constela/router": "8.0.0",
+    "@constela/runtime": "0.10.1"
   },
   "devDependencies": {
     "@types/mdast": "^4.0.4",