@rs-x/cli 2.0.0-next.10 → 2.0.0-next.11

package/bin/rsx.cjs

@@ -21,6 +21,12 @@ const ANGULAR_DEMO_TEMPLATE_DIR = path.join(
   'templates',
   'angular-demo',
 );
+const REACT_DEMO_TEMPLATE_DIR = path.join(
+  __dirname,
+  '..',
+  'templates',
+  'react-demo',
+);
 const RUNTIME_PACKAGES = [
   '@rs-x/core',
   '@rs-x/state-manager',
@@ -680,6 +686,40 @@ function resolveAngularProjectTsConfig(projectRoot) {
   return path.join(projectRoot, 'tsconfig.json');
 }
 
+function upsertTypescriptPluginInTsConfig(configPath, dryRun) {
+  if (!fs.existsSync(configPath)) {
+    logWarn(`TypeScript config not found: ${configPath}`);
+    return;
+  }
+
+  const tsConfig = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+  const compilerOptions = tsConfig.compilerOptions ?? {};
+  const plugins = Array.isArray(compilerOptions.plugins)
+    ? compilerOptions.plugins
+    : [];
+
+  if (
+    !plugins.some(
+      (plugin) =>
+        plugin &&
+        typeof plugin === 'object' &&
+        plugin.name === '@rs-x/typescript-plugin',
+    )
+  ) {
+    plugins.push({ name: '@rs-x/typescript-plugin' });
+  }
+
+  compilerOptions.plugins = plugins;
+  tsConfig.compilerOptions = compilerOptions;
+
+  if (dryRun) {
+    logInfo(`[dry-run] patch ${configPath}`);
+    return;
+  }
+
+  fs.writeFileSync(configPath, `${JSON.stringify(tsConfig, null, 2)}\n`, 'utf8');
+}
+
 function toFileDependencySpec(fromDir, targetPath) {
   const relative = path.relative(fromDir, targetPath).replace(/\\/gu, '/');
   const normalized = relative.startsWith('.') ? relative : `./${relative}`;
@@ -729,6 +769,7 @@ function resolveProjectRsxSpecs(
   options = {},
 ) {
   const includeAngularPackage = Boolean(options.includeAngularPackage);
+  const includeReactPackage = Boolean(options.includeReactPackage);
   const versionSpec = options.tag ? options.tag : RSX_PACKAGE_VERSION;
   const defaults = {
     '@rs-x/core': versionSpec,
@@ -737,6 +778,7 @@ function resolveProjectRsxSpecs(
     '@rs-x/compiler': versionSpec,
     '@rs-x/typescript-plugin': versionSpec,
     ...(includeAngularPackage ? { '@rs-x/angular': versionSpec } : {}),
+    ...(includeReactPackage ? { '@rs-x/react': versionSpec } : {}),
     '@rs-x/cli': versionSpec,
   };
 
@@ -747,6 +789,7 @@ function resolveProjectRsxSpecs(
     '@rs-x/compiler': 'rs-x-compiler',
     '@rs-x/typescript-plugin': 'rs-x-typescript-plugin',
     ...(includeAngularPackage ? { '@rs-x/angular': 'rs-x-angular' } : {}),
+    ...(includeReactPackage ? { '@rs-x/react': 'rs-x-react' } : {}),
     '@rs-x/cli': 'rs-x-cli',
   };
 
@@ -769,6 +812,11 @@ function resolveProjectRsxSpecs(
             'rs-x-angular': path.join(tarballsDir, 'rs-x-angular'),
           }
         : {}),
+      ...(includeReactPackage
+        ? {
+            'rs-x-react': path.join(tarballsDir, 'rs-x-react'),
+          }
+        : {}),
       'rs-x-cli': path.join(tarballsDir, 'rs-x-cli'),
     };
 
@@ -812,6 +860,11 @@ function resolveProjectRsxSpecs(
           ),
         }
       : {}),
+    ...(includeReactPackage
+      ? {
+          '@rs-x/react': path.join(workspaceRoot, 'rs-x-react'),
+        }
+      : {}),
     '@rs-x/cli': path.join(workspaceRoot, 'rs-x-cli'),
   };
 
@@ -1454,6 +1507,138 @@ function applyAngularDemoStarter(projectRoot, projectName, pm, flags) {
   }
 }
 
