create-lumen 2.0.0-alpha.1 → 2.0.0-beta.1

package/templates/conditional/next/font/src/pages/_document.tsx

@@ -0,0 +1,18 @@
+import { Html, Head, Main, NextScript } from "next/document";
+
+/**
+ * Pages Router Custom Document.
+ * Note: Per Next.js compiler specifications, next/font loaders are configured
+ * in pages/_app to avoid the 'Cannot be used within pages/_document' compile error.
+ */
+export default function Document() {
+  return (
+    <Html lang="en">
+      <Head />
+      <body className="antialiased">
+        <Main />
+        <NextScript />
+      </body>
+    </Html>
+  );
+}

package/templates/conditional/next/image/BUILD_SIZE_NOTE.md

@@ -0,0 +1,15 @@
+# next/image Build Size and Performance Impact
+
+## Built-In Optimization
+`next/image` extends standard HTML `<img>` elements with automatic visual stability and performance optimizations:
+1. **Zero Cumulative Layout Shift (CLS)**: Enforces explicit `width` and `height` dimensions or fills the parent container with `fill`, reserving geometric space before the bitmap payload loads.
+2. **Modern Format Negotiation**: Serves WebP and AVIF modern formats dynamically when supported by the requesting browser, yielding 30–50% bandwidth reduction compared to legacy JPEG/PNG.
+3. **Native Lazy Loading**: Viewport-aware on-demand loading so off-screen images do not delay initial page interactivity. The `priority` property allows opting into preloading for Largest Contentful Paint (LCP) elements.
+
+## Bundle Footprint
+- **Runtime JavaScript Overhead**: ~5 KB gzipped client-side runtime handling IntersectionObserver and responsive `srcSet` generation.
+- **Build Impact**: Zero additional build time overhead during static compilation when referencing local SVGs or remote URLs; image transformations are handled on-demand by the Next.js server image optimizer.
+
+## Router Parity
+- **App Router**: Fully compatible with both Server Components (static rendering) and Client Components (`"use client"`).
+- **Pages Router**: Fully compatible with all page and component hierarchies.

package/templates/conditional/next/image/app-router/src/components/ImageExample.jsx

@@ -0,0 +1,34 @@
+import React from "react";
+import Image from "next/image";
+
+export function ImageExample({
+  src = "/next.svg",
+  alt = "Next.js logo",
+  width = 180,
+  height = 37,
+  priority = false,
+  className = "",
+  caption = "Optimized with next/image",
+}) {
+  return (
+    <figure className={`inline-flex flex-col items-center gap-2 p-4 rounded-xl border border-gray-200 dark:border-gray-800 bg-white/50 dark:bg-black/20 ${className}`}>
+      <div className="relative flex items-center justify-center p-2">
+        <Image
+          src={src}
+          alt={alt}
+          width={width}
+          height={height}
+          priority={priority}
+          className="dark:invert transition-transform hover:scale-105"
+        />
+      </div>
+      {caption && (
+        <figcaption className="text-xs text-gray-500 dark:text-gray-400 text-center font-mono">
+          {caption}
+        </figcaption>
+      )}
+    </figure>
+  );
+}
+
+export default ImageExample;

package/templates/conditional/next/image/app-router/src/components/ImageExample.tsx

@@ -0,0 +1,44 @@
+import React from "react";
+import Image from "next/image";
+
+export interface ImageExampleProps {
+  src?: string;
+  alt?: string;
+  width?: number;
+  height?: number;
+  priority?: boolean;
+  className?: string;
+  caption?: string;
+}
+
+export function ImageExample({
+  src = "/next.svg",
+  alt = "Next.js logo",
+  width = 180,
+  height = 37,
+  priority = false,
+  className = "",
+  caption = "Optimized with next/image",
+}: ImageExampleProps) {
+  return (
+    <figure className={`inline-flex flex-col items-center gap-2 p-4 rounded-xl border border-gray-200 dark:border-gray-800 bg-white/50 dark:bg-black/20 ${className}`}>
+      <div className="relative flex items-center justify-center p-2">
+        <Image
+          src={src}
+          alt={alt}
+          width={width}
+          height={height}
+          priority={priority}
+          className="dark:invert transition-transform hover:scale-105"
+        />
+      </div>
+      {caption && (
+        <figcaption className="text-xs text-gray-500 dark:text-gray-400 text-center font-mono">
+          {caption}
+        </figcaption>
+      )}
+    </figure>
+  );
+}
+
+export default ImageExample;

