@ng-native/nx 0.0.1 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ashley Hunter
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,43 @@
 # @ng-native/nx
 
-A placeholder: this version has no code. See https://ng-native.com.
+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.
+
+Alpha: APIs may change before 1.0.
+
+## Install
+
+```sh
+nx add @ng-native/nx
+nx g @ng-native/nx:app apps/mobile
+```
+
+`nx add` adds `@nx/expo` at the workspace's Nx version and registers its plugin, which infers the
+app's Expo targets. The generator writes the template's app, with a `metro.config.js` wrapped in
+`withNxMetro` so workspace libraries resolve, and adds `typecheck` and `test` targets.
+
+## Example
+
+```sh
+nx start mobile            # expo start
+nx run mobile:run-ios      # expo run:ios
+nx export mobile --platform ios
+nx test mobile             # vitest run, on the fake Fabric
+nx typecheck mobile
+```
+
+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`).
+- `files/` - the template's source files, which a test keeps identical to `template/`.
+
+## Docs
+
+- [Nx](https://ng-native.com/packages/nx)
+- [Root README](https://github.com/ng-native/ng-native/blob/main/README.md)
+
+## License
+
+MIT

package/application/index.cjs

@@ -0,0 +1,160 @@
+/**
+ * `nx g @ng-native/nx:app apps/mobile`: an Angular Native app as a project of this workspace.
+ *
+ * The app is an Expo project, built by Metro. `@nx/expo`'s plugin, which `init` registers, infers
+ * its Expo targets from the files written here; `project.json` adds the two it cannot infer:
+ * `typecheck`, since Expo's `tsconfig` sets `noEmit` and `@nx/js` disables its own for that, and
+ * `test`, which runs Vitest once rather than watching.
+ *
+ * Where the dependencies go depends on the workspace. With package-manager workspaces, the Nx
+ * default since 20, the app is a workspace package and lists them itself, which pnpm needs in
+ * order to link them. In an integrated workspace, with one root `package.json`, they go there.
+ */
+const path = require('node:path').posix;
+const {
+  formatFiles,
+  joinPathFragments,
+  logger,
+  offsetFromRoot,
+  readJson,
+  runTasksInSerial,
+  addProjectConfiguration,
+  installPackagesTask,
+  addDependenciesToPackageJson,
+} = require('@nx/devkit');
+const native = require('../native-app.cjs');
+const { init, workspaceNxVersion } = require('../init/index.cjs');
+const { usesWorkspaces, includeInWorkspaces } = require('./workspaces.cjs');
+
+function names(tree, options) {
+  const directory = path.normalize(options.directory).replace(/\/$/, '');
+  const name = options.name ?? path.basename(directory);
+  const scope = readJson(tree, 'package.json').name?.match(/^@[^/]+/)?.[0];
+  const workspaces = usesWorkspaces(tree);
+  // A workspace package is named for the workspace's scope, as Nx names its own.
+  const projectName = workspaces && scope ? `${scope}/${name}` : name;
+  return { directory, name, projectName, workspaces };
+}
+
+function targets(directory) {
+  const run = (command) => ({ executor: 'nx:run-commands', options: { cwd: directory, command } });
+  return {
+    typecheck: {
+      ...run('ngc -p tsconfig.json --noEmit'),
+      cache: true,
+      inputs: ['default', '^production'],
+    },
+    test: { ...run('vitest run'), cache: true, inputs: ['default', '^production'] },
+  };
+}
+
+/** The Commands section of the app's `AGENTS.md`, as this workspace runs them. */
+function commands(name) {
+  const rows = [
+    [`nx start ${name}`, 'Metro; press i or a for a simulator, or scan the QR code with Expo Go'],
+    [`nx run ${name}:run-ios`, 'the iOS simulator'],
+    [`nx run ${name}:run-android`, 'the Android emulator'],
+    [`nx test ${name}`, 'Vitest, in Node against a fake native layer: no simulator needed'],
+    [`nx typecheck ${name}`, 'TypeScript, without emitting'],
+  ];
+  const width = Math.max(...rows.map(([command]) => command.length)) + 2;
+  return [
+    '```sh',
+    ...rows.map(([command, what]) => `${command.padEnd(width)}# ${what}`),
+    '```',
+    '',
+    '`src/main.ts` mounts the root component, `src/app/app.ts`. ' +
+      `Run \`nx test ${name}\` and \`nx typecheck ${name}\` after a change; both are fast.`,
+  ].join('\n');
+}
+
+function writeFiles(tree, { directory, projectName, workspaces }) {
+  const file = (name, content) => tree.write(joinPathFragments(directory, name), content);
+  for (const name of native.SOURCE_FILES) file(name, native.sourceFile(name));
+  file('app.json', native.appJson(projectName));
+  file('AGENTS.md', native.agentsFile(commands(projectName)));
+  file('CLAUDE.md', '@AGENTS.md\n');
+  file('metro.config.js', native.METRO_CONFIG);
+
+  const base = !workspaces && tree.exists('tsconfig.base.json');
+  const workspaceBase = base ? `${offsetFromRoot(directory)}tsconfig.base.json` : undefined;
+  const conditions = tree.exists('tsconfig.base.json')
+    ? (readJson(tree, 'tsconfig.base.json').compilerOptions?.customConditions ?? [])
+    : [];
+  file('tsconfig.json', JSON.stringify(native.tsconfig(workspaceBase, conditions), null, 2) + '\n');
+  file('vitest.config.mts', native.vitestConfig(Boolean(base)));
+
+  const manifest = { name: projectName, version: '0.0.1', private: true, main: 'src/main.ts' };
+  if (workspaces) {
+    Object.assign(manifest, {
+      dependencies: native.dependencies,
+      devDependencies: native.devDependencies,
+    });
+  } else {
+    manifest.dependencies = native.prebuildPins(readJson(tree, 'package.json'));
+  }
+  file('package.json', JSON.stringify(manifest, null, 2) + '\n');
+}
+
+/** Expo's cache directory, once. */
+function ignoreExpo(tree) {
+  if (!tree.exists('.gitignore')) return;
+  const ignore = tree.read('.gitignore', 'utf-8') ?? '';
+  if (/^\.expo\/?$/m.test(ignore)) return;
+  tree.write('.gitignore', ignore.replace(/\n*$/, '\n\n# Expo\n.expo/\n'));
+}
+
+/**
+ * @param {import('@nx/devkit').Tree} tree
+ * @param {{ directory: string, name?: string, tags?: string, skipInstall?: boolean, skipFormat?: boolean }} options
+ */
+async function application(tree, options) {
+  const resolved = names(tree, options);
+  const { directory, projectName, workspaces } = resolved;
+  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 });
+
+  if (workspaces) {
+    includeInWorkspaces(tree, directory);
+  } else {
+    for (const problem of native.conflicts(readJson(tree, 'package.json'))) logger.warn(problem);
+    // `nxViteTsPaths()`, which the app's Vitest config uses to reach the workspace's libraries.
+    // Added now rather than only when present, because a library generated later is the ordinary
+    // case and nothing would come back to add it then.
+    const aliases = tree.exists('tsconfig.base.json')
+      ? { '@nx/vite': workspaceNxVersion(tree) }
+      : {};
+    addDependenciesToPackageJson(
+      tree,
+      native.dependencies,
+      { ...native.devDependencies, ...aliases },
+      'package.json',
+      true,
+    );
+  }
+  writeFiles(tree, resolved);
+  addProjectConfiguration(tree, projectName, {
+    root: directory,
+    sourceRoot: directory,
+    projectType: 'application',
+    tags: (options.tags ?? '')
+      .split(',')
+      .map((tag) => tag.trim())
+      .filter(Boolean),
+    targets: targets(directory),
+  });
+
+  ignoreExpo(tree);
+
+  if (!options.skipFormat) await formatFiles(tree);
+  logger.info(
+    `Created ${directory}. nx start ${projectName} runs Metro; nx run ${projectName}:run-ios, ` +
+      `nx test ${projectName}, nx typecheck ${projectName}, nx export ${projectName}.`,
+  );
+  if (options.skipInstall) return initTask;
+  return runTasksInSerial(initTask, () => installPackagesTask(tree, true));
+}
+
+module.exports = { application };