+function applyReactDemoStarter(projectRoot, projectName, pm, flags) {
+  const dryRun = Boolean(flags['dry-run']);
+  const tag = resolveInstallTag(flags);
+  const tarballsDir =
+    typeof flags['tarballs-dir'] === 'string'
+      ? path.resolve(process.cwd(), flags['tarballs-dir'])
+      : typeof process.env.RSX_TARBALLS_DIR === 'string' &&
+          process.env.RSX_TARBALLS_DIR.trim().length > 0
+        ? path.resolve(process.cwd(), process.env.RSX_TARBALLS_DIR)
+        : null;
+  const workspaceRoot = findRepoRoot(projectRoot);
+  const rsxSpecs = resolveProjectRsxSpecs(
+    projectRoot,
+    workspaceRoot,
+    tarballsDir,
+    { tag, includeReactPackage: true },
+  );
+
+  const templateFiles = [
+    'README.md',
+    'index.html',
+    'src',
+    'tsconfig.json',
+    'vite.config.ts',
+  ];
+  for (const entry of templateFiles) {
+    copyPathWithDryRun(
+      path.join(REACT_DEMO_TEMPLATE_DIR, entry),
+      path.join(projectRoot, entry),
+      dryRun,
+    );
+  }
+
+  const staleReactFiles = [
+    path.join(projectRoot, 'src/App.tsx'),
+    path.join(projectRoot, 'src/App.css'),
+    path.join(projectRoot, 'src/index.css'),
+    path.join(projectRoot, 'src/vite-env.d.ts'),
+    path.join(projectRoot, 'src/assets'),
+    path.join(projectRoot, 'public'),
+    path.join(projectRoot, 'eslint.config.js'),
+    path.join(projectRoot, 'eslint.config.ts'),
+    path.join(projectRoot, 'tsconfig.app.json'),
+    path.join(projectRoot, 'tsconfig.node.json'),
+  ];
+  for (const stalePath of staleReactFiles) {
+    removeFileOrDirectoryWithDryRun(stalePath, dryRun);
+  }
+
+  const readmePath = path.join(projectRoot, 'README.md');
+  if (fs.existsSync(readmePath)) {
+    const readmeSource = fs.readFileSync(readmePath, 'utf8');
+    const nextReadme = readmeSource.replace(
+      /^#\s+rsx-react-example/mu,
+      `# ${projectName}`,
+    );
+    if (dryRun) {
+      logInfo(`[dry-run] patch ${readmePath}`);
+    } else {
+      fs.writeFileSync(readmePath, nextReadme, 'utf8');
+    }
+  }
+
+  const packageJsonPath = path.join(projectRoot, 'package.json');
+  if (!fs.existsSync(packageJsonPath)) {
+    logError(`package.json not found in generated React app: ${packageJsonPath}`);
+    process.exit(1);
+  }
+
+  const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+  packageJson.name = projectName;
+  packageJson.private = true;
+  packageJson.version = '0.1.0';
+  packageJson.type = 'module';
+  packageJson.scripts = {
+    'build:rsx': 'rsx build --project tsconfig.json --no-emit --prod',
+    dev: 'npm run build:rsx && vite',
+    build: 'npm run build:rsx && vite build',
+    preview: 'vite preview',
+  };
+  packageJson.rsx = {
+    build: {
+      preparse: true,
+      preparseFile: 'src/rsx-generated/rsx-aot-preparsed.generated.ts',
+      compiled: true,
+      compiledFile: 'src/rsx-generated/rsx-aot-compiled.generated.ts',
+      compiledResolvedEvaluator: false,
+    },
+  };
+  packageJson.dependencies = {
+    react: packageJson.dependencies?.react ?? '^19.2.4',
+    'react-dom': packageJson.dependencies?.['react-dom'] ?? '^19.2.4',
+    '@rs-x/core': rsxSpecs['@rs-x/core'],
+    '@rs-x/state-manager': rsxSpecs['@rs-x/state-manager'],
+    '@rs-x/expression-parser': rsxSpecs['@rs-x/expression-parser'],
+    '@rs-x/react': rsxSpecs['@rs-x/react'],
+  };
+  packageJson.devDependencies = {
+    typescript: packageJson.devDependencies?.typescript ?? '^5.9.3',
+    vite: packageJson.devDependencies?.vite ?? '^7.3.1',
+    '@vitejs/plugin-react':
+      packageJson.devDependencies?.['@vitejs/plugin-react'] ?? '^5.1.4',
+    '@types/react': packageJson.devDependencies?.['@types/react'] ?? '^19.2.2',
+    '@types/react-dom':
+      packageJson.devDependencies?.['@types/react-dom'] ?? '^19.2.2',
+    '@rs-x/cli': rsxSpecs['@rs-x/cli'],
+    '@rs-x/compiler': rsxSpecs['@rs-x/compiler'],
+    '@rs-x/typescript-plugin': rsxSpecs['@rs-x/typescript-plugin'],
+  };
+
+  if (dryRun) {
+    logInfo(`[dry-run] patch ${packageJsonPath}`);
+  } else {
+    fs.writeFileSync(
+      packageJsonPath,
+      `${JSON.stringify(packageJson, null, 2)}\n`,
+      'utf8',
+    );
+  }
+
+  const tsConfigPath = path.join(projectRoot, 'tsconfig.json');
+  if (fs.existsSync(tsConfigPath)) {
+    upsertTypescriptPluginInTsConfig(tsConfigPath, dryRun);
+  }
+
+  if (!Boolean(flags['skip-install'])) {
+    logInfo(`Refreshing ${pm} dependencies for the RS-X React starter...`);
+    run(pm, ['install'], { dryRun });
+    logOk('React starter dependencies are up to date.');
+  }
+}
+
 async function runProjectWithTemplate(template, flags) {
   const normalizedTemplate = normalizeProjectTemplate(template);
   if (!normalizedTemplate) {
@@ -1489,10 +1674,7 @@ async function runProjectWithTemplate(template, flags) {
       return;
     }
     if (normalizedTemplate === 'react') {
-      runSetupReact({
-        ...flags,
-        entry: flags.entry ?? 'src/main.tsx',
-      });
+      applyReactDemoStarter(projectRoot, projectName, pm, flags);
       return;
     }
     if (normalizedTemplate === 'nextjs') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rs-x/cli",
-  "version": "2.0.0-next.10",
+  "version": "2.0.0-next.11",
   "description": "CLI for installing RS-X compiler tooling and VS Code integration",
   "bin": {
     "rsx": "./bin/rsx.cjs"

package/templates/react-demo/README.md

@@ -0,0 +1,113 @@
+# rsx-react-example
+
+React demo app for RS-X.
+
+**Website & docs:** [rsxjs.com](https://www.rsxjs.com/)
+
+This example shows a million-row virtual table that:
+
+- uses the `useRsxExpression` hook from `@rs-x/react`
+- creates row expressions with `rsx(...)`
+- keeps a fixed pool of row models and expressions
+- loads pages on demand while scrolling
+- keeps memory bounded by reusing the row pool and pruning old page data
+
+## Install
+
+```bash
+cd rsx-react-example
+npm install
+```
+
+## Start
+
+```bash
+npm run dev
+```
+
+`npm run dev` first runs the RS-X build step, then starts Vite.
+
+## Build
+
+```bash
+npm run build
+```
+
+This runs:
+
+1. `rsx build --project tsconfig.json --no-emit --prod`
+2. `vite build`
+
+So the example gets:
+
+- RS-X semantic checks
+- generated AOT RS-X caches
+- React production build output
+
+## Basic RS-X React setup
+
+The example uses the normal React RS-X setup:
+
+### 1. Initialize RS-X before rendering React
+
+In `src/rsx-bootstrap.ts`:
+
+```ts
+import { InjectionContainer } from '@rs-x/core';
+import { RsXExpressionParserModule } from '@rs-x/expression-parser';
+
+export async function initRsx(): Promise<void> {
+  await InjectionContainer.load(RsXExpressionParserModule);
+}
+```
+
+### 2. Create expressions with `rsx(...)`
+
+In `src/app/virtual-table/row-model.ts`:
+
+```ts
+idExpr: rsx<number>('id')(model),
+nameExpr: rsx<string>('name')(model),
+totalExpr: rsx<number>('price * quantity')(model),
+```
+
+### 3. Bind them with `useRsxExpression`
+
+In `src/app/virtual-table/virtual-table-row.tsx`:
+
+```tsx
+const total = useRsxExpression(row.totalExpr);
+return <span>{total}</span>;
+```
+
+## Why this example is useful
+
+The point of the demo is not just rendering a table. It shows how RS-X behaves in a realistic React scenario:
+
+- large logical dataset: `1,000,000` rows
+- small live expression pool: only the pooled row models stay active
+- page loading is async to simulate real server requests
+- old loaded pages are pruned so scrolling does not grow memory forever
+
+## About the React integration in this demo
+
+This example uses `useRsxExpression` directly in row components so the RS-X behavior is easy to see.
+
+That is a demo choice, not a restriction.
+
+In a real React app, you can also bridge RS-X values into other React-friendly state shapes such as `useSyncExternalStore`, memoized selectors, or your preferred state container if that fits better.
+
+## Key files
+
+- `src/main.tsx`
+- `src/rsx-bootstrap.ts`
+- `src/app/app.tsx`
+- `src/app/virtual-table/virtual-table-shell.tsx`
+- `src/app/virtual-table/virtual-table-row.tsx`
+- `src/app/virtual-table/virtual-table-controller.ts`
+- `src/app/virtual-table/virtual-table-data.service.ts`
+- `src/app/virtual-table/row-model.ts`
+
+## Notes
+
+- The virtual table uses a bounded pool and bounded page retention on purpose, so performance characteristics stay visible while memory stays under control.

package/templates/react-demo/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>RS-X React Demo</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/templates/react-demo/src/app/app.tsx

@@ -0,0 +1,87 @@
+import { type FC, useEffect, useState } from 'react';
+
+import { VirtualTableShell } from './virtual-table/virtual-table-shell';
+
+type ThemeMode = 'light' | 'dark';
+
+function getInitialTheme(): ThemeMode {
+  const storedTheme = window.localStorage.getItem('rsx-theme');
+  if (storedTheme === 'light' || storedTheme === 'dark') {
+    return storedTheme;
+  }
+
+  return 'dark';
+}
+
+export const App: FC = () => {
+  const [theme, setTheme] = useState<ThemeMode>(() => getInitialTheme());
+
+  useEffect(() => {
+    document.documentElement.setAttribute('data-theme', theme);
+    document.body.setAttribute('data-theme', theme);
+    window.localStorage.setItem('rsx-theme', theme);
+  }, [theme]);
+
+  return (
+    <main className="app-shell">
+      <section className="hero">
+        <div className="container">
+          <div className="heroGrid">
+            <div className="heroLeft">
+              <p className="app-eyebrow">RS-X React Demo</p>
+              <h1 className="hTitle">Virtual Table</h1>
+              <p className="hSubhead">
+                Million-row scrolling with a fixed RS-X expression pool.
+              </p>
+              <p className="hSub">
+                This demo keeps rendering bounded while streaming pages on demand,
+                so scrolling stays smooth without growing expression memory with the
+                dataset.
+              </p>
+
+              <div className="heroActions">
+                <a
+                  className="btn btnGhost"
+                  href="https://www.rsxjs.com/"
+                  target="_blank"
+                  rel="noreferrer"
+                >
+                  rs-x
+                </a>
+                <button
+                  type="button"
+                  className="btn btnGhost theme-toggle"
+                  aria-label={`Switch to ${theme === 'dark' ? 'light' : 'dark'} mode`}
+                  onClick={() => {
+                    setTheme((currentTheme) =>
+                      currentTheme === 'dark' ? 'light' : 'dark',
+                    );
+                  }}
+                >
+                  {theme === 'dark' ? 'Light mode' : 'Dark mode'}
+                </button>
+              </div>
+            </div>
+
+            <aside className="card heroNote">
+              <h2 className="cardTitle">What This Shows</h2>
+              <p className="cardText">
+                Only a small row-model pool stays alive while pages stream in
+                around the viewport. That means one million logical rows without
+                one million live bindings.
+              </p>
+            </aside>
+          </div>
+        </div>
+      </section>
+
+      <section className="section">
+        <div className="container">
+          <section className="app-panel card">
+            <VirtualTableShell />
+          </section>
+        </div>
+      </section>
+    </main>
+  );
+};

package/templates/react-demo/src/app/hooks/use-virtual-table-controller.ts

@@ -0,0 +1,24 @@
+import { useRef, useSyncExternalStore } from 'react';
+
+import {
+  VirtualTableController,
+  type VirtualTableSnapshot,
+} from '../virtual-table/virtual-table-controller';
+
+export function useVirtualTableController(): {
+  controller: VirtualTableController;
+  snapshot: VirtualTableSnapshot;
+} {
+  const controllerRef = useRef<VirtualTableController | null>(null);
+  if (!controllerRef.current) {
+    controllerRef.current = new VirtualTableController();
+  }
+  const controller = controllerRef.current;
+  const snapshot = useSyncExternalStore(
+    controller.subscribe,
+    controller.getSnapshot,
+    controller.getSnapshot,
+  );
+
+  return { controller, snapshot };
+}

package/templates/react-demo/src/app/hooks/use-virtual-table-viewport.ts

@@ -0,0 +1,39 @@
+import { type RefObject, useEffect, useRef } from 'react';
+
+import type { VirtualTableController } from '../virtual-table/virtual-table-controller';
+
+const COMPACT_BREAKPOINT_PX = 720;
+const DEFAULT_ROW_HEIGHT = 36;
+const COMPACT_ROW_HEIGHT = 168;
+
+export function useVirtualTableViewport(
+  controller: VirtualTableController,
+): RefObject<HTMLDivElement | null> {
+  const viewportRef = useRef<HTMLDivElement | null>(null);
+
+  useEffect(() => {
+    const viewport = viewportRef.current;
+    if (!viewport) {
+      return;
+    }
+
+    const syncMetrics = (): void => {
+      controller.setViewportHeight(viewport.clientHeight);
+      controller.setRowHeight(
+        viewport.clientWidth <= COMPACT_BREAKPOINT_PX
+          ? COMPACT_ROW_HEIGHT
+          : DEFAULT_ROW_HEIGHT,
+      );
+    };
+
+    syncMetrics();
+    const observer = new ResizeObserver(syncMetrics);
+    observer.observe(viewport);
+
+    return () => {
+      observer.disconnect();
+    };
+  }, [controller]);
+
+  return viewportRef;
+}

package/templates/react-demo/src/app/virtual-table/row-data.ts

@@ -0,0 +1,35 @@
+export type SortKey = 'id' | 'name' | 'price' | 'quantity' | 'category';
+export type SortDirection = 'asc' | 'desc';
+
+export type RowData = {
+  id: number;
+  name: string;
+  price: number;
+  quantity: number;
+  category: string;
+  updatedAt: string;
+};
+
+const categories = ['Hardware', 'Software', 'Design', 'Ops'];
+
+function pad(value: number): string {
+  return value.toString().padStart(2, '0');
+}
+
+export function createRowData(id: number): RowData {
+  const zeroBasedId = id - 1;
+  const price = 25 + (zeroBasedId % 1000) / 10;
+  const quantity = 1 + (Math.floor(zeroBasedId / 1000) % 100);
+  const category = categories[zeroBasedId % categories.length] ?? 'General';
+  const month = pad(((zeroBasedId * 7) % 12) + 1);
+  const day = pad(((zeroBasedId * 11) % 28) + 1);
+
+  return {
+    id,
+    name: `Product ${id.toString().padStart(7, '0')}`,
+    price,
+    quantity,
+    category,
+    updatedAt: `2026-${month}-${day}`,
+  };
+}

package/templates/react-demo/src/app/virtual-table/row-model.ts

@@ -0,0 +1,45 @@
+import { rsx, type IExpression } from '@rs-x/expression-parser';
+
+import type { RowData } from './row-data';
+
+export type RowModel = {
+  model: RowData;
+  idExpr: IExpression<number>;
+  nameExpr: IExpression<string>;
+  categoryExpr: IExpression<string>;
+  priceExpr: IExpression<number>;
+  quantityExpr: IExpression<number>;
+  updatedAtExpr: IExpression<string>;
+  totalExpr: IExpression<number>;
+};
+
+export function createRowModel(): RowModel {
+  const model: RowData = {
+    id: 0,
+    name: '',
+    price: 0,
+    quantity: 0,
+    category: 'General',
+    updatedAt: '2026-01-01',
+  };
+
+  return {
+    model,
+    idExpr: rsx<number>('id')(model),
+    nameExpr: rsx<string>('name')(model),
+    categoryExpr: rsx<string>('category')(model),
+    priceExpr: rsx<number>('price')(model),
+    quantityExpr: rsx<number>('quantity')(model),
+    updatedAtExpr: rsx<string>('updatedAt')(model),
+    totalExpr: rsx<number>('price * quantity')(model),
+  };
+}
+
+export function updateRowModel(target: RowModel, data: RowData): void {
+  target.model.id = data.id;
+  target.model.name = data.name;
+  target.model.price = data.price;
+  target.model.quantity = data.quantity;
+  target.model.category = data.category;
+  target.model.updatedAt = data.updatedAt;
+}