package/templates/conditional/next/image/pages-router/src/components/ImageExample.jsx

@@ -0,0 +1,34 @@
+import React from "react";
+import Image from "next/image";
+
+export function ImageExample({
+  src = "/next.svg",
+  alt = "Next.js logo",
+  width = 180,
+  height = 37,
+  priority = false,
+  className = "",
+  caption = "Optimized with next/image",
+}) {
+  return (
+    <figure className={`inline-flex flex-col items-center gap-2 p-4 rounded-xl border border-gray-200 dark:border-gray-800 bg-white/50 dark:bg-black/20 ${className}`}>
+      <div className="relative flex items-center justify-center p-2">
+        <Image
+          src={src}
+          alt={alt}
+          width={width}
+          height={height}
+          priority={priority}
+          className="dark:invert transition-transform hover:scale-105"
+        />
+      </div>
+      {caption && (
+        <figcaption className="text-xs text-gray-500 dark:text-gray-400 text-center font-mono">
+          {caption}
+        </figcaption>
+      )}
+    </figure>
+  );
+}
+
+export default ImageExample;

package/templates/conditional/next/image/pages-router/src/components/ImageExample.tsx

@@ -0,0 +1,44 @@
+import React from "react";
+import Image from "next/image";
+
+export interface ImageExampleProps {
+  src?: string;
+  alt?: string;
+  width?: number;
+  height?: number;
+  priority?: boolean;
+  className?: string;
+  caption?: string;
+}
+
+export function ImageExample({
+  src = "/next.svg",
+  alt = "Next.js logo",
+  width = 180,
+  height = 37,
+  priority = false,
+  className = "",
+  caption = "Optimized with next/image",
+}: ImageExampleProps) {
+  return (
+    <figure className={`inline-flex flex-col items-center gap-2 p-4 rounded-xl border border-gray-200 dark:border-gray-800 bg-white/50 dark:bg-black/20 ${className}`}>
+      <div className="relative flex items-center justify-center p-2">
+        <Image
+          src={src}
+          alt={alt}
+          width={width}
+          height={height}
+          priority={priority}
+          className="dark:invert transition-transform hover:scale-105"
+        />
+      </div>
+      {caption && (
+        <figcaption className="text-xs text-gray-500 dark:text-gray-400 text-center font-mono">
+          {caption}
+        </figcaption>
+      )}
+    </figure>
+  );
+}
+
+export default ImageExample;

package/templates/conditional/next/image/src/components/ImageExample.jsx

@@ -0,0 +1,44 @@
+import React from "react";
+import Image from "next/image";
+
+/**
+ * Universal Next.js Image component example.
+ * Works seamlessly in both App Router (Server and Client components)
+ * and Pages Router.
+ *
+ * Demonstrates:
+ * - Built-in automatic format optimization (WebP/AVIF)
+ * - Intrinsic sizing to avoid layout shift (CLS)
+ * - Priority loading option for LCP optimization
+ */
+export function ImageExample({
+  src = "/next.svg",
+  alt = "Next.js logo",
+  width = 180,
+  height = 37,
+  priority = false,
+  className = "",
+  caption = "Optimized with next/image",
+}) {
+  return (
+    <figure className={`inline-flex flex-col items-center gap-2 p-4 rounded-xl border border-gray-200 dark:border-gray-800 bg-white/50 dark:bg-black/20 ${className}`}>
+      <div className="relative flex items-center justify-center p-2">
+        <Image
+          src={src}
+          alt={alt}
+          width={width}
+          height={height}
+          priority={priority}
+          className="dark:invert transition-transform hover:scale-105"
+        />
+      </div>
+      {caption && (
+        <figcaption className="text-xs text-gray-500 dark:text-gray-400 text-center font-mono">
+          {caption}
+        </figcaption>
+      )}
+    </figure>
+  );
+}
+
+export default ImageExample;

package/templates/conditional/next/image/src/components/ImageExample.tsx

