@ereo/router-conventions 0.1.6

package/README.md

@@ -0,0 +1,103 @@
+# @ereo/router-conventions
+
+File-based routing conventions for the EreoJS framework. Automatically configure routes based on filename patterns, enabling intuitive and powerful file-based routing.
+
+## Installation
+
+```bash
+bun add @ereo/router-conventions
+```
+
+## Quick Start
+
+```typescript
+import { parseConvention, applyConventionConfig } from '@ereo/router-conventions';
+
+// Parse a filename to extract convention info
+const info = parseConvention('blog/[slug].ssg.tsx');
+// => { basePath: 'blog/[slug]', renderMode: 'ssg', isApi: false, ... }
+
+// Apply convention-based configuration to a route
+const config = applyConventionConfig('blog/[slug].ssg.tsx');
+// => { render: { mode: 'ssg', prerender: { enabled: true } }, ... }
+```
+
+## Convention Patterns
+
+Use filename suffixes to configure route behavior:
+
+| Pattern | Description |
+|---------|-------------|
+| `*.ssg.tsx` | Static Site Generation (pre-rendered at build time) |
+| `*.server.tsx` | Server-side only (no client JavaScript) |
+| `*.client.tsx` | Client-side rendering only |
+| `*.api.tsx` | API endpoint (JSON response) |
+| `*.rsc.tsx` | React Server Component |
+| `_islands/*.tsx` | Auto-extracted island components |
+| `_layout.tsx` | Nested layout wrapper |
+
+## Examples
+
+```
+app/routes/
+  index.tsx              # SSR (default)
+  about.server.tsx       # Server-only, no hydration
+  blog/
+    index.tsx            # SSR blog list
+    [slug].ssg.tsx       # Static blog posts
+  api/
+    posts.api.tsx        # JSON API endpoint
+  _islands/
+    Counter.tsx          # Auto-hydrated island
+```
+
+## API
+
+### `parseConvention(filename)`
+
+Parse a filename to extract convention information.
+
+```typescript
+const info = parseConvention('posts/[id].ssg.tsx');
+// {
+//   basePath: 'posts/[id]',
+//   renderMode: 'ssg',
+//   isApi: false,
+//   isIsland: false,
+//   isLayout: false,
+//   filename: 'posts/[id].ssg.tsx',
+//   extension: '.tsx'
+// }
+```
+
+### `applyConventionConfig(routePath, explicitConfig?)`
+
+Apply convention-based configuration, merging with explicit config.
+
+### `hasConvention(filename)`
+
+Check if a filename uses any convention pattern.
+
+### `stripConvention(routePath)`
+
+Remove convention suffix from a route path for URL generation.
+
+## Key Features
+
+- Automatic render mode detection from filenames
+- Support for SSG, SSR, CSR, API, and RSC modes
+- Island component detection
+- Layout file recognition
+- Seamless integration with EreoJS router
+
+## Documentation
+
+For full documentation, visit [https://ereo.dev/docs/router-conventions](https://ereo.dev/docs/router-conventions)
+
+## Part of EreoJS
+
+This package is part of the [EreoJS monorepo](https://github.com/anthropics/ereo-js).
+
+## License
+
+MIT

package/dist/conventions.d.ts

@@ -0,0 +1,66 @@
+/**
+ * @ereo/router-conventions - File naming convention parser
+ *
+ * Parses file names to determine route configuration:
+ * - [slug].ssg.tsx -> SSG mode
+ * - [slug].server.tsx -> Server-only, no hydration
+ * - [slug].client.tsx -> CSR only
+ * - [slug].api.tsx -> API endpoint
+ * - _islands/*.tsx -> Auto-extracted islands
+ */
+import type { RenderMode, RouteConfig } from '@ereo/core';
+/** Convention suffixes and their render modes */
+export declare const CONVENTION_SUFFIXES: Record<string, RenderMode | 'api'>;
+/** Parsed convention info from a filename */
+export interface ConventionInfo {
+    /** Base route path (without convention suffix) */
+    basePath: string;
+    /** Detected render mode from convention */
+    renderMode?: RenderMode;
+    /** Whether this is an API route */
+    isApi: boolean;
+    /** Whether this is an island component */
+    isIsland: boolean;
+    /** Whether this is a layout file */
+    isLayout: boolean;
+    /** Original filename */
+    filename: string;
+    /** File extension */
+    extension: string;
+}
+/**
+ * Parse a filename to extract convention information.
+ *
+ * @example
+ * parseConvention('blog/[slug].ssg.tsx')
+ * // => { basePath: 'blog/[slug]', renderMode: 'ssg', isApi: false, ... }
+ *
+ * parseConvention('_islands/Counter.tsx')
+ * // => { basePath: '_islands/Counter', isIsland: true, ... }
+ */
+export declare function parseConvention(filename: string): ConventionInfo;
+/**
+ * Generate route configuration from convention info.
+ */
+export declare function conventionToRouteConfig(info: ConventionInfo): Partial<RouteConfig>;
+/**
+ * Check if a filename matches a convention pattern.
+ */
+export declare function hasConvention(filename: string): boolean;
+/**
+ * Get all supported convention patterns for documentation.
+ */
+export declare function getConventionPatterns(): string[];
+/**
+ * Strip convention suffix from route path for URL generation.
+ *
+ * @example
+ * stripConvention('blog/[slug].ssg') // => 'blog/[slug]'
+ */
+export declare function stripConvention(routePath: string): string;
+/**
+ * Apply convention-based configuration to a route.
+ * This merges convention config with explicit config exports.
+ */
+export declare function applyConventionConfig(routePath: string, explicitConfig?: Partial<RouteConfig>): Partial<RouteConfig>;
+//# sourceMappingURL=conventions.d.ts.map

package/dist/conventions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conventions.d.ts","sourceRoot":"","sources":["../src/conventions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE1D,iDAAiD;AACjD,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,KAAK,CAMlE,CAAC;AAEF,6CAA6C;AAC7C,MAAM,WAAW,cAAc;IAC7B,kDAAkD;IAClD,QAAQ,EAAE,MAAM,CAAC;IACjB,2CAA2C;IAC3C,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,mCAAmC;IACnC,KAAK,EAAE,OAAO,CAAC;IACf,0CAA0C;IAC1C,QAAQ,EAAE,OAAO,CAAC;IAClB,oCAAoC;IACpC,QAAQ,EAAE,OAAO,CAAC;IAClB,wBAAwB;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,qBAAqB;IACrB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,CAsChE;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,WAAW,CAAC,CAsClF;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAGvD;AAED;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,EAAE,CAUhD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAOzD;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,MAAM,EACjB,cAAc,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GACpC,OAAO,CAAC,WAAW,CAAC,CAatB"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @ereo/router-conventions - Main exports
+ */
+export { parseConvention, conventionToRouteConfig, hasConvention, stripConvention, applyConventionConfig, getConventionPatterns, CONVENTION_SUFFIXES, } from './conventions';
+export type { ConventionInfo, } from './conventions';
+export { integrateConventions } from './integration';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,eAAe,EACf,uBAAuB,EACvB,aAAa,EACb,eAAe,EACf,qBAAqB,EACrB,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,eAAe,CAAC;AAEvB,YAAY,EACV,cAAc,GACf,MAAM,eAAe,CAAC;AAGvB,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,128 @@
+// @bun
+// src/conventions.ts
+var CONVENTION_SUFFIXES = {
+  ".ssg": "ssg",
+  ".server": "ssr",
+  ".client": "csr",
+  ".api": "api",
+  ".rsc": "rsc"
+};
+function parseConvention(filename) {
+  const lastDot = filename.lastIndexOf(".");
+  const extension = lastDot >= 0 ? filename.slice(lastDot) : "";
+  const nameWithoutExt = lastDot >= 0 ? filename.slice(0, lastDot) : filename;
+  const isIsland = filename.includes("/_islands/") || filename.startsWith("_islands/");
+  const isLayout = nameWithoutExt.endsWith("/_layout") || nameWithoutExt === "_layout";
+  let basePath = nameWithoutExt;
+  let renderMode;
+  let isApi = false;
+  for (const [suffix, mode] of Object.entries(CONVENTION_SUFFIXES)) {
+    if (nameWithoutExt.endsWith(suffix)) {
+      basePath = nameWithoutExt.slice(0, -suffix.length);
+      if (mode === "api") {
+        isApi = true;
+      } else {
+        renderMode = mode;
+      }
+      break;
+    }
+  }
+  return {
+    basePath,
+    renderMode,
+    isApi,
+    isIsland,
+    isLayout,
+    filename,
+    extension
+  };
+}
+function conventionToRouteConfig(info) {
+  const config = {};
+  if (info.renderMode) {
+    config.render = {
+      mode: info.renderMode,
+      streaming: { enabled: info.renderMode === "ssr" }
+    };
+    if (info.renderMode === "ssg") {
+      config.render.prerender = {
+        enabled: true,
+        fallback: "blocking"
+      };
+    }
+    if (info.renderMode === "ssr" && info.filename.includes(".server.")) {
+      config.islands = { disabled: true, defaultStrategy: "none" };
+    }
+  }
+  if (info.isApi) {
+    config.render = { mode: "json" };
+  }
+  if (info.isIsland) {
+    config.islands = {
+      defaultStrategy: "load",
+      ...config.islands
+    };
+  }
+  return config;
+}
+function hasConvention(filename) {
+  const info = parseConvention(filename);
+  return !!info.renderMode || info.isApi || info.isIsland;
+}
+function getConventionPatterns() {
+  return [
+    "*.ssg.tsx - Static Site Generation (pre-rendered at build)",
+    "*.server.tsx - Server-side only (no client JavaScript)",
+    "*.client.tsx - Client-side rendering only",
+    "*.api.tsx - API endpoint (JSON response)",
+    "*.rsc.tsx - React Server Component",
+    "_islands/*.tsx - Auto-extracted island components",
+    "_layout.tsx - Nested layout wrapper"
+  ];
+}
+function stripConvention(routePath) {
+  for (const suffix of Object.keys(CONVENTION_SUFFIXES)) {
+    if (routePath.endsWith(suffix)) {
+      return routePath.slice(0, -suffix.length);
+    }
+  }
+  return routePath;
+}
+function applyConventionConfig(routePath, explicitConfig) {
+  const info = parseConvention(routePath);
+  const conventionConfig = conventionToRouteConfig(info);
+  return {
+    ...conventionConfig,
+    ...explicitConfig,
+    render: explicitConfig?.render ?? conventionConfig.render,
+    islands: explicitConfig?.islands ?? conventionConfig.islands,
+    cache: explicitConfig?.cache ?? conventionConfig.cache
+  };
+}
+// src/integration.ts
+function integrateConventions(routes, options = {}) {
+  const { enabled = true } = options;
+  if (!enabled) {
+    return routes;
+  }
+  return routes.map((route) => {
+    const conventionConfig = applyConventionConfig(route.file, route.config);
+    return {
+      ...route,
+      config: {
+        ...route.config,
+        ...conventionConfig
+      }
+    };
+  });
+}
+export {
+  stripConvention,
+  parseConvention,
+  integrateConventions,
+  hasConvention,
+  getConventionPatterns,
+  conventionToRouteConfig,
+  applyConventionConfig,
+  CONVENTION_SUFFIXES
+};

package/dist/integration.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @ereo/router-conventions - Integration with file router
+ *
+ * Integrates convention-based routing with the file router system.
+ */
+import type { Route } from '@ereo/core';
+/**
+ * Options for integrating conventions with the router.
+ */
+export interface ConventionIntegrationOptions {
+    /** Enable convention parsing (default: true) */
+    enabled?: boolean;
+    /** Custom convention suffixes to add */
+    customSuffixes?: Record<string, string>;
+    /** Directories to scan for islands */
+    islandDirs?: string[];
+}
+/**
+ * Integrate conventions with discovered routes.
+ * This transforms route configs based on filename conventions.
+ */
+export declare function integrateConventions(routes: Route[], options?: ConventionIntegrationOptions): Route[];
+/**
+ * Generate route ID from convention info.
+ * Strips convention suffixes for cleaner route IDs.
+ */
+export declare function generateRouteId(filePath: string): string;
+/**
+ * Check if a route should be treated as an API route.
+ */
+export declare function isApiRoute(filePath: string): boolean;
+/**
+ * Check if a route should be treated as an island component.
+ */
+export declare function isIslandComponent(filePath: string): boolean;
+/**
+ * Get the effective render mode for a route file.
+ */
+export declare function getEffectiveRenderMode(filePath: string, explicitMode?: string): string;
+//# sourceMappingURL=integration.d.ts.map

package/dist/integration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"integration.d.ts","sourceRoot":"","sources":["../src/integration.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAGxC;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC3C,gDAAgD;IAChD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,wCAAwC;IACxC,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,sCAAsC;IACtC,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,KAAK,EAAE,EACf,OAAO,GAAE,4BAAiC,GACzC,KAAK,EAAE,CAkBT;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGxD;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAGpD;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAG3D;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,MAAM,EAChB,YAAY,CAAC,EAAE,MAAM,GACpB,MAAM,CAaR"}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@ereo/router-conventions",
+  "version": "0.1.6",
+  "license": "MIT",
+  "author": "Ereo Team",
+  "homepage": "https://ereo.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ereojs/ereo.git",
+    "directory": "packages/router-conventions"
+  },
+  "bugs": {
+    "url": "https://github.com/ereojs/ereo/issues"
+  },
+  "description": "File-based routing conventions for EreoJS framework",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --target bun --external @ereo/core --external @ereo/router && bun run build:types",
+    "build:types": "tsc --emitDeclarationOnly --outDir dist",
+    "dev": "bun build ./src/index.ts --outdir ./dist --target bun --watch",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@ereo/core": "workspace:*",
+    "@ereo/router": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.1.0",
+    "typescript": "^5.4.0"
+  }
+}