package/application/schema.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "https://json-schema.org/schema",
+  "$id": "NgNativeNxApplication",
+  "title": "Angular Native application",
+  "type": "object",
+  "properties": {
+    "directory": {
+      "type": "string",
+      "description": "Where the app goes, relative to the workspace root: apps/mobile.",
+      "$default": { "$source": "argv", "index": 0 },
+      "x-prompt": "Which directory should the app be created in?"
+    },
+    "name": {
+      "type": "string",
+      "description": "The project name. Defaults to the directory's last segment.",
+      "pattern": "^[a-z][a-z0-9-]*$"
+    },
+    "tags": {
+      "type": "string",
+      "description": "Comma-separated tags for the project."
+    },
+    "skipInstall": {
+      "type": "boolean",
+      "description": "Write the files without installing.",
+      "default": false
+    },
+    "skipFormat": {
+      "type": "boolean",
+      "description": "Leave the generated files unformatted.",
+      "default": false,
+      "x-priority": "internal"
+    }
+  },
+  "required": ["directory"]
+}

package/application/workspaces.cjs

@@ -0,0 +1,68 @@
+/**
+ * The package manager's workspaces, which decide where an app's dependencies go.
+ *
+ * An app outside every workspace glob is not a workspace package: pnpm installs nothing for it,
+ * and its `metro.config.js` cannot find Expo. Nx's own TypeScript preset starts with `packages/*`
+ * only, so an app in `apps/` is outside it until the glob is added.
+ */
+const { minimatch } = require('minimatch');
+const { readJson, updateJson } = require('@nx/devkit');
+
+const PNPM = 'pnpm-workspace.yaml';
+
+/** The `packages:` list of a `pnpm-workspace.yaml`, as written: one quoted or bare glob a line. */
+function pnpmGlobs(yaml) {
+  const block = /^packages:[ \t]*\n((?:[ \t]+-.*\n?)*)/m.exec(yaml)?.[1] ?? '';
+  return [...block.matchAll(/^[ \t]+-\s*['"]?([^'"\n#]+?)['"]?\s*(?:#.*)?$/gm)].map(
+    (match) => match[1],
+  );
+}
+
+function manifestGlobs(tree) {
+  const { workspaces } = readJson(tree, 'package.json');
+  return Array.isArray(workspaces) ? workspaces : (workspaces?.packages ?? []);
+}
+
+function globs(tree) {
+  if (tree.exists(PNPM)) return pnpmGlobs(tree.read(PNPM, 'utf-8') ?? '');
+  return manifestGlobs(tree);
+}
+
+/**
+ * Whether the workspace has package-manager workspaces at all. A `pnpm-workspace.yaml` with no
+ * `packages:` list does not: pnpm 11 writes one to hold settings alone, in an integrated
+ * workspace like the `angular-monorepo` preset's.
+ */
+function usesWorkspaces(tree) {
+  return globs(tree).length > 0;
+}
+
+/**
+ * Adds `<parent>/*` for the app's directory when no glob already covers it.
+ *
+ * @param {import('@nx/devkit').Tree} tree
+ * @param {string} directory
+ */
+function includeInWorkspaces(tree, directory) {
+  // A negated glob excludes; it never makes a directory a workspace package.
+  const including = globs(tree).filter((glob) => !glob.startsWith('!'));
+  if (including.some((glob) => minimatch(directory, glob))) return;
+  const parent = directory.includes('/') ? directory.slice(0, directory.lastIndexOf('/')) : '';
+  const glob = parent ? `${parent}/*` : directory;
+
+  if (tree.exists(PNPM)) {
+    const yaml = tree.read(PNPM, 'utf-8') ?? '';
+    const next = /^packages:[ \t]*$/m.test(yaml)
+      ? yaml.replace(/^packages:[ \t]*$/m, `packages:\n  - '${glob}'`)
+      : `packages:\n  - '${glob}'\n${yaml}`;
+    tree.write(PNPM, next);
+    return;
+  }
+  updateJson(tree, 'package.json', (manifest) => {
+    if (Array.isArray(manifest.workspaces)) manifest.workspaces.push(glob);
+    else manifest.workspaces.packages = [...(manifest.workspaces.packages ?? []), glob];
+    return manifest;
+  });
+}
+
+module.exports = { usesWorkspaces, includeInWorkspaces, pnpmGlobs };

package/files/AGENTS.md

@@ -0,0 +1,75 @@
+# AGENTS.md
+
+This is an Angular app rendering real native iOS and Android views with
+[Angular Native](https://ng-native.com): Angular components on React Native's Fabric renderer,
+inside an Expo app. It is not a web app and not React: there is no DOM and no JSX.
+
+The whole documentation, for reading before a change: https://ng-native.com/llms-full.txt. An
+outline with a line per page: https://ng-native.com/llms.txt.
+
+Angular's own rules apply as well: https://angular.dev/assets/context/best-practices.md. Its
+browser-only parts do not: there is no `NgOptimizedImage` (use `<image>`), and no AXE or ARIA
+(accessibility is the props below). Where the two disagree, this file wins.
+
+## Commands
+
+```sh
+npm start           # Metro; press i or a for a simulator, or scan the QR code with Expo Go
+npm run ios         # the iOS simulator
+npm run android     # the Android emulator
+npm test            # Vitest, in Node against a fake native layer: no simulator needed
+npm run typecheck
+```
+
+`src/main.ts` mounts the root component, `src/app/app.ts`. Run `npm test` and `npm run typecheck` after a
+change; both are fast.
+
+## Rules that are easy to get wrong
+
+- **Element names are lowercase:** `<view>`, `<text>`, `<pressable>`, `<scroll-view>`,
+  `<text-input>`, `<image>`, `<switch>`, `<safe-area-view>`, `<virtual-list>`, `<modal>`. Each is
+  imported from `@ng-native/components` into the component's `imports`, like any Angular
+  component: `imports: [View, Text]`. `<View>` compiles to an empty template, and an element used
+  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.
+- **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)="...">`.
+- **Signals, zoneless, AOT.** State is signals and `computed()`; there is no zone.js, so nothing
+  updates from a plain field changing outside a signal or an event.
+- **No backticks inside an inline template**, even in an HTML comment: they end the template string
+  and the build fails with a misleading parse error.
+- **Accessibility is props:** `accessibilityRole="button"`, `accessibilityLabel`,
+  `[accessibilityState]`. Screen readers and the testing library's `getByRole` both read them.
+
+## Styling
+
+- `[style]` takes a React Native style object: camelCase keys, numbers in points
+  (`{ padding: 16, backgroundColor: '#fff' }`).
+- A component's `styles` is real CSS, compiled at build time: type, class, id and attribute
+  selectors, combinators, `:host`, `@media`, custom properties, transitions and `@keyframes`.
+  Grid, float, `::before`/`::after`, `:hover` and `:focus-visible` are dropped with a build
+  warning naming the file, line and reason - lay out with flexbox, and drive a hover or focus look
+  from a bound attribute. Everything is `display: flex`
+  with `flex-direction: column` by default, as in React Native.
+- Tailwind v4 works through `@ng-native/tailwind`, with `ios:`, `android:` and `dark:` variants.
+
+## Lists, navigation, forms
+
+- A long list is `<virtual-list>`: `@for (row of list.window(); track row.slot)` recycles rows as
+  they scroll. `<scroll-view>` renders everything, so keep it for short content.
+- Navigation is `@angular/router` on native stacks and tabs: `provideNativeRouter(routes)` from
+  `@ng-native/router` in `mount`'s `providers`, and `<native-stack-outlet />` in a template. Add
+  `withComponentInputBinding()` from `@angular/router` for route params to arrive as inputs, in
+  tests too.
+- Forms are Signal Forms (`@angular/forms/signals`), with `[formField]` on `<text-input>` and
+  `<switch>`.
+- HTTP needs `provideNativeHttpClient()` from `@ng-native/platform/http`, not `provideHttpClient()`.
+
+## Tests
+
+`app.test.ts` shows the shape: `render(Component)`, then query with `screen.getByRole`,
+`getByText` or `getByTestId` (which matches `nativeID` and `testID`), and act with
+`userEvent.setup().press(...)` or `.type(...)`, all from `@ng-native/testing`. Tests run in Node
+with no simulator, so write one alongside a change.

package/files/src/app/app.test.ts

@@ -0,0 +1,11 @@
+import { render, screen, userEvent } from '@ng-native/testing';
+import { expect, test } from 'vitest';
+import { App } from './app.ts';
+
+test('counts taps', async () => {
+  await render(App);
+
+  await userEvent.setup().press(screen.getByRole('button', { name: 'Tapped 0 times' }));
+
+  expect(screen.getByText('Tapped 1 times')).toBeTruthy();
+});

package/files/src/app/app.ts

@@ -0,0 +1,62 @@
+import { Component, signal } from '@angular/core';
+import { Pressable, SafeAreaView, Text, View } from '@ng-native/components';
+
+/**
+ * Element names are lowercase, and that is load-bearing rather than style: an uppercase name is
+ * read as an unknown Angular component and commits as a plain view with nothing in it.
+ */
+@Component({
+  imports: [Pressable, SafeAreaView, Text, View],
+  selector: 'app-root',
+  template: `
+    <safe-area-view class="screen">
+      <view class="body">
+        <text class="title">Angular, natively</text>
+        <text class="hint">Real native views. React is never in the render path.</text>
+
+        <pressable accessibilityRole="button" class="button" (press)="count.set(count() + 1)">
+          <text class="label">Tapped {{ count() }} times</text>
+        </pressable>
+      </view>
+    </safe-area-view>
+  `,
+  styles: `
+    :host {
+      flex: 1;
+    }
+    .screen {
+      flex: 1;
+      background-color: #101014;
+    }
+    .body {
+      flex: 1;
+      justify-content: center;
+      gap: 12px;
+      padding: 24px;
+    }
+    .title {
+      color: #ffffff;
+      font-size: 28px;
+      font-weight: 700;
+    }
+    .hint {
+      color: #8b8b96;
+      font-size: 15px;
+    }
+    .button {
+      align-items: center;
+      margin-top: 8px;
+      padding: 14px;
+      border-radius: 10px;
+      background-color: #3b6ef5;
+    }
+    .label {
+      color: #ffffff;
+      font-size: 16px;
+      font-weight: 600;
+    }
+  `,
+})
+export class App {
+  protected readonly count = signal(0);
+}

package/files/src/main.ts

@@ -0,0 +1,27 @@
+import { AppRegistry, Image, Platform, processColor } from 'react-native';
+import { mount } from '@ng-native/platform';
+import { currentConditions, deviceTokens, watchConditions } from '@ng-native/device';
+import { getFabricUIManager, registerPlatformComponents } from '@ng-native/fabric';
+import { App } from './app/app.ts';
+
+registerPlatformComponents(Platform.OS);
+
+AppRegistry.registerRunnable('main', ({ rootTag }: { rootTag: number | string }) => {
+  const app = mount(Number(rootTag), App, getFabricUIManager(), {
+    // Colours, as the integers the platform wants.
+    processColor,
+    // What `@media` resolves against. Without it every media query is false and a responsive
+    // layout renders as its smallest case.
+    conditions: currentConditions(),
+    // Values only the device knows - the hairline width, which is a third of a point on a 3x
+    // screen. Without it `1px` is what you get, and that is a visibly fat divider.
+    tokens: deviceTokens(),
+    // Turns a `require('./x.png')` into something native can load. Without it images are blank.
+    resolveAssetSource: (value) => Image.resolveAssetSource(value as never),
+  });
+
+  // Re-resolves the conditions when the device rotates or the theme changes. A rotation dirties
+  // no component and no binding, so without this nothing re-renders and `dark:` stops following
+  // the system switch.
+  watchConditions(app.engine);
+});

package/files/vitest.config.mts

@@ -0,0 +1,8 @@
+import { ngNative } from '@ng-native/testing/vitest';
+import { defineConfig } from 'vitest/config';
+
+// Compiles Angular for the tests the way Metro compiles it for the app. Tests run in Node against
+// a fake of the native side: no simulator, no device.
+export default defineConfig({
+  plugins: [ngNative()],
+});

package/generators.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "../../node_modules/nx/schemas/generators-schema.json",
+  "name": "@ng-native/nx",
+  "generators": {
+    "init": {
+      "factory": "./init/index.cjs#init",
+      "schema": "./init/schema.json",
+      "description": "Registers @nx/expo's plugin, which infers the Expo targets. nx add runs this.",
+      "hidden": true
+    },
+    "application": {
+      "aliases": ["app"],
+      "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."
+    }
+  }
+}

package/init/index.cjs

@@ -0,0 +1,79 @@
+/**
+ * `nx add @ng-native/nx`, and the first step of every app generated here.
+ *
+ * An Angular Native app is an Expo app, so its targets are Expo's, and `@nx/expo`'s plugin already
+ * infers them from any project with an `app.json`, a `metro.config.js` and a `package.json`:
+ * `start`, `run-ios`, `run-android`, `export`, `prebuild`, and EAS `build` and `submit`. This adds
+ * `@nx/expo` at the workspace's own Nx version and registers that plugin.
+ *
+ * It does not run `@nx/expo:init`, which installs Expo itself at the SDK `@nx/expo` was released
+ * against. On Nx 23.2 that is SDK 56, with `@expo/cli` 56 and a `react-dom` that asks for React
+ * 19.3, and an Angular Native app needs SDK 57 and React 19.2.3: npm refuses the install.
+ *
+ * Two things `init` would have added, it adds itself at the versions the app needs. `react-dom`,
+ * because `@nx/expo` depends on `@nx/react`, whose `react-dom` peer npm otherwise takes at the
+ * newest React and then refuses every later install beside React 19.2.3. And `@expo/cli`, which
+ * `@nx/expo`'s prebuild executor loads from the root, where npm does not put it on its own.
+ */
+const {
+  addDependenciesToPackageJson,
+  formatFiles,
+  readJson,
+  readNxJson,
+  updateNxJson,
+  NX_VERSION,
+} = require('@nx/devkit');
+const native = require('../native-app.cjs');
+
+/** The plugin entry `@nx/expo:init` itself writes, so the target names are the ones Nx documents. */
+const EXPO_PLUGIN = {
+  plugin: '@nx/expo/plugin',
+  options: {
+    startTargetName: 'start',
+    buildTargetName: 'build',
+    prebuildTargetName: 'prebuild',
+    serveTargetName: 'serve',
+    installTargetName: 'install',
+    exportTargetName: 'export',
+    submitTargetName: 'submit',
+    runIosTargetName: 'run-ios',
+    runAndroidTargetName: 'run-android',
+    buildDepsTargetName: 'build-deps',
+    watchDepsTargetName: 'watch-deps',
+  },
+};
+
+/** The Nx this workspace installed, which every `@nx/*` package in it has to match. */
+function workspaceNxVersion(tree) {
+  const manifest = readJson(tree, 'package.json');
+  return manifest.devDependencies?.nx ?? manifest.dependencies?.nx ?? NX_VERSION;
+}
+
+function registerExpoPlugin(tree) {
+  const nxJson = readNxJson(tree) ?? {};
+  const plugins = nxJson.plugins ?? [];
+  const registered = plugins.some(
+    (entry) => (typeof entry === 'string' ? entry : entry.plugin) === EXPO_PLUGIN.plugin,
+  );
+  if (registered) return;
+  updateNxJson(tree, { ...nxJson, plugins: [...plugins, EXPO_PLUGIN] });
+}
+
+/**
+ * @param {import('@nx/devkit').Tree} tree
+ * @param {{ skipInstall?: boolean, skipFormat?: boolean }} options
+ */
+async function init(tree, options = {}) {
+  registerExpoPlugin(tree);
+  const install = addDependenciesToPackageJson(
+    tree,
+    {},
+    { '@nx/expo': workspaceNxVersion(tree), ...native.expoCompanions },
+    'package.json',
+    true,
+  );
+  if (!options.skipFormat) await formatFiles(tree);
+  return options.skipInstall ? () => {} : install;
+}
+
+module.exports = { init, workspaceNxVersion, EXPO_PLUGIN };

package/init/schema.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://json-schema.org/schema",
+  "$id": "NgNativeNxInit",
+  "title": "Set up Angular Native",
+  "type": "object",
+  "properties": {
+    "skipInstall": {
+      "type": "boolean",
+      "description": "Update package.json without installing.",
+      "default": false
+    },
+    "skipFormat": {
+      "type": "boolean",
+      "description": "Leave the changed files unformatted.",
+      "default": false,
+      "x-priority": "internal"
+    },
+    "keepExistingVersions": {
+      "type": "boolean",
+      "description": "Passed by nx add. Existing versions are always kept.",
+      "default": true,
+      "x-priority": "internal"
+    },
+    "updatePackageScripts": {
+      "type": "boolean",
+      "description": "Passed by nx add. There are no package scripts to update.",
+      "x-priority": "internal"
+    }
+  }
+}

package/native-app.cjs

@@ -0,0 +1,246 @@
+/**
+ * What an Angular Native app is made of, in an Nx workspace.
+ *
+ * The source of truth is `template/`, the starter `create-expo-app` uses and the setup this project
+ * verifies before every release. `files/` holds verbatim copies of the template's source files and
+ * the versions below are the template's own, and `native-app.test.ts` fails the moment either
+ * drifts from it.
+ *
+ * Three files differ from the template's, each because of something Nx does:
+ *
+ * - `metro.config.js` wraps the preset in `withNxMetro`, which resolves the workspace's tsconfig
+ *   path aliases and watches its libraries. Without it an app in an integrated workspace cannot
+ *   import a library at all: Metro reports `Cannot resolve @org/ui`.
+ * - `tsconfig.json` also extends the workspace's `tsconfig.base.json` when there is one, which is
+ *   where those aliases live, and puts back the Expo settings the workspace's base overrides.
+ * - `vitest.config.mts` adds `nxViteTsPaths` when the workspace has `@nx/vite`, for the same
+ *   aliases, which Vitest does not read from tsconfig either.
+ *
+ * The `@ng-native/*` packages are pinned to this package's own version, because every one of them
+ * is released in lockstep with it.
+ */
+const { readFileSync } = require('node:fs');
+const path = require('node:path');
+const semver = require('semver');
+
+const { version } = require('./package.json');
+
+const FRAMEWORK = [
+  '@ng-native/components',
+  '@ng-native/device',
+  '@ng-native/fabric',
+  '@ng-native/metro',
+  '@ng-native/platform',
+];
+
+/** @type {Record<string, string>} */
+const dependencies = {
+  ...Object.fromEntries(FRAMEWORK.map((name) => [name, version])),
+  '@angular/common': '^22.0.0',
+  '@angular/core': '^22.0.0',
+  expo: '~57.0.20',
+  'expo-status-bar': '~57.0.1',
+  react: '19.2.3',
+  'react-native': '0.86.3',
+  'react-native-safe-area-context': '~5.7.0',
+};
+
+/**
+ * What `nx add` puts beside `@nx/expo`, in place of the `@nx/expo:init` it does not run: see
+ * `init/index.cjs`. `@expo/cli` is the range the template's `expo` depends on.
+ */
+const expoCompanions = { 'react-dom': dependencies.react, '@expo/cli': '^57.0.22' };
+
+/** @type {Record<string, string>} */
+const devDependencies = {
+  // An Angular workspace already has Babel 8 through @angular/compiler-cli, and React Native's
+  // Babel peer would otherwise take the newest copy there is.
+  // The typecheck script compiles the templates too, which only the Angular compiler can.
+  '@angular/compiler-cli': '^22.0.0',
+  '@babel/core': '^7.29.7',
+  '@ng-native/testing': version,
+  '@types/react': '~19.2.2',
+  typescript: '~6.0.3',
+  vitest: '^5.0.0',
+};
+
+/** The template's files, copied verbatim into the new app. */
+const SOURCE_FILES = ['src/app/app.ts', 'src/main.ts', 'src/app/app.test.ts'];
+
+/** @param {string} name */
+function sourceFile(name) {
+  return readFileSync(path.join(__dirname, 'files', name), 'utf8');
+}
+
+/**
+ * The template's `AGENTS.md`, with its Commands section replaced by this workspace's own. The rest
+ * describes the framework, which is the same wherever the app lives.
+ *
+ * @param {string} commands the markdown that goes under the Commands heading
+ */
+function agentsFile(commands) {
+  return sourceFile('AGENTS.md').replace(
+    /## Commands\n[\s\S]*?(?=\n## )/,
+    `## Commands\n\n${commands}\n`,
+  );
+}
+
+/**
+ * The template's `app.json`, named for this app, without the template's icons: they are the
+ * template's branding, and Expo draws its own default until `icon` is set.
+ *
+ * @param {string} name the project name, which is also the Expo slug
+ */
+function appJson(name) {
+  const slug = name.replace(/^@[^/]+\//, '');
+  const expo = {
+    name: slug,
+    slug,
+    version: '1.0.0',
+    // Not left to Expo, which adds `web` whenever `react-dom` resolves, and @nx/react puts one there.
+    platforms: ['ios', 'android'],
+    orientation: 'portrait',
+    userInterfaceStyle: 'dark',
+    ios: { supportsTablet: true },
+    android: { predictiveBackGestureEnabled: false },
+    scheme: slug.replace(/[^a-z0-9]/gi, '').toLowerCase(),
+  };
+  return JSON.stringify({ expo }, null, 2) + '\n';
+}
+
+const METRO_CONFIG = `const { withNxMetro } = require('@nx/expo');
+const { getDefaultConfig } = require('expo/metro-config');
+const { withAngularNative } = require('@ng-native/metro/config.cjs');
+
+// withNxMetro resolves the workspace's libraries, through its tsconfig path aliases or its package
+// manager's links, and watches them. withAngularNative registers the transformer that compiles
+// Angular ahead of time, compiles each component's CSS into the sheet the engine reads, and adds
+// the polyfills Angular needs before \`@angular/core\` is first evaluated. It goes on the outside,
+// so its resolver can wrap Nx's: a library's \`./lib/ui.js\` import has to find \`ui.ts\`.
+module.exports = withAngularNative(withNxMetro(getDefaultConfig(__dirname)));
+`;
+
+/**
+ * @param {string | undefined} workspaceBase the workspace's `tsconfig.base.json`, relative to the
+ *   app, when there is one to take path aliases from
+ */
+function tsconfig(workspaceBase, conditions = []) {
+  const compilerOptions = { strict: true, allowImportingTsExtensions: true };
+  // The template's own: templates checked strictly, less the two checks that read a native host
+  // element's props and events as a DOM element's.
+  const angularCompilerOptions = {
+    strictTemplates: true,
+    typeCheckHostBindings: false,
+    strictDomEventTypes: false,
+  };
+  if (!workspaceBase) {
+    // The workspace's custom conditions, which a library in Nx's TypeScript preset exports its
+    // source under; the Metro preset and the Vitest plugin read them from here too. Beside
+    // Expo's own `react-native`, which setting the option would otherwise replace.
+    const extra = conditions.filter((c) => c !== 'react-native');
+    if (extra.length) compilerOptions.customConditions = ['react-native', ...extra];
+    return { extends: 'expo/tsconfig.base', compilerOptions, angularCompilerOptions };
+  }
+  // The workspace's base is written for a web build or for emitting declarations, and wins over
+  // Expo's where they overlap. These are Expo's, restored: without `DOM` and `ESNext` the framework
+  // packages' own source, which the app compiles, fails to typecheck.
+  return {
+    extends: ['expo/tsconfig.base', workspaceBase],
+    compilerOptions: {
+      ...compilerOptions,
+      noEmit: true,
+      lib: ['DOM', 'ESNext'],
+      target: 'ESNext',
+      module: 'preserve',
+      moduleResolution: 'bundler',
+      customConditions: ['react-native'],
+      composite: false,
+      declaration: false,
+      emitDeclarationOnly: false,
+    },
+    angularCompilerOptions,
+  };
+}
+
+/** @param {boolean} withPaths whether to resolve the workspace's tsconfig path aliases */
+function vitestConfig(withPaths) {
+  const template = readFileSync(path.join(__dirname, 'files', 'vitest.config.mts'), 'utf8');
+  if (!withPaths) return template;
+  return template
+    .replace(
+      "import { defineConfig } from 'vitest/config';",
+      "import { nxViteTsPaths } from '@nx/vite/plugins/nx-tsconfig-paths.plugin';\n" +
+        "import { defineConfig } from 'vitest/config';",
+    )
+    .replace('plugins: [ngNative()],', 'plugins: [nxViteTsPaths(), ngNative()],');
+}
+
+/**
+ * The dependencies an integrated workspace's app lists in its own `package.json`, at the ranges
+ * the root installs, though nothing installs from it.
+ *
+ * All of them, because Expo's autolinking links the native modules the app's `package.json` names
+ * and no others: without `react-native-safe-area-context` here, Android crashed on RNCSafeAreaView.
+ * And `expo prebuild`, which `expo run:ios` starts with, adds `expo`, `react` or `react-native` if
+ * it does not find them and then offers to install them into the app's directory, which would put a
+ * second copy of React Native beside the root's.
+ *
+ * @param {{ dependencies?: Record<string, string>, devDependencies?: Record<string, string> }} root
+ */
+function prebuildPins(root) {
+  const installed = { ...root.devDependencies, ...root.dependencies };
+  return Object.fromEntries(
+    Object.keys(dependencies).map((pkg) => [pkg, installed[pkg] ?? dependencies[pkg]]),
+  );
+}
+
+/**
+ * Where what a workspace already has can be older than what a new app is given: `@ng-native/testing`
+ * installs Vitest 5 but its plugin runs on 4, which `ng new` 22.1 and the Nx preset still start on.
+ * The range here is that package's `vitest` peer, and a test holds the two together.
+ */
+const accepted = { vitest: '^4.0.8 || ^5.0.0' };
+
+/**
+ * Why an existing dependency would stop this app installing or running, as a sentence each.
+ *
+ * Only ranges already in the manifest are judged, and only a range that cannot overlap the one
+ * wanted is a conflict: `~6.0.2` and `~6.0.3` resolve to the same TypeScript. A missing package is
+ * added at the version above. Nothing is rewritten, because moving a workspace's Angular or Vitest
+ * is an upgrade of every project in it, and that belongs to `nx migrate`, not to a generator.
+ *
+ * @param {{ dependencies?: Record<string, string>, devDependencies?: Record<string, string> }} manifest
+ * @returns {string[]}
+ */
+function conflicts(manifest) {
+  const existing = { ...manifest.dependencies, ...manifest.devDependencies };
+  const problems = [];
+  for (const [name, installed] of Object.entries({ ...dependencies, ...devDependencies })) {
+    const range = existing[name];
+    const wanted = accepted[name] ?? installed;
+    if (!range || name.startsWith('@ng-native/')) continue;
+    if (semver.validRange(range) && !semver.intersects(range, wanted)) {
+      problems.push(
+        `${name} is ${range} here, and Angular Native needs ${wanted}. ` +
+          `npm will refuse the install until it is moved.`,
+      );
+    }
+  }
+  return problems;
+}
+
+module.exports = {
+  dependencies,
+  devDependencies,
+  SOURCE_FILES,
+  sourceFile,
+  agentsFile,
+  appJson,
+  METRO_CONFIG,
+  tsconfig,
+  vitestConfig,
+  prebuildPins,
+  expoCompanions,
+  conflicts,
+  accepted,
+};

package/package.json

@@ -1,12 +1,61 @@
 {
   "name": "@ng-native/nx",
-  "version": "0.0.1",
-  "description": "Reserved for ng-native. The first release follows.",
+  "version": "0.1.0",
+  "description": "Nx generators for Angular Native: nx add, and an Expo app project whose targets run it.",
+  "keywords": [
+    "angular",
+    "react-native",
+    "angular-native",
+    "ios",
+    "android",
+    "fabric",
+    "native",
+    "nx",
+    "nx-plugin",
+    "generators",
+    "expo"
+  ],
+  "type": "module",
+  "generators": "./generators.json",
+  "dependencies": {
+    "@nx/devkit": "^23.0.0",
+    "minimatch": "^10.0.0",
+    "semver": "^7.7.0"
+  },
+  "peerDependencies": {
+    "nx": "^23.0.0"
+  },
+  "devDependencies": {
+    "@types/semver": "^7.7.0"
+  },
+  "nx": {
+    "tags": [
+      "scope:nx",
+      "layer:build"
+    ]
+  },
   "license": "MIT",
+  "homepage": "https://ng-native.com/packages/nx",
+  "bugs": {
+    "url": "https://github.com/ng-native/ng-native/issues"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ng-native/ng-native.git",
     "directory": "packages/nx"
   },
-  "homepage": "https://ng-native.com/packages/nx"
+  "files": [
+    "*.cjs",
+    "generators.json",
+    "*/*.cjs",
+    "*/*.json",
+    "files"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --test \"*.test.ts\" \"{init,application}/*.test.ts\""
+  }
 }