@@ -0,0 +1,54 @@
+import React from "react";
+import Image from "next/image";
+
+export interface ImageExampleProps {
+  src?: string;
+  alt?: string;
+  width?: number;
+  height?: number;
+  priority?: boolean;
+  className?: string;
+  caption?: string;
+}
+
+/**
+ * Universal Next.js Image component example.
+ * Works seamlessly in both App Router (Server and Client components)
+ * and Pages Router.
+ *
+ * Demonstrates:
+ * - Built-in automatic format optimization (WebP/AVIF)
+ * - Intrinsic sizing to avoid layout shift (CLS)
+ * - Priority loading option for LCP optimization
+ */
+export function ImageExample({
+  src = "/next.svg",
+  alt = "Next.js logo",
+  width = 180,
+  height = 37,
+  priority = false,
+  className = "",
+  caption = "Optimized with next/image",
+}: ImageExampleProps) {
+  return (
+    <figure className={`inline-flex flex-col items-center gap-2 p-4 rounded-xl border border-gray-200 dark:border-gray-800 bg-white/50 dark:bg-black/20 ${className}`}>
+      <div className="relative flex items-center justify-center p-2">
+        <Image
+          src={src}
+          alt={alt}
+          width={width}
+          height={height}
+          priority={priority}
+          className="dark:invert transition-transform hover:scale-105"
+        />
+      </div>
+      {caption && (
+        <figcaption className="text-xs text-gray-500 dark:text-gray-400 text-center font-mono">
+          {caption}
+        </figcaption>
+      )}
+    </figure>
+  );
+}
+
+export default ImageExample;

package/templates/conditional/next/image/src/components/image/index.js

@@ -0,0 +1 @@
+export { ImageExample } from "../ImageExample";

package/templates/conditional/next/image/src/components/image/index.ts

@@ -0,0 +1,2 @@
+export { ImageExample } from "../ImageExample";
+export type { ImageExampleProps } from "../ImageExample";

package/templates/conditional/next/server-components/README.md

@@ -0,0 +1,13 @@
+# React Server Components (RSC) Boundaries & Linting
+
+This conditional template provides:
+1. **Server vs Client Boundary Components**: Clean demonstrations of React Server Components composing Client Components with `"use client"`.
+2. **ESLint Rule Wiring (`rsc/no-server-imports-in-client`)**: An AST-based ESLint rule that disallows importing server-only packages (e.g., `server-only`, Node.js built-ins) into Client Components marked with `"use client"`.
+3. **Dual Router Compatibility**: Operates seamlessly in both Next.js App Router and Pages Router.
+
+## Components
+- `ClientCounter`: An interactive client component demonstrating React state and event handling.
+- `ServerCard`: A server-rendered component shell passing children and composing `ClientCounter` across the boundary.
+
+## ESLint Configuration
+Wires `rsc/no-server-imports-in-client` and `no-restricted-imports` into Next.js flat configuration (`eslint.config.mjs`).

package/templates/conditional/next/server-components/eslint.config.mjs

@@ -0,0 +1,47 @@
+import { noServerImportsInClient } from "./rules/no-server-imports-in-client.mjs";
+
+let baseConfig = [];
+try {
+  const next = await import("eslint-config-next");
+  const imported = next.default || next;
+  baseConfig = Array.isArray(imported) ? imported : [imported];
+} catch {
+  try {
+    const { FlatCompat } = await import("@eslint/eslintrc");
+    const { fileURLToPath } = await import("url");
+    const { dirname } = await import("path");
+    const __filename = fileURLToPath(import.meta.url);
+    const __dirname = dirname(__filename);
+    const compat = new FlatCompat({ baseDirectory: __dirname });
+    baseConfig = compat.extends("next/core-web-vitals");
+  } catch {}
+}
+
+const eslintConfig = [
+  ...baseConfig,
+  {
+    plugins: {
+      rsc: {
+        rules: {
+          "no-server-imports-in-client": noServerImportsInClient,
+        },
+      },
+    },
+    rules: {
+      "rsc/no-server-imports-in-client": "error",
+      "no-restricted-imports": [
+        "error",
+        {
+          patterns: [
+            {
+              group: ["server-only", "**/server-only/**"],
+              message: "Do not import server-only packages in client modules.",
+            },
+          ],
+        },
+      ],
+    },
+  },
+];
+
+export default eslintConfig;

