create-monolayer-app 0.1.0-canary.1

package/README.md

@@ -0,0 +1,54 @@
+# create-monolayer-app
+
+The official CLI starter kit for creating Monolayer applications.
+
+## Quick Start
+
+You can create a new Monolayer app using `npm create` or `npx`:
+
+```bash
+# Using npm create (recommended)
+npm create monolayer-app <app-name>
+
+# Using npx
+npx create-monolayer-app <app-name>
+```
+
+Replace `<app-name>` with your desired project name (must be a slug without spaces, e.g. `my-monolayer-app`).
+
+## What's Included
+
+The scaffolded project includes:
+
+- **React Router v8** — Server-side rendering, routing, and data loading
+- **React 19** — Latest React features
+- **Tailwind CSS v4** — Modern utility-first styling with Vite integration
+- **TypeScript** — Full type safety out of the box
+- **Ultracite (Oxlint + Oxfmt)** — Fast linting and formatting
+- **AI Agent Context** — Preconfigured `.agents`, `.claude`, and `AGENTS.md` guidelines
+
+## Next Steps
+
+Once your project is scaffolded and dependencies are installed:
+
+```bash
+cd <app-name>
+npm run dev
+```
+
+### Available Scripts
+
+- `npm run dev` — Start the development server with HMR at `http://localhost:5173`
+- `npm run build` — Create an optimized production build
+- `npm run start` — Run the production server
+- `npm run check` — Run typegen, TypeScript compiler, and Ultracite checks
+- `npm run fix` — Automatically format and fix lint issues
+
+## Requirements
+
+- Node.js >= 18.0.0
+- npm >= 9.0.0
+
+## License
+
+MIT

