@ng-native/nx 0.2.0 → 0.3.0

package/README.md

@@ -1,7 +1,8 @@
 # @ng-native/nx
 
-Nx generators for Angular Native: `nx add @ng-native/nx`, and an app generator that adds an Expo
-app project to the workspace, able to import its Angular libraries.
+Nx generators for Angular Native: `nx add @ng-native/nx`, an app generator that adds an Expo app
+project to the workspace, able to import its Angular libraries, and library and component
+generators whose tests render on the fake Fabric.
 
 Alpha: APIs may change before 1.0.
 
@@ -10,6 +11,7 @@ Alpha: APIs may change before 1.0.
 ```sh
 nx add @ng-native/nx
 nx g @ng-native/nx:app apps/mobile
+nx g @ng-native/nx:library packages/ui
 ```
 
 `nx add` adds `@nx/expo` at the workspace's Nx version and registers its plugin, which infers the
@@ -30,7 +32,10 @@ In a workspace whose root package is scoped, the project is `@org/mobile`.
 
 ## What's in the package
 
-- `generators.json` - `init`, which `nx add` runs, and `application` (alias `app`).
+- `generators.json` - `init`, which `nx add` runs, `application` (alias `app`), `library` (alias
+  `lib`), `component` (alias `c`), `tailwind`, which sets up Tailwind in an app and the libraries
+  it uses, and `sync-native-modules`, the sync generator an app runs before `start`, `export` and
+  `prebuild`.
 - `files/` - the template's source files, which a test keeps identical to `template/`.
 
 ## Docs

package/application/index.cjs