package/templates/conditional/next/server-components/rules/no-server-imports-in-client.js

@@ -0,0 +1,89 @@
+/**
+ * ESLint Rule: rsc/no-server-imports-in-client
+ *
+ * Enforces server/client boundaries in React Server Components (RSC).
+ * When a file is marked with the "use client" directive, it is prohibited
+ * from importing server-only packages (e.g. 'server-only', Node.js builtins,
+ * or modules from server-designated paths).
+ */
+
+export const noServerImportsInClient = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Disallow server-only imports in client components marked with 'use client'",
+      category: "Possible Errors",
+      recommended: true,
+    },
+    schema: [
+      {
+        type: "object",
+        properties: {
+          serverModules: {
+            type: "array",
+            items: { type: "string" },
+          },
+        },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      noServerImport:
+        "Server-only module '{{name}}' cannot be imported into a Client Component ('use client'). Keep server logic on the server side of the RSC boundary.",
+    },
+  },
+  create(context) {
+    const options = context.options[0] || {};
+    const restrictedSet = new Set(
+      options.serverModules || [
+        "server-only",
+        "node:fs",
+        "node:fs/promises",
+        "fs",
+        "fs/promises",
+        "node:child_process",
+        "child_process",
+        "node:net",
+        "net",
+        "node:tls",
+        "tls",
+      ]
+    );
+
+    let isClientComponent = false;
+
+    return {
+      Program(node) {
+        // Inspect top-level statements for "use client" directive
+        for (const stmt of node.body) {
+          if (
+            stmt.type === "ExpressionStatement" &&
+            stmt.expression.type === "Literal" &&
+            stmt.expression.value === "use client"
+          ) {
+            isClientComponent = true;
+            break;
+          }
+        }
+      },
+      ImportDeclaration(node) {
+        if (!isClientComponent) return;
+        const source = node.source.value;
+        if (
+          restrictedSet.has(source) ||
+          source.startsWith("server-only") ||
+          source.includes("/server/") ||
+          source.endsWith("/server")
+        ) {
+          context.report({
+            node,
+            messageId: "noServerImport",
+            data: { name: source },
+          });
+        }
+      },
+    };
+  },
+};
+
+export default noServerImportsInClient;

package/templates/conditional/next/server-components/rules/no-server-imports-in-client.mjs

@@ -0,0 +1,88 @@
+/**
+ * ESLint Rule: rsc/no-server-imports-in-client
+ *
+ * Enforces server/client boundaries in React Server Components (RSC).
+ * When a file is marked with the "use client" directive, it is prohibited
+ * from importing server-only packages (e.g. 'server-only', Node.js builtins,
+ * or modules from server-designated paths).
+ */
+
+export const noServerImportsInClient = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Disallow server-only imports in client components marked with 'use client'",
+      category: "Possible Errors",
+      recommended: true,
+    },
+    schema: [
+      {
+        type: "object",
+        properties: {
+          serverModules: {
+            type: "array",
+            items: { type: "string" },
+          },
+        },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      noServerImport:
+        "Server-only module '{{name}}' cannot be imported into a Client Component ('use client'). Keep server logic on the server side of the RSC boundary.",
+    },
+  },
+  create(context) {
+    const options = context.options[0] || {};
+    const restrictedSet = new Set(
+      options.serverModules || [
+        "server-only",
+        "node:fs",
+        "node:fs/promises",
+        "fs",
+        "fs/promises",
+        "node:child_process",
+        "child_process",
+        "node:net",
+        "net",
+        "node:tls",
+        "tls",
+      ]
+    );
+
+    let isClientComponent = false;
+
+    return {
+      Program(node) {
+        for (const stmt of node.body) {
+          if (
+            stmt.type === "ExpressionStatement" &&
+            stmt.expression.type === "Literal" &&
+            stmt.expression.value === "use client"
+          ) {
+            isClientComponent = true;
+            break;
+          }
+        }
+      },
+      ImportDeclaration(node) {
+        if (!isClientComponent) return;
+        const source = node.source.value;
+        if (
+          restrictedSet.has(source) ||
+          source.startsWith("server-only") ||
+          source.includes("/server/") ||
+          source.endsWith("/server")
+        ) {
+          context.report({
+            node,
+            messageId: "noServerImport",
+            data: { name: source },
+          });
+        }
+      },
+    };
+  },
+};
+
+export default noServerImportsInClient;