package/bin/index.js

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Terminal color helpers
+const reset = '\x1b[0m';
+const bold = (str) => `\x1b[1m${str}${reset}`;
+const cyan = (str) => `\x1b[36m${str}${reset}`;
+const green = (str) => `\x1b[32m${str}${reset}`;
+const red = (str) => `\x1b[31m${str}${reset}`;
+const dim = (str) => `\x1b[2m${str}${reset}`;
+const yellow = (str) => `\x1b[33m${str}${reset}`;
+
+// Helper to validate slug
+function isValidSlug(name) {
+  if (!name || typeof name !== 'string') return false;
+  if (/\s/.test(name)) return false;
+  // Slug should consist of letters, numbers, hyphens, and underscores
+  return /^[a-zA-Z0-9_-]+$/.test(name);
+}
+
+// Copy directory recursively
+function copyDir(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (entry.name === '.DS_Store') continue;
+
+    const srcPath = path.join(src, entry.name);
+    let destName = entry.name;
+
+    // npm ignores or modifies .gitignore during publishing, so we use _gitignore in template
+    if (destName === '_gitignore') {
+      destName = '.gitignore';
+    }
+
+    const destPath = path.join(dest, destName);
+
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+function printUsage() {
+  console.log(`
+${bold('create-monolayer-app')} - Scaffold a new Monolayer application
+
+${bold('Usage:')}
+  npx create-monolayer-app ${green('<app-name>')}
+
+${bold('Arguments:')}
+  ${green('<app-name>')}    Required. The name of the app (slug, no spaces). A directory
+                with this name will be created in the current working directory.
+
+${bold('Options:')}
+  -h, --help       Show this help message
+  -v, --version    Show version number
+
+${bold('Example:')}
+  npx create-monolayer-app my-monolayer-app
+`);
+}
+
+function main() {
+  const args = process.argv.slice(2);
+
+  if (args.includes('--help') || args.includes('-h')) {
+    printUsage();
+    process.exit(0);
+  }
+
+  if (args.includes('--version') || args.includes('-v')) {
+    const pkgPath = path.join(__dirname, '../package.json');
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    console.log(pkg.version);
+    process.exit(0);
+  }
+
+  const rawArg = args.find((arg) => !arg.startsWith('-'));
+
+  if (!rawArg) {
+    console.error(red('Error: <app-name> is required.'));
+    printUsage();
+    process.exit(1);
+  }
+
+  const appName = rawArg.trim();
+
+  if (appName.length === 0) {
+    console.error(red('Error: App name cannot be empty.'));
+    process.exit(1);
+  }
+
+  if (/\s/.test(appName)) {
+    console.error(red(`Error: App name "${appName}" contains spaces.`));
+    console.error(yellow('App name must be a slug without spaces (e.g. my-app or my_app).'));
+    process.exit(1);
+  }
+
+  if (!isValidSlug(appName)) {
+    console.error(red(`Error: App name "${appName}" is not a valid slug.`));
+    console.error(yellow('Only alphanumeric characters, hyphens (-), and underscores (_) are allowed.'));
+    process.exit(1);
+  }
+
+  const targetDir = path.resolve(process.cwd(), appName);
+  const templateDir = path.resolve(__dirname, '../template');
+
+  if (!fs.existsSync(templateDir)) {
+    console.error(red(`Error: Template directory not found at ${templateDir}`));
+    process.exit(1);
+  }
+
+  if (fs.existsSync(targetDir)) {
+    const existingFiles = fs.readdirSync(targetDir);
+    if (existingFiles.length > 0) {
+      console.error(red(`Error: Directory "${appName}" already exists and is not empty.`));
+      process.exit(1);
+    }
+  }
+
+  console.log(`\nCreating a new Monolayer app in ${green(targetDir)}...\n`);
+
+  // 1. Copy template files
+  copyDir(templateDir, targetDir);
+
+  // 2. Update package.json name
+  const targetPkgPath = path.join(targetDir, 'package.json');
+  if (fs.existsSync(targetPkgPath)) {
+    const pkg = JSON.parse(fs.readFileSync(targetPkgPath, 'utf8'));
+    pkg.name = appName.toLowerCase();
+    fs.writeFileSync(targetPkgPath, `${JSON.stringify(pkg, null, 2)}\n`, 'utf8');
+  }
+
+  // 3. Install dependencies with npm
+  console.log(cyan('Installing dependencies with npm...'));
+  console.log(dim(`Running npm install in ${targetDir}\n`));
+
+  const npmCmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+  const installResult = spawnSync(npmCmd, ['install'], {
+    cwd: targetDir,
+    stdio: 'inherit',
+  });
+
+  if (installResult.status !== 0) {
+    console.error(red('\nFailed to install dependencies with npm.'));
+    process.exit(installResult.status ?? 1);
+  }
+
+  // 4. Success message
+  console.log(`\n${green('✔')} Successfully created ${bold(appName)} at ${dim(targetDir)}\n`);
+  console.log('Inside that directory, you can run:');
+  console.log(`\n  ${cyan(`cd ${appName}`)}`);
+  console.log(`  ${cyan('npm run dev')}\n`);
+  console.log('Available scripts:');
+  console.log(`  ${cyan('npm run dev')}     - Start the development server with HMR`);
+  console.log(`  ${cyan('npm run build')}   - Build the application for production`);
+  console.log(`  ${cyan('npm run start')}   - Start the production server`);
+  console.log(`  ${cyan('npm run check')}   - Run typegen, TypeScript, and Ultracite checks`);
+  console.log(`  ${cyan('npm run fix')}     - Automatically fix lint and format issues\n`);
+  console.log(bold('Happy coding!'));
+}
+
+try {
+  main();
+} catch (err) {
+  console.error(red('\nAn unexpected error occurred:'), err);
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "create-monolayer-app",
+  "version": "0.1.0-canary.1",
+  "description": "CLI to scaffold a new Monolayer application",
+  "type": "module",
+  "bin": {
+    "create-monolayer-app": "./bin/index.js"
+  },
+  "scripts": {
+    "publish:local": "npm publish --registry http://localhost:4873",
+    "unpublish:local": "npm unpublish --registry http://localhost:4873 create-monolayer-app -f"
+  },
+  "files": [
+    "bin",
+    "template"
+  ],
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "keywords": [
+    "create-monolayer-app",
+    "create-app",
+    "monolayer",
+    "react-router",
+    "scaffold",
+    "template"
+  ],
+  "license": "MIT"
+}

package/template/.agents/skills/react-router/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: react-router
+description: Build applications with React Router in Framework, Data, Declarative, and unstable RSC modes. Use when configuring routes, route modules, loaders, actions, forms, fetchers, navigation, pending UI, SSR/SPA/pre-rendering, middleware, URL params/search params, or React Router upgrades.
+license: MIT
+---
+
+# React Router
+
+React Router is mode-specific. Before changing an app, identify the mode, load the matching reference, then read the installed docs for the installed package version.
+
+## Identify the Mode
+
+Do not apply Framework/Data patterns to a Declarative app unless you are intentionally migrating modes.
+
+### Framework Mode
+
+Use Framework Mode guidance when you see:
+
+- `@react-router/dev` in dependencies
+- `react-router.config.ts`
+- `app/routes.ts`
+- `app/entry.server.tsx` and/or `app/entry.client.tsx` files
+- route modules under `app/routes/`
+- route exports like `loader`, `action`, `clientLoader`, `clientAction`, `ErrorBoundary`, `meta`, `links`, or `headers`
+- imports from `./+types/...`
+- the React Router Vite plugin from `@react-router/dev/vite`
+
+Framework examples usually use the default `app/` directory, but check `react-router.config.ts` for a custom `appDirectory` before assuming exact paths.
+
+Then read `references/framework-mode.md`.
+
+### Data Mode
+
+Use Data Mode guidance when you see:
+
+- `createBrowserRouter`, `createHashRouter`, `createMemoryRouter`, or `createStaticRouter`
+- `<RouterProvider router={router}>`
+- route objects with properties like `path`, `children`, `loader`, `action`, `Component`, `ErrorBoundary`, or `lazy`
+- data APIs without the Framework Vite plugin
+
+Then read `references/data-mode.md`.
+
+### Declarative Mode
+
+Use Declarative Mode guidance when you see:
+
+- `<BrowserRouter>`, `<HashRouter>`, or `<MemoryRouter>`
+- `<Routes>` and `<Route>` JSX route configuration
+- route components passed with `element={<Component />}`
+- no data router, no route module convention, and no loaders/actions
+
+Then read `references/declarative-mode.md`.
+
+### RSC Framework and RSC Data Modes
+
+React Server Components support is unstable and exists in both Framework and Data variants. Use RSC guidance when you see:
+
+- `unstable_reactRouterRSC`
+- `@vitejs/plugin-rsc`
+- `unstable_RSCRouteConfig`
+- RSC entry files such as `entry.rsc`
+- `ServerComponent`, `ServerErrorBoundary`, `ServerLayout`, or `ServerHydrateFallback`
+- React directives or boundary packages such as `"use client"`, `"server-only"`, or `"client-only"`
+
+For RSC Framework, read both `references/framework-mode.md` and `references/rsc.md`.
+For RSC Data, read both `references/data-mode.md` and `references/rsc.md`.
+
+## Use Installed Docs as Source of Truth
+
+React Router ships markdown docs in the package so guidance can match the installed version:
+
+```txt
+node_modules/react-router/docs/
+```
+
+Key docs paths:
+
+```txt
+node_modules/react-router/docs/index.md
+node_modules/react-router/docs/start/
+node_modules/react-router/docs/how-to/
+node_modules/react-router/docs/explanation/
+node_modules/react-router/docs/upgrading/
+```
+
+When this skill references `react-router/docs/...`, read the matching file under `node_modules/react-router/docs/`. If the installed version does not include local docs, use the repo `docs/` directory when working inside the React Router repository; in a consuming app, fall back to version-matched website docs.
+
+Most docs include a mode marker near the top:
+
+```txt
+[MODES: framework, data, declarative]
+```
+
+Only apply a doc when its mode marker matches the app mode. If a task spans modes, prefer the section or file that matches the current app.
+
+RSC is documented primarily in:
+
+```txt
+node_modules/react-router/docs/how-to/react-server-components.md
+```
+
+## Skill References
+
+Load the relevant reference after identifying the mode:
+
+| Reference                        | Use When                                      |
+| -------------------------------- | --------------------------------------------- |
+| `references/framework-mode.md`   | Framework Mode or RSC Framework base behavior |
+| `references/data-mode.md`        | Data Mode or RSC Data base behavior           |
+| `references/declarative-mode.md` | Declarative Mode                              |
+| `references/rsc.md`              | Any unstable RSC app                          |
+
+## Mode Migration Doc Index
+
+If the user explicitly asks to switch modes, read the target mode reference plus the migration-relevant docs:
+
+| Migration                            | Docs to read                                                                                                                                                                                                                          |
+| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Declarative → Data                   | `react-router/docs/start/modes.md`, `react-router/docs/start/data/routing.md`, `react-router/docs/start/data/data-loading.md`, `react-router/docs/start/data/actions.md`                                                              |
+| Declarative/Data → Framework         | `react-router/docs/start/modes.md`, `react-router/docs/start/framework/routing.md`, `react-router/docs/start/framework/route-module.md`, `react-router/docs/how-to/route-module-type-safety.md`                                       |
+| Framework SPA/SSR/pre-render changes | `react-router/docs/start/framework/rendering.md`, `react-router/docs/how-to/spa.md`, `react-router/docs/how-to/pre-rendering.md`, `react-router/docs/start/framework/data-loading.md`, `react-router/docs/start/framework/actions.md` |
+| Future flags/upgrades                | `react-router/docs/upgrading/future.md` and relevant files under `react-router/docs/upgrading/`                                                                                                                                       |

package/template/.agents/skills/react-router/references/data-mode.md

@@ -0,0 +1,165 @@
+# Data Mode
+
+Data Mode uses data routers such as `createBrowserRouter` and renders with `<RouterProvider>`. It gives an app route objects, loaders, actions, pending UI, fetchers, and SSR primitives without adopting the Framework Vite plugin or route-module file conventions.
+
+Use this reference after the main skill identifies a Data Mode app.
+
+## Read the Local Docs by Mode
+
+Start with:
+
+```txt
+react-router/docs/start/modes.md
+react-router/docs/start/data/index.md
+```
+
+Then use the Data docs under:
+
+```txt
+react-router/docs/start/data/
+```
+
+Those files cover installation, route objects, routing, data loading, actions, navigation, pending UI, and testing. For task-specific details, read relevant files in:
+
+```txt
+react-router/docs/how-to/
+react-router/docs/explanation/
+```
+
+Always check the `[MODES: data, ...]` marker in a doc before applying it.
+
+## Data Router Shape
+
+Typical setup:
+
+```tsx
+import { createBrowserRouter, RouterProvider } from "react-router";
+
+const router = createBrowserRouter([
+  {
+    path: "/",
+    Component: Root,
+    loader: rootLoader,
+    children: [
+      { index: true, Component: Home },
+      {
+        path: "projects/:projectId",
+        Component: Project,
+        loader: projectLoader,
+      },
+    ],
+  },
+]);
+
+root.render(<RouterProvider router={router} />);
+```
+
+Look for route object arrays and APIs such as:
+
+- `createBrowserRouter`
+- `createHashRouter`
+- `createMemoryRouter`
+- `RouterProvider`
+- `loader`
+- `action`
+- `Component`
+- `ErrorBoundary`
+- `lazy`
+- `children`
+
+## Route Objects and Routing
+
+Before editing route configuration, read:
+
+```txt
+react-router/docs/start/data/routing.md
+react-router/docs/start/data/route-object.md
+```
+
+Rules:
+
+- Keep route objects outside render when possible.
+- Use nested routes for shared layouts and data boundaries.
+- Use index routes for default child content.
+- Use dynamic segments and splats according to route-object docs.
+- Prefer `Component`/`ErrorBoundary` route object properties in Data Mode examples unless the existing app uses `element` consistently.
+
+## Data and Mutations
+
+Before working on data loading or mutations, read:
+
+```txt
+react-router/docs/start/data/data-loading.md
+react-router/docs/start/data/actions.md
+```
+
+Rules:
+
+- Load route data with route `loader` functions.
+- Mutate route data with route `action` functions.
+- Prefer loaders/actions over route-level `useEffect` fetching.
+- Use `request`, `params`, and returned/throwable Responses as described in the docs.
+- Let React Router revalidate after actions unless there is a documented reason to customize revalidation.
+
+Common patterns:
+
+- Validation failure from an action: return `data({ errors, values }, { status: 400 })`, then render errors with `useActionData()` or `fetcher.data`.
+- Missing record in a loader: throw `data("Not Found", { status: 404 })` and render the route `ErrorBoundary`.
+- Search/filter data: parse `new URL(request.url).searchParams` in the loader so the URL is shareable and bookmarkable.
+
+## Forms, Fetchers, and Pending UI
+
+For forms and pending UI, read:
+
+```txt
+react-router/docs/start/data/actions.md
+react-router/docs/start/data/pending-ui.md
+react-router/docs/how-to/fetchers.md
+react-router/docs/explanation/form-vs-fetcher.md
+```
+
+Rules of thumb:
+
+- Search/filter form that updates the URL: `<Form method="get">`.
+- Mutation that should change URL/history or redirect after completion: `<Form method="post">`.
+- Mutation that should keep the user on the same page: `useFetcher` / `<fetcher.Form>`.
+- Optimistic UI: derive from `fetcher.formData` or `navigation.formData`.
+
+## Navigation and URL State
+
+Before changing navigation or search params, read:
+
+```txt
+react-router/docs/start/data/navigating.md
+react-router/docs/how-to/search-params.md
+react-router/docs/explanation/location.md
+```
+
+Rules:
+
+- Use `<Link>`/`<NavLink>` for user-initiated internal navigation.
+- Use `redirect` in loaders/actions when navigation follows data loading or mutations.
+- Use `useNavigate` for imperative client-side event navigation.
+- Treat URL params as strings and validate/parse them.
+- Preserve unrelated search params unless intentionally resetting them.
+
+## SSR in Data Mode
+
+Data Mode SSR is manual and lower-level than Framework Mode. Before implementing or changing SSR, read the Data Mode custom/SSR docs and match existing server abstractions.
+
+Start with:
+
+```txt
+react-router/docs/start/data/custom.md
+```
+
+Look for APIs like `createStaticHandler`, `createStaticRouter`, `StaticRouterProvider`, and hydration data handling in the current app before changing anything.
+
+## RSC Data
+
+If this Data Mode app uses `unstable_RSCRouteConfig`, RSC route config, or low-level RSC server APIs, also read:
+
+```txt
+references/rsc.md
+react-router/docs/how-to/react-server-components.md
+```

package/template/.agents/skills/react-router/references/declarative-mode.md

@@ -0,0 +1,123 @@
+# Declarative Mode
+
+Declarative Mode is React Router's simplest mode. It uses router components like `<BrowserRouter>` and JSX routes with `<Routes>`/`<Route>`. It does not provide loaders, actions, fetchers, or data-router pending UI.
+
+Use this reference after the main skill identifies a Declarative Mode app.
+
+## Read the Local Docs by Mode
+
+Start with:
+
+```txt
+react-router/docs/start/modes.md
+react-router/docs/start/declarative/index.md
+```
+
+Then use the Declarative docs under:
+
+```txt
+react-router/docs/start/declarative/
+```
+
+Those files cover installation, routing, navigation, and URL values. For conceptual details, read relevant files in:
+
+```txt
+react-router/docs/explanation/
+```
+
+Always check the `[MODES: declarative, ...]` marker in a doc before applying it.
+
+## Declarative Router Shape
+
+Typical setup:
+
+```tsx
+import { BrowserRouter, Routes, Route } from "react-router";
+
+function App() {
+  return (
+    <BrowserRouter>
+      <Routes>
+        <Route path="/" element={<Home />} />
+        <Route path="about" element={<About />} />
+        <Route path="dashboard" element={<DashboardLayout />}>
+          <Route index element={<DashboardHome />} />
+          <Route path="settings" element={<Settings />} />
+        </Route>
+      </Routes>
+    </BrowserRouter>
+  );
+}
+```
+
+Look for APIs such as:
+
+- `<BrowserRouter>`
+- `<HashRouter>`
+- `<MemoryRouter>`
+- `<Routes>`
+- `<Route>`
+- `element={<Component />}`
+- `useRoutes`
+
+## Routing
+
+Before editing routes, read:
+
+```txt
+react-router/docs/start/declarative/routing.md
+```
+
+Rules:
+
+- Use `<Routes>` and `<Route>` for route configuration.
+- Use nested routes with `<Outlet>` for shared layout.
+- Use index routes for default child UI.
+- Use route params and splats according to the declarative routing docs.
+- Do not add route object loaders/actions to a Declarative router.
+
+## Navigation
+
+Before changing navigation, read:
+
+```txt
+react-router/docs/start/declarative/navigating.md
+```
+
+Rules:
+
+- Use `<Link>` or `<NavLink>` for user-initiated internal navigation.
+- Use `NavLink` when active styling matters.
+- Use `useNavigate` for imperative navigation from event handlers or effects.
+- Do not use plain `<a href>` for internal navigation unless intentionally forcing a full document navigation.
+
+## URL Values
+
+Before changing params, search params, or location state, read:
+
+```txt
+react-router/docs/start/declarative/url-values.md
+react-router/docs/explanation/location.md
+```
+
+Rules:
+
+- Use `useParams` for dynamic route params.
+- Use `useSearchParams` for query string state.
+- Use `useLocation` for the current location object and navigation state.
+- Validate and parse URL params; they are strings and can be absent.
+- Preserve unrelated search params unless intentionally resetting them.
+
+## Mode Boundary
+
+Declarative Mode does not have Data/Framework APIs such as:
+
+- `loader`
+- `action`
+- `<Form>`
+- `useFetcher`
+- `useNavigation`
+- route module exports
+- generated `./+types` route types
+
+If the user asks for route data loading, DB/API-backed data, CRUD, form mutations, validation returned from submissions, revalidation, pending UI, optimistic UI, or fetchers, recommend Data Mode or Framework Mode depending on how much structure they want. Ask before migrating unless they already requested it.