@@ -18,6 +18,7 @@
 const path = require('node:path').posix;
 const {
   formatFiles,
+  getProjects,
   joinPathFragments,
   logger,
   offsetFromRoot,
@@ -31,6 +32,7 @@ const native = require('../native-app.cjs');
 const { init, workspaceNxVersion } = require('../init/index.cjs');
 const { usesWorkspaces, includeInWorkspaces } = require('./workspaces.cjs');
 const { asSaved } = require('../save-exact.cjs');
+const { registerSyncGenerator } = require('../sync/index.cjs');
 
 function names(tree, options) {
   const directory = path.normalize(options.directory).replace(/\/$/, '');
@@ -85,17 +87,56 @@ function extendedFile(tree, directory, parent) {
   }
 }
 
-function targets(directory) {
+/** Expo's own, which `expo start` listens on unless given `--port`. */
+const DEFAULT_PORT = 8081;
+
+/**
+ * The lowest Metro port no other Expo app in the workspace listens on, so that
+ * `nx run-many -t start` can run them together: two on Expo's default raced for it, and the second
+ * died with `EADDRINUSE`. Each `expo start` a target runs, as `command` or in `commands`, takes the
+ * port its `--port` names, or Expo's default without one. An app with an `app.json` and no such
+ * command has the default too: its `start` is inferred.
+ */
+function metroPort(tree) {
+  const taken = new Set();
+  for (const [, project] of getProjects(tree)) {
+    const starts = Object.values(project.targets ?? {})
+      .flatMap(({ options }) => [options?.command, ...(options?.commands ?? [])])
+      .map((entry) => (typeof entry === 'string' ? entry : entry?.command))
+      .filter((command) => typeof command === 'string' && /\bexpo start\b/.test(command));
+    for (const command of starts) {
+      taken.add(Number(command.match(/--port[= ](\d+)/)?.[1] ?? DEFAULT_PORT));
+    }
+    if (!starts.length && tree.exists(joinPathFragments(project.root, 'app.json'))) {
+      taken.add(DEFAULT_PORT);
+    }
+  }
+  let port = DEFAULT_PORT;
+  while (taken.has(port)) port++;
+  return port;
+}
+
+function targets(directory, port) {
   const run = (command) => ({ executor: 'nx:run-commands', options: { cwd: directory, command } });
+  const own = port === DEFAULT_PORT ? '' : ` --port ${port}`;
+  // `expo run:ios` and `expo run:android` build the port into the app, so a later app's has to be
+  // its own too. The first app's are @nx/expo's inferred ones, on Expo's default.
+  const runs = own && {
+    'run-ios': { ...run(`expo run:ios${own}`), continuous: true },
+    'run-android': { ...run(`expo run:android${own}`), continuous: true },
+  };
   return {
     typecheck: {
-      ...run('ngc -p tsconfig.json --noEmit'),
+      ...run(native.TYPECHECK),
       cache: true,
       inputs: ['default', '^production'],
+      // The Tailwind sheet the command builds, which a cache hit restores rather than rebuilds.
+      outputs: ['{projectRoot}/.angular-native'],
     },
     test: { ...run('vitest run'), cache: true, inputs: ['default', '^production'] },
-    start: { ...run('expo start'), continuous: true },
-    serve: { ...run('expo start'), continuous: true },
+    start: { ...run(`expo start${own}`), continuous: true },
+    serve: { ...run(`expo start${own}`), continuous: true },
+    ...runs,
   };
 }
 
@@ -143,8 +184,7 @@ async function writeFiles(tree, { directory, projectName, workspaces, bundleIden
   file('AGENTS.md', native.agentsFile(commands(projectName)));
   file('CLAUDE.md', '@AGENTS.md\n');
   file('metro.config.js', native.METRO_CONFIG);
-  // The template's own, for the native projects `expo prebuild` writes beside app.json.
-  file('.gitignore', '# generated native folders\n/ios\n/android\n');
+  file('.gitignore', native.GITIGNORE);
 
   const base = hasPathAliases(tree, workspaces);
   const workspaceBase = base ? `${offsetFromRoot(directory)}tsconfig.base.json` : undefined;
@@ -181,16 +221,13 @@ function ignoreExpo(tree) {
 async function application(tree, options) {
   const resolved = names(tree, options);
   const { directory, projectName, workspaces } = resolved;
-  if (!native.isBundleIdentifier(resolved.bundleIdentifier)) {
-    throw new Error(
-      `${resolved.bundleIdentifier} is not a bundle identifier both iOS and Android accept: ` +
-        'two or more dot-separated segments, each a letter and then letters or digits, none a Java keyword.',
-    );
-  }
+  const problem = native.bundleIdentifierProblem(resolved.bundleIdentifier);
+  if (problem) throw new Error(problem);
   if (tree.exists(joinPathFragments(directory, 'package.json'))) {
     throw new Error(`${directory} already has a package.json. Choose another directory.`);
   }
   const initTask = await init(tree, { skipInstall: true, skipFormat: true });
+  const port = metroPort(tree);
 
   if (workspaces) {
     includeInWorkspaces(tree, directory);
@@ -221,10 +258,11 @@ async function application(tree, options) {
       .split(',')
       .map((tag) => tag.trim())
       .filter(Boolean),
-    targets: targets(directory),
+    targets: targets(directory, port),
   });
 
   ignoreExpo(tree);
+  registerSyncGenerator(tree, projectName);
 
   if (!options.skipFormat) await formatFiles(tree);
   logger.info(
@@ -235,4 +273,4 @@ async function application(tree, options) {
   return runTasksInSerial(initTask, () => installPackagesTask(tree, true));
 }
 
-module.exports = { application };
+module.exports = { application, hasPathAliases };

package/component/index.cjs

@@ -0,0 +1,66 @@
+/**
+ * `nx g @ng-native/nx:component profile-card --project ui`: a component for an Angular Native app
+ * or library.
+ *
+ * `@nx/angular:component` writes a `<p>` and a `TestBed` spec, neither of which works on a device
+ * or on the fake Fabric. This writes what `@ng-native/schematics`' component schematic writes for
+ * the Angular CLI: a component built from `<view>` and `<text>`, with an inline template, and a
+ * `.test.ts` beside it that renders it. It goes under `src/lib` in a library and `src/app` in an
+ * app, in a folder of its own unless `--flat`.
+ */
+const path = require('node:path').posix;
+const { formatFiles, getProjects, joinPathFragments, names } = require('@nx/devkit');
+const { componentSource, testSource } = require('./sources.cjs');
+
+/**
+ * Whether the project is an app: by its `projectType`, or, where it has none, as `@nx/js:library`
+ * leaves a package.json-only project in the TypeScript preset, by the `app.json` an Expo app has.
+ *
+ * @param {import('@nx/devkit').Tree} tree
+ * @param {import('@nx/devkit').ProjectConfiguration} project
+ */
+function isApp(tree, project) {
+  if (project.projectType) return project.projectType === 'application';
+  return tree.exists(joinPathFragments(project.root, 'app.json'));
+}
+
+/**
+ * @param {import('@nx/devkit').Tree} tree
+ * @param {{ name: string, project: string, flat?: boolean, skipTests?: boolean, skipFormat?: boolean }} options
+ */
+async function component(tree, options) {
+  const project = getProjects(tree).get(options.project);
+  if (!project) throw new Error(`The workspace has no project called "${options.project}".`);
+  const file = names(path.basename(options.name)).fileName;
+  const base = joinPathFragments(
+    project.root,
+    'src',
+    isApp(tree, project) ? 'app' : 'lib',
+    path.dirname(options.name),
+  );
+  const folder = options.flat ? base : joinPathFragments(base, file);
+  writeComponent(tree, folder, file, project.prefix, options.skipTests);
+  if (!options.skipFormat) await formatFiles(tree);
+}
+
+/**
+ * The component `file` in `folder`, and its test unless `skipTests`. The library generator writes
+ * its first component with this too.
+ *
+ * @param {import('@nx/devkit').Tree} tree
+ * @param {string} folder
+ * @param {string} file the file name, kebab-case, without `.ts`
+ * @param {string | undefined} prefix the project's selector prefix
+ * @param {boolean} [skipTests]
+ */
+function writeComponent(tree, folder, file, prefix, skipTests = false) {
+  const className = names(file).className;
+  const selector = prefix ? `${prefix}-${file}` : file;
+  const label = `${file} works`;
+  tree.write(joinPathFragments(folder, `${file}.ts`), componentSource(className, selector, label));
+  if (!skipTests) {
+    tree.write(joinPathFragments(folder, `${file}.test.ts`), testSource(className, file, label));
+  }
+}
+
+module.exports = { component, writeComponent };

package/component/schema.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "https://json-schema.org/schema",
+  "$id": "NgNativeNxComponent",
+  "title": "Angular Native component",
+  "description": "A component for an Angular Native app or library, with native elements and a test that runs in Node.",
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "The component's name, optionally with a path: settings/profile-card.",
+      "$default": { "$source": "argv", "index": 0 },
+      "x-prompt": "What should the component be called?"
+    },
+    "project": {
+      "type": "string",
+      "description": "The app or library it belongs to.",
+      "$default": { "$source": "projectName" },
+      "x-dropdown": "projects"
+    },
+    "flat": {
+      "type": "boolean",
+      "description": "Create the files in the directory itself rather than in a folder of their own.",
+      "default": false
+    },
+    "skipTests": {
+      "type": "boolean",
+      "description": "Leave out the .test.ts file.",
+      "default": false
+    },
+    "skipFormat": {
+      "type": "boolean",
+      "description": "Leave the generated files unformatted.",
+      "default": false,
+      "x-priority": "internal"
+    }
+  },
+  "required": ["name", "project"]
+}

package/component/sources.cjs

@@ -0,0 +1,47 @@
+/**
+ * The files a generated component is made of: a component built from `<view>` and `<text>`, and a
+ * test that renders it on the fake Fabric. `@ng-native/schematics` and `@ng-native/nx` each ship
+ * this file, and a test in `@ng-native/nx` keeps the two identical.
+ */
+
+/**
+ * @param {string} className
+ * @param {string} selector
+ * @param {string} label the text it shows, which its test finds
+ */
+function componentSource(className, selector, label) {
+  return `import { Component } from '@angular/core';
+import { Text, View } from '@ng-native/components';
+
+@Component({
+  selector: '${selector}',
+  imports: [Text, View],
+  template: \`
+    <view>
+      <text>${label}</text>
+    </view>
+  \`,
+})
+export class ${className} {}
+`;
+}
+
+/**
+ * @param {string} className
+ * @param {string} file the component's file name, without `.ts`
+ * @param {string} label
+ */
+function testSource(className, file, label) {
+  return `import { render, screen } from '@ng-native/testing';
+import { expect, test } from 'vitest';
+import { ${className} } from './${file}.ts';
+
+test('renders', async () => {
+  await render(${className});
+
+  expect(screen.getByText('${label}')).toBeTruthy();
+});
+`;
+}
+
+module.exports = { componentSource, testSource };

package/files/AGENTS.md

@@ -33,6 +33,9 @@ change; both are fast.
   without its import renders as a plain view.
 - **There is no DOM.** No `document`, no `window`, no `<div>`, `<span>`, `<button>` or `<input>`,
   no `@angular/platform-browser`, and no `@angular/animations`. Use the native elements above.
+- **A component's host is a flex item.** `<app-case-list />` commits as a view of its own, with no
+  `flex`, so a `flex: 1` scroll view inside it gets a height of zero and shows nothing. A component
+  that fills the space it is given sets `host: { style: 'flex: 1' }` (or `:host { flex: 1; }`).
 - **Text only renders inside `<text>`.** `<view>Hello</view>` compiles and shows nothing.
 - **Events are native:** `(press)` on `<pressable>`, not `(click)`; `[(value)]` or `(changeText)` on
   `<text-input>`; `(scroll)`, `(layout)`. A pressable text is `<text pressable (press)="...">`.

package/files/src/app/app.ts

@@ -1,5 +1,6 @@
-import { Component, signal } from '@angular/core';
+import { Component, inject, signal } from '@angular/core';
 import { Pressable, SafeAreaProvider, SafeAreaView, Text, View } from '@ng-native/components';
+import { StatusBar } from '@ng-native/device';
 
 /**
  * Element names are lowercase, and that is load-bearing rather than style: an uppercase name is
@@ -28,7 +29,7 @@ import { Pressable, SafeAreaProvider, SafeAreaView, Text, View } from '@ng-nativ
     }
     .screen {
       flex: 1;
-      background-color: #101014;
+      background-color: #f5f5f7;
     }
     .body {
       flex: 1;
@@ -37,12 +38,12 @@ import { Pressable, SafeAreaProvider, SafeAreaView, Text, View } from '@ng-nativ
       padding: 24px;
     }
     .title {
-      color: #ffffff;
+      color: #101014;
       font-size: 28px;
       font-weight: 700;
     }
     .hint {
-      color: #8b8b96;
+      color: #5f5f6b;
       font-size: 15px;
     }
     .button {
@@ -57,8 +58,25 @@ import { Pressable, SafeAreaProvider, SafeAreaView, Text, View } from '@ng-nativ
       font-size: 16px;
       font-weight: 600;
     }
+    @media (prefers-color-scheme: dark) {
+      .screen {
+        background-color: #101014;
+      }
+      .title {
+        color: #ffffff;
+      }
+      .hint {
+        color: #8b8b96;
+      }
+    }
   `,
 })
 export class App {
   protected readonly count = signal(0);
+
+  constructor() {
+    // Dark status bar icons in light mode and light ones in dark mode. Unclaimed, Android keeps
+    // light icons whatever the scheme.
+    inject(StatusBar).set({ style: 'auto' });
+  }
 }

package/files/src/main.ts

@@ -1,3 +1,7 @@
+// Expo's runtime: its fetch, whose response streams a body, and URL, TextDecoderStream and
+// structuredClone. Metro runs it before this file only when something imports it, and nothing
+// else does in a release build, which would then get React Native's fetch, with no body.
+import 'expo';
 import { AppRegistry, Image, Platform, processColor } from 'react-native';
 import { mount } from '@ng-native/platform';
 import { currentConditions, deviceTokens, watchConditions } from '@ng-native/device';

package/generators.json

@@ -13,6 +13,28 @@
       "factory": "./application/index.cjs#application",
       "schema": "./application/schema.json",
       "description": "An Angular Native app: an Expo project with start, run-ios, run-android, export, test and typecheck targets."
+    },
+    "sync-native-modules": {
+      "factory": "./sync/index.cjs#syncNativeModules",
+      "schema": "./sync/schema.json",
+      "description": "Lists the native modules an app's libraries import in the app's package.json, with their config plugins in app.json. A sync generator."
+    },
+    "library": {
+      "aliases": ["lib"],
+      "factory": "./library/index.cjs#library",
+      "schema": "./library/schema.json",
+      "description": "A library of native components, whose tests render on the fake Fabric as an app's do."
+    },
+    "tailwind": {
+      "factory": "./tailwind/index.cjs#tailwind",
+      "schema": "./tailwind/schema.json",
+      "description": "Sets up Tailwind in an Angular Native app, and the Tailwind-styled workspace libraries it uses."
+    },
+    "component": {
+      "aliases": ["c"],
+      "factory": "./component/index.cjs#component",
+      "schema": "./component/schema.json",
+      "description": "A component for an Angular Native app or library, with native elements and a test that runs in Node."
     }
   }
 }

package/init/index.cjs

@@ -17,11 +17,18 @@
  *
  * It also adds Babel 7's `@babel/runtime`, the one Expo's Babel preset writes imports of. In an
  * Angular workspace `@angular-devkit/build-angular` hoists Babel 8's to the root, which has no
- * `regenerator`, and every `nx start` warned that Metro fell back to file-based resolution.
+ * `regenerator`, and every `nx start` warned that Metro fell back to file-based resolution. And
+ * Babel 7's `@babel/core`, which every plugin in that preset peers on, and which the same hoisted
+ * Babel 8 otherwise answers.
+ *
+ * And `@expo/metro`, which `withNxMetro` in the app's `metro.config.js` loads from the app's
+ * directory up. It is a dependency of `expo`, which pnpm keeps out of the root's `node_modules`, and
+ * loading the config threw "Unable to load Metro config" without it.
  */
 const {
   addDependenciesToPackageJson,
   formatFiles,
+  logger,
   readJson,
   readNxJson,
   updateNxJson,
@@ -88,12 +95,95 @@ function rootDependencies(tree) {
   return { ...companions, expo, react, 'react-native': reactNative };
 }
 
+/**
+ * The dependencies of `@nx/expo` with an install script, through `@nx/jest`. Both ship prebuilt
+ * binaries for every platform, and the script only builds from source when one is missing, so
+ * they are declined rather than allowed. pnpm 11 refuses to install until each one is decided,
+ * with `ERR_PNPM_IGNORED_BUILDS`.
+ */
+const DECLINED_BUILDS = ['@parcel/watcher', 'unrs-resolver'];
+
+const PNPM = 'pnpm-workspace.yaml';
+
+/**
+ * `allowBuilds`' entries with `name` declined, unless it is already `true` or `false`.
+ *
+ * @param {string} entries
+ * @param {string} name
+ */
+function decline(entries, name) {
+  const key = name.startsWith('@') ? `'${name}'` : name;
+  const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const line = new RegExp(`^([ \\t]+)['"]?${escaped}['"]?:[ \\t]*(.*)$`, 'm');
+  const found = line.exec(entries);
+  if (!found) return `${entries && entries.replace(/\n?$/, '\n')}  ${key}: false\n`;
+  if (/^(true|false)\b/.test(found[2])) return entries;
+  return entries.replace(line, `$1${key}: false`);
+}
+
+/**
+ * `allowBuilds` as a block mapping, the form pnpm writes: the key alone on its line, with a comment
+ * after it at most, then its entries, indented, with blank and comment lines among them. The
+ * entries end at their last indented line, before any blank lines that lead to the next key. Null
+ * when there is no such block.
+ *
+ * @param {string} yaml
+ * @returns {{ head: string, entries: string, start: number, end: number } | null}
+ */
+function allowBuildsBlock(yaml) {
+  const key = /^allowBuilds:[ \t]*(?:#.*)?(?:\n|$)/m.exec(yaml);
+  if (!key) return null;
+  const head = key[0].endsWith('\n') ? key[0] : `${key[0]}\n`;
+  const from = key.index + key[0].length;
+  let end = from;
+  for (let at = from; at < yaml.length;) {
+    const next = yaml.indexOf('\n', at);
+    const lineEnd = next === -1 ? yaml.length : next + 1;
+    const line = yaml.slice(at, lineEnd);
+    if (/^[ \t]+\S/.test(line)) end = lineEnd;
+    else if (!/^[ \t]*\n?$/.test(line)) break;
+    at = lineEnd;
+  }
+  return { head, entries: yaml.slice(from, end), start: key.index, end };
+}
+
+/**
+ * Decides the builds above in `pnpm-workspace.yaml`'s `allowBuilds`, which pnpm 10.26 and later
+ * read. A decision the workspace already made stays, and the placeholder pnpm writes after refusing
+ * an install is settled. A workspace without pnpm is left alone.
+ *
+ * Edited as text, so the file keeps its comments and layout. An `allowBuilds` in any form other than
+ * a block mapping, such as a flow mapping, is left as it is with a warning: a second key beside it
+ * would make the file invalid YAML, which pnpm refuses to read.
+ */
+function declineBuilds(tree) {
+  if (!tree.exists(PNPM) && !tree.exists('pnpm-lock.yaml')) return;
+  const yaml = tree.read(PNPM, 'utf-8') ?? '';
+  const block = allowBuildsBlock(yaml);
+  if (!block && /^allowBuilds:/m.test(yaml)) {
+    logger.warn(
+      `${PNPM} sets allowBuilds in a form this cannot add to. Add ` +
+        `${DECLINED_BUILDS.map((name) => `${name}: false`).join(' and ')} to it, ` +
+        'or pnpm 11 stops the install until they are decided.',
+    );
+    return;
+  }
+  const entries = DECLINED_BUILDS.reduce(decline, block?.entries ?? '');
+  const allowBuilds = `${block?.head ?? 'allowBuilds:\n'}${entries}`;
+  if (block) {
+    tree.write(PNPM, yaml.slice(0, block.start) + allowBuilds + yaml.slice(block.end));
+  } else {
+    tree.write(PNPM, yaml ? `${yaml.replace(/\n*$/, '\n')}\n${allowBuilds}` : allowBuilds);
+  }
+}
+
 /**
  * @param {import('@nx/devkit').Tree} tree
  * @param {{ skipInstall?: boolean, skipFormat?: boolean }} options
  */
 async function init(tree, options = {}) {
   registerExpoPlugin(tree);
+  declineBuilds(tree);
   const { dependencies, devDependencies } = readJson(tree, 'package.json');
   const existing = Object.keys({ ...dependencies, ...devDependencies });
   const companions = await asSaved(tree, rootDependencies(tree), existing);