package/templates/conditional/next/server-components/src/components/boundaries/ClientCounter.jsx

@@ -0,0 +1,48 @@
+"use client";
+
+import React, { useState } from "react";
+
+/**
+ * Client Component example for RSC boundary.
+ * Marked with "use client" directive — renders on client with full interactivity,
+ * React hooks, and state management.
+ */
+export function ClientCounter({ initialCount = 0, children }) {
+  const [count, setCount] = useState(initialCount);
+
+  return (
+    <div className="client-boundary p-4 rounded-lg border border-blue-500/20 bg-blue-500/5 my-4">
+      <div className="flex items-center gap-2 mb-2">
+        <span className="inline-flex items-center px-2 py-0.5 rounded text-xs font-semibold bg-blue-100 text-blue-800 dark:bg-blue-900/60 dark:text-blue-300">
+          Client Component (&quot;use client&quot;)
+        </span>
+      </div>
+      <p className="text-sm text-gray-600 dark:text-gray-300 mb-3">
+        Interactive client boundary component. Manages state and handles user interaction.
+      </p>
+      <div className="flex items-center gap-3">
+        <button
+          type="button"
+          onClick={() => setCount((c) => c + 1)}
+          className="px-3 py-1.5 text-sm font-medium rounded-md bg-blue-600 text-white hover:bg-blue-700 transition-colors cursor-pointer"
+        >
+          Count: {count}
+        </button>
+        <button
+          type="button"
+          onClick={() => setCount(0)}
+          className="px-2 py-1.5 text-xs text-gray-500 hover:text-gray-700 dark:text-gray-400 dark:hover:text-gray-200 cursor-pointer"
+        >
+          Reset
+        </button>
+      </div>
+      {children && (
+        <div className="mt-4 pt-3 border-t border-blue-500/10">
+          {children}
+        </div>
+      )}
+    </div>
+  );
+}
+
+export default ClientCounter;

package/templates/conditional/next/server-components/src/components/boundaries/ClientCounter.tsx

@@ -0,0 +1,53 @@
+"use client";
+
+import React, { useState } from "react";
+
+export interface ClientCounterProps {
+  initialCount?: number;
+  children?: React.ReactNode;
+}
+
+/**
+ * Client Component example for RSC boundary.
+ * Marked with "use client" directive — renders on client with full interactivity,
+ * React hooks, and state management.
+ */
+export function ClientCounter({ initialCount = 0, children }: ClientCounterProps) {
+  const [count, setCount] = useState(initialCount);
+
+  return (
+    <div className="client-boundary p-4 rounded-lg border border-blue-500/20 bg-blue-500/5 my-4">
+      <div className="flex items-center gap-2 mb-2">
+        <span className="inline-flex items-center px-2 py-0.5 rounded text-xs font-semibold bg-blue-100 text-blue-800 dark:bg-blue-900/60 dark:text-blue-300">
+          Client Component (&quot;use client&quot;)
+        </span>
+      </div>
+      <p className="text-sm text-gray-600 dark:text-gray-300 mb-3">
+        Interactive client boundary component. Manages state and handles user interaction.
+      </p>
+      <div className="flex items-center gap-3">
+        <button
+          type="button"
+          onClick={() => setCount((c) => c + 1)}
+          className="px-3 py-1.5 text-sm font-medium rounded-md bg-blue-600 text-white hover:bg-blue-700 transition-colors cursor-pointer"
+        >
+          Count: {count}
+        </button>
+        <button
+          type="button"
+          onClick={() => setCount(0)}
+          className="px-2 py-1.5 text-xs text-gray-500 hover:text-gray-700 dark:text-gray-400 dark:hover:text-gray-200 cursor-pointer"
+        >
+          Reset
+        </button>
+      </div>
+      {children && (
+        <div className="mt-4 pt-3 border-t border-blue-500/10">
+          {children}
+        </div>
+      )}
+    </div>
+  );
+}
+
+export default ClientCounter;