@ng-native/schematics 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/schematics
 
-A placeholder: this version has no code. See https://ng-native.com.
+`ng add` and `ng generate` for Angular Native: an Expo app added to an Angular CLI workspace,
+beside its web app, with builders that let `ng serve`, `ng build` and `ng test` run it.
+
+Alpha: APIs may change before 1.0.
+
+## Install
+
+```sh
+ng add @ng-native/schematics
+```
+
+That writes the template's app to `projects/native`, registers it in `angular.json`, and installs
+its dependencies into the workspace's root `package.json`. For an app on its own, without a
+workspace, use `npx create-expo-app@latest my-app --template @ng-native/template` instead.
+
+## Example
+
+```sh
+ng serve native                  # expo start: Metro, with Expo Go or a simulator
+ng build native                  # expo export, into dist/native
+ng test native                   # vitest run, on the fake Fabric
+ng run native:run-ios            # expo run:ios
+
+cd projects/native && ng generate component profile-card   # <view>, <text>, and a test
+```
+
+## What's in the package
+
+- `collection.json` - the `ng-add`, `application` and `component` schematics.
+- `builders.json` - `@ng-native/schematics:expo`, which runs an Expo CLI command in the project, and
+  `@ng-native/schematics:vitest`, which runs its tests.
+- `files/` - the template's source files, which a test keeps identical to `template/`.
+
+## Docs
+
+- [Angular CLI](https://ng-native.com/packages/schematics)
+- [Root README](https://github.com/ng-native/ng-native/blob/main/README.md)
+
+## License
+
+MIT

package/application/index.cjs

@@ -0,0 +1,164 @@
+/**
+ * `ng generate @ng-native/schematics:application`: an Angular Native app inside an Angular CLI
+ * workspace.
+ *
+ * The app is an Expo project in its own directory, beside whatever web app the workspace already
+ * has, and Metro builds it rather than `@angular/build`. What makes it a project of this workspace
+ * is its entry in `angular.json`: the builders there run Expo, so `ng serve native` starts Metro,
+ * `ng build native` exports a bundle and `ng test native` runs its tests in Node.
+ *
+ * Its dependencies go in the root `package.json`, because an Angular CLI workspace has one. The
+ * project's own `package.json` is for Expo, which reads `main` from it to find the entry file.
+ */
+const path = require('node:path').posix;
+const { SchematicsException } = require('@angular-devkit/schematics');
+const { NodePackageInstallTask } = require('@angular-devkit/schematics/tasks');
+const native = require('../native-app.cjs');
+
+function readJson(tree, file) {
+  return JSON.parse(tree.readText(file));
+}
+
+function writeJson(tree, file, value) {
+  tree.overwrite(file, JSON.stringify(value, null, 2) + '\n');
+}
+
+/**
+ * The project's targets. Each is an Expo command run in the project's directory, which is where
+ * Expo reads `app.json` and `metro.config.js` from.
+ */
+function targets(root, name) {
+  const expo = (command, args) => ({
+    builder: '@ng-native/schematics:expo',
+    options: args ? { command, args } : { command },
+  });
+  // Beside the workspace's other build output, rather than in a `dist/` inside the project.
+  const outputDir = path.relative(root, path.join('dist', name));
+  return {
+    serve: expo('start'),
+    build: expo('export', ['--output-dir', outputDir]),
+    'run-ios': expo('run:ios'),
+    'run-android': expo('run:android'),
+    test: { builder: '@ng-native/schematics:vitest', options: {} },
+  };
+}
+
+/**
+ * Angular's own schematics, which write a spec this project cannot run: each assumes Vitest's
+ * globals and most assume `TestBed` on a DOM, and a test here renders onto the fake Fabric.
+ */
+const WEB_SPECS = [
+  'class',
+  'component',
+  'directive',
+  'guard',
+  'interceptor',
+  'pipe',
+  'resolver',
+  'service',
+];
+
+function project(root, name, prefix) {
+  return {
+    projectType: 'application',
+    root,
+    sourceRoot: root,
+    prefix,
+    // `ng generate component` run inside this project makes a native component, with `<view>` and
+    // a test that runs on the fake Fabric. Anything this collection does not have, a service or a
+    // pipe, falls through to Angular's own. Only inside it: `--project` from the workspace root
+    // does not switch collections, which is the Angular CLI's rule rather than this project's.
+    cli: { schematicCollections: ['@ng-native/schematics', '@schematics/angular'] },
+    schematics: Object.fromEntries(
+      WEB_SPECS.map((schematic) => [`@schematics/angular:${schematic}`, { skipTests: true }]),
+    ),
+    architect: targets(root, name),
+  };
+}
+
+/** The Commands section of the app's `AGENTS.md`, as this workspace runs them. */
+function commands(name) {
+  const rows = [
+    [`ng serve ${name}`, 'Metro; press i or a for a simulator, or scan the QR code with Expo Go'],
+    [`ng run ${name}:run-ios`, 'the iOS simulator'],
+    [`ng run ${name}:run-android`, 'the Android emulator'],
+    [`ng test ${name}`, 'Vitest, in Node against a fake native layer: no simulator needed'],
+    [`ng build ${name}`, 'an exported bundle'],
+  ];
+  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 \`ng test ${name}\` after a change; it is fast.`,
+  ].join('\n');
+}
+
+function writeFiles(tree, root, name) {
+  for (const file of native.SOURCE_FILES) {
+    tree.create(path.join(root, file), native.sourceFile(file));
+  }
+  tree.create(path.join(root, 'app.json'), native.appJson(name));
+  tree.create(path.join(root, 'AGENTS.md'), native.agentsFile(commands(name)));
+  tree.create(path.join(root, 'CLAUDE.md'), '@AGENTS.md\n');
+  const manifest = native.projectManifest(name, readJson(tree, 'package.json'));
+  tree.create(path.join(root, 'package.json'), JSON.stringify(manifest, null, 2) + '\n');
+}
+
+/** Adds what is missing and leaves every version the workspace already chose alone. */
+function addDependencies(tree, context) {
+  const manifest = readJson(tree, 'package.json');
+  for (const problem of native.conflicts(manifest)) context.logger.warn(problem);
+  for (const field of ['dependencies', 'devDependencies']) {
+    const existing = { ...manifest.dependencies, ...manifest.devDependencies };
+    const added = Object.entries(native[field]).filter(([name]) => !(name in existing));
+    manifest[field] = Object.fromEntries(
+      [...Object.entries(manifest[field] ?? {}), ...added].sort(([a], [b]) => (a < b ? -1 : 1)),
+    );
+  }
+  writeJson(tree, 'package.json', manifest);
+}
+
+/** Expo's cache directory, once, wherever the project is. */
+function ignoreExpo(tree) {
+  if (!tree.exists('.gitignore')) return;
+  const ignore = tree.readText('.gitignore');
+  if (/^\.expo\/?$/m.test(ignore)) return;
+  tree.overwrite('.gitignore', ignore.replace(/\n*$/, '\n\n# Expo\n.expo/\n'));
+}
+
+/**
+ * @param {{ name: string, directory?: string, prefix?: string, skipInstall?: boolean }} options
+ */
+function application(options) {
+  return (tree, context) => {
+    if (!tree.exists('angular.json')) {
+      throw new SchematicsException(
+        'No angular.json here. This adds an app to an Angular CLI workspace; for an app on its ' +
+          'own, run: npx create-expo-app@latest my-app --template @ng-native/template',
+      );
+    }
+    const workspace = readJson(tree, 'angular.json');
+    const { name } = options;
+    if (workspace.projects?.[name]) {
+      throw new SchematicsException(`angular.json already has a project called "${name}".`);
+    }
+    const root = options.directory ?? path.join(workspace.newProjectRoot ?? 'projects', name);
+
+    addDependencies(tree, context);
+    writeFiles(tree, root, name);
+    workspace.projects = { ...workspace.projects, [name]: project(root, name, options.prefix) };
+    writeJson(tree, 'angular.json', workspace);
+    ignoreExpo(tree);
+
+    if (!options.skipInstall) context.addTask(new NodePackageInstallTask());
+    context.logger.info(
+      `Created ${root}. Run it with: ng serve ${name} (Metro), ng run ${name}:run-ios, ` +
+        `ng test ${name}, ng build ${name}.`,
+    );
+  };
+}
+
+module.exports = { application, targets };

package/application/schema.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema",
+  "$id": "NgNativeApplication",
+  "title": "Angular Native application",
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "The project name, in angular.json and as the Expo slug.",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "$default": { "$source": "argv", "index": 0 },
+      "x-prompt": "What should the native app be called?"
+    },
+    "directory": {
+      "type": "string",
+      "description": "Where the project goes. Defaults to newProjectRoot/name, usually projects/name."
+    },
+    "prefix": {
+      "type": "string",
+      "description": "The selector prefix for components generated in this project.",
+      "default": "app",
+      "pattern": "^[a-z][a-z0-9-]*$"
+    },
+    "skipInstall": {
+      "type": "boolean",
+      "description": "Write the files and package.json without installing.",
+      "default": false
+    }
+  },
+  "required": ["name"]
+}

package/builders/expo.cjs

@@ -0,0 +1,25 @@
+/**
+ * `@ng-native/schematics:expo`: an Expo CLI command, run in the project.
+ *
+ * `ng serve native` is `expo start`, `ng build native` is `expo export` and
+ * `ng run native:run-ios` is `expo run:ios`. Nothing is translated: Metro builds an Angular Native
+ * app, Expo drives Metro, and this is how `ng` reaches it.
+ */
+const { createBuilder } = require('@angular-devkit/architect');
+const { spawnBin } = require('./spawn-bin.cjs');
+
+/**
+ * The Expo CLI's arguments for a target's options.
+ *
+ * @param {{ command: string, args?: string[], platform?: string, port?: number, clear?: boolean }} options
+ */
+function expoArgs(options) {
+  const args = [options.command, ...(options.args ?? [])];
+  if (options.platform) args.push('--platform', options.platform);
+  if (options.port) args.push('--port', String(options.port));
+  if (options.clear) args.push('--clear');
+  return args;
+}
+
+module.exports = createBuilder((options, context) => spawnBin('expo', expoArgs(options), context));
+module.exports.expoArgs = expoArgs;

package/builders/expo.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema",
+  "$id": "NgNativeExpoBuilder",
+  "title": "Expo command",
+  "type": "object",
+  "properties": {
+    "command": {
+      "type": "string",
+      "description": "The Expo CLI command: start, export, run:ios, run:android, prebuild."
+    },
+    "args": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Arguments passed to the command as they are.",
+      "default": []
+    },
+    "platform": {
+      "type": "string",
+      "enum": ["ios", "android", "web", "all"],
+      "description": "Passed as --platform, for export."
+    },
+    "port": {
+      "type": "number",
+      "description": "Passed as --port: the port Metro listens on."
+    },
+    "clear": {
+      "type": "boolean",
+      "description": "Passed as --clear: start Metro with an empty transform cache."
+    }
+  },
+  "required": ["command"]
+}

package/builders/spawn-bin.cjs

@@ -0,0 +1,84 @@
+/**
+ * Runs a package's own CLI in an Angular Native project's directory, for the builders.
+ *
+ * The CLI is found from the project, not from this package, so it is the copy the app installed:
+ * `expo` from wherever the workspace hoisted it. It is found the way Node looks a package up, one
+ * `node_modules` at a time upwards, and not through `require.resolve`: a package's `exports` map
+ * can hide its bin file, as Vitest's does, or its `package.json`.
+ */
+const { spawn } = require('node:child_process');
+const { existsSync, readFileSync } = require('node:fs');
+const path = require('node:path');
+
+/** @param {string} name @param {string} from */
+function findManifest(name, from) {
+  for (let dir = path.resolve(from); ; dir = path.dirname(dir)) {
+    const manifest = path.join(dir, 'node_modules', name, 'package.json');
+    if (existsSync(manifest)) return manifest;
+    if (dir === path.dirname(dir))
+      throw new Error(`${name} is not installed, looking from ${from}.`);
+  }
+}
+
+/**
+ * @param {string} name the package, `expo` or `vitest`
+ * @param {string} from the directory to resolve it from
+ */
+function resolveBin(name, from) {
+  const manifestPath = findManifest(name, from);
+  const { bin } = JSON.parse(readFileSync(manifestPath, 'utf8'));
+  const file = typeof bin === 'string' ? bin : bin[name];
+  return path.join(path.dirname(manifestPath), file);
+}
+
+/**
+ * Where the target's project lives, as an absolute path.
+ *
+ * @param {import('@angular-devkit/architect').BuilderContext} context
+ */
+async function projectRoot(context) {
+  const project = context.target?.project;
+  if (!project) throw new Error('This builder runs as a project target, not on its own.');
+  const metadata = await context.getProjectMetadata(project);
+  return path.join(context.workspaceRoot, String(metadata['root'] ?? ''));
+}
+
+const SIGNALS = ['SIGINT', 'SIGTERM', 'SIGHUP'];
+
+/**
+ * Spawns the CLI with the terminal attached, so Metro's QR code and keyboard shortcuts work as
+ * they do under `npx expo start`, and resolves when it exits.
+ *
+ * @param {string} name
+ * @param {string[]} args
+ * @param {import('@angular-devkit/architect').BuilderContext} context
+ * @returns {Promise<{ success: boolean, error?: string }>}
+ */
+async function spawnBin(name, args, context) {
+  const cwd = await projectRoot(context);
+  const bin = resolveBin(name, cwd);
+  context.logger.info(
+    `${name} ${args.join(' ')}  (in ${path.relative(context.workspaceRoot, cwd)})`,
+  );
+  return new Promise((resolve) => {
+    const child = spawn(process.execPath, [bin, ...args], { cwd, stdio: 'inherit' });
+    // Ctrl-C reaches the whole process group, but a supervisor, CI or an IDE's task runner signals
+    // `ng` alone, and Metro would outlive it on its port. So a stop is passed on.
+    const stop = (signal) => child.kill(signal);
+    for (const signal of SIGNALS) process.on(signal, stop);
+    const settle = (result) => {
+      for (const signal of SIGNALS) process.off(signal, stop);
+      resolve(result);
+    };
+    child.on('error', (error) => settle({ success: false, error: error.message }));
+    child.on('exit', (code, signal) =>
+      settle(
+        code === 0
+          ? { success: true }
+          : { success: false, error: `${name} exited with ${signal ?? `code ${code}`}` },
+      ),
+    );
+  });
+}
+
+module.exports = { resolveBin, projectRoot, spawnBin };

package/builders/vitest.cjs

@@ -0,0 +1,22 @@
+/**
+ * `@ng-native/schematics:vitest`: the project's tests, once.
+ *
+ * Not `@angular/build:unit-test`, which compiles the tests with the workspace's web build and runs
+ * them against a DOM. An Angular Native test renders onto the fake Fabric from
+ * `@ng-native/testing`, compiled by the same transform Metro uses, and that is set up in the
+ * project's own `vitest.config.mts`.
+ */
+const { createBuilder } = require('@angular-devkit/architect');
+const { spawnBin } = require('./spawn-bin.cjs');
+
+/** @param {{ watch?: boolean, filter?: string }} options */
+function vitestArgs(options) {
+  const args = [options.watch ? 'watch' : 'run'];
+  if (options.filter) args.push(options.filter);
+  return args;
+}
+
+module.exports = createBuilder((options, context) =>
+  spawnBin('vitest', vitestArgs(options), context),
+);
+module.exports.vitestArgs = vitestArgs;

package/builders/vitest.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema",
+  "$id": "NgNativeVitestBuilder",
+  "title": "Vitest",
+  "type": "object",
+  "properties": {
+    "watch": {
+      "type": "boolean",
+      "description": "Keep running and re-run on change.",
+      "default": false
+    },
+    "filter": {
+      "type": "string",
+      "description": "Only test files whose path contains this."
+    }
+  }
+}

package/builders.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "../../node_modules/@angular-devkit/architect/src/builders-schema.json",
+  "builders": {
+    "expo": {
+      "implementation": "./builders/expo.cjs",
+      "schema": "./builders/expo.json",
+      "description": "Runs an Expo CLI command in the project: start, export, run:ios, run:android."
+    },
+    "vitest": {
+      "implementation": "./builders/vitest.cjs",
+      "schema": "./builders/vitest.json",
+      "description": "Runs the project's tests once with Vitest, through @ng-native/testing."
+    }
+  }
+}

package/collection.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "../../node_modules/@angular-devkit/schematics/collection-schema.json",
+  "schematics": {
+    "ng-add": {
+      "description": "Adds an Angular Native app to this workspace, with its dependencies installed.",
+      "factory": "./ng-add/index.cjs#ngAdd",
+      "schema": "./ng-add/schema.json"
+    },
+    "application": {
+      "aliases": ["app"],
+      "description": "An Angular Native app: an Expo project in the workspace, registered in angular.json.",
+      "factory": "./application/index.cjs#application",
+      "schema": "./application/schema.json"
+    },
+    "component": {
+      "aliases": ["c"],
+      "description": "A component for an Angular Native app, with native elements and a test that runs in Node.",
+      "factory": "./component/index.cjs#component",
+      "schema": "./component/schema.json"
+    }
+  }
+}

package/component/index.cjs

@@ -0,0 +1,79 @@
+/**
+ * `ng generate component` in an Angular Native project.
+ *
+ * Angular's own component schematic runs here too, and what it writes does not work on a device:
+ * a `<p>` is not a native element, and its spec needs `TestBed` on a DOM that does not exist. This
+ * writes the native equivalent, a component built from `<view>` and `<text>` with a test that
+ * renders it on the fake Fabric, following the template's conventions: kebab-case files, no
+ * `Component` suffix, an inline template, and a `.test.ts` beside it.
+ */
+const path = require('node:path').posix;
+const { SchematicsException } = require('@angular-devkit/schematics');
+const { strings } = require('@angular-devkit/core');
+
+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} {}
+`;
+}
+
+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();
+});
+`;
+}
+
+/**
+ * The directory the component goes in: the one `ng generate` was run from if that is inside the
+ * project, the project's root otherwise.
+ */
+function directoryFor(workspace, options) {
+  const project = workspace.projects?.[options.project];
+  if (!project) {
+    throw new SchematicsException(`angular.json has no project called "${options.project}".`);
+  }
+  const root = project.sourceRoot ?? project.root;
+  const cwd = path.normalize(options.path ?? '');
+  const inside = cwd === root || cwd.startsWith(root + '/');
+  return { directory: inside ? cwd : root, prefix: project.prefix };
+}
+
+/**
+ * @param {{ name: string, project: string, path?: string, flat?: boolean, skipTests?: boolean }} options
+ */
+function component(options) {
+  return (tree) => {
+    const workspace = JSON.parse(tree.readText('angular.json'));
+    const { directory, prefix } = directoryFor(workspace, options);
+    const file = strings.dasherize(path.basename(options.name));
+    const folder = path.join(directory, path.dirname(options.name), options.flat ? '' : file);
+    const className = strings.classify(file);
+    const selector = prefix ? `${prefix}-${file}` : file;
+    const label = `${file} works`;
+
+    tree.create(path.join(folder, `${file}.ts`), componentSource(className, selector, label));
+    if (!options.skipTests) {
+      tree.create(path.join(folder, `${file}.test.ts`), testSource(className, file, label));
+    }
+  };
+}
+
+module.exports = { component };

package/component/schema.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema",
+  "$id": "NgNativeComponent",
+  "title": "Angular Native component",
+  "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 Angular Native project it belongs to.",
+      "$default": { "$source": "projectName" }
+    },
+    "path": {
+      "type": "string",
+      "format": "path",
+      "description": "The directory to create it in, relative to the workspace root.",
+      "$default": { "$source": "workingDirectory" },
+      "visible": false
+    },
+    "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
+    }
+  },
+  "required": ["name", "project"]
+}

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/metro.config.js

@@ -0,0 +1,7 @@
+const { getDefaultConfig } = require('expo/metro-config');
+const { withAngularNative } = require('@ng-native/metro/config.cjs');
+
+// 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. No options: the framework packages are ordinary dependencies here.
+module.exports = withAngularNative(getDefaultConfig(__dirname));

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/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "extends": "expo/tsconfig.base",
+  "compilerOptions": {
+    "strict": true,
+    "allowImportingTsExtensions": true
+  },
+  "angularCompilerOptions": {
+    "strictTemplates": true,
+    "typeCheckHostBindings": false,
+    "strictDomEventTypes": false
+  }
+}

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/native-app.cjs

@@ -0,0 +1,170 @@
+/**
+ * What an Angular Native app is made of, whichever workspace it is generated into.
+ *
+ * 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. A generated app and a templated app are the same app.
+ *
+ * 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',
+};
+
+/** @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. Its `metro.config.js` and `tsconfig.json`
+ * need nothing changed here: the dependencies are hoisted to the workspace root, where Node's and
+ * Metro's resolution both find them by walking up.
+ */
+const SOURCE_FILES = [
+  'src/app/app.ts',
+  'src/main.ts',
+  'src/app/app.test.ts',
+  'vitest.config.mts',
+  'metro.config.js',
+  'tsconfig.json',
+];
+
+/** @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, not this app's, 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 expo = {
+    name,
+    slug: name,
+    version: '1.0.0',
+    orientation: 'portrait',
+    userInterfaceStyle: 'dark',
+    ios: { supportsTablet: true },
+    android: { predictiveBackGestureEnabled: false },
+    scheme: name.replace(/[^a-z0-9]/gi, '').toLowerCase(),
+  };
+  return JSON.stringify({ expo }, null, 2) + '\n';
+}
+
+/**
+ * The project's own `package.json`, which only Expo reads: `main` is how it finds the entry file.
+ *
+ * It lists every dependency the app has too, at the ranges the workspace root installs, though
+ * nothing installs from it. Expo's autolinking links the native modules named here and no others,
+ * so one left out, such as `react-native-safe-area-context`, is missing from the native build. 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 project's directory, which would put
+ * a second copy of React Native beside the root's.
+ *
+ * @param {string} name
+ * @param {{ dependencies?: Record<string, string>, devDependencies?: Record<string, string> }} root
+ *   the workspace's root `package.json`, once this app's dependencies are in it
+ */
+function projectManifest(name, root) {
+  const installed = { ...root.devDependencies, ...root.dependencies };
+  const pinned = Object.keys(dependencies).map((pkg) => [pkg, installed[pkg] ?? dependencies[pkg]]);
+  return { name, private: true, main: 'src/main.ts', dependencies: Object.fromEntries(pinned) };
+}
+
+/**
+ * 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 `ng update` or `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,
+  projectManifest,
+  conflicts,
+  accepted,
+};

package/ng-add/index.cjs

@@ -0,0 +1,16 @@
+/**
+ * `ng add @ng-native/schematics`: the application schematic, with the name defaulted.
+ *
+ * `ng add` has already installed this package by the time this runs. What it adds is a second
+ * project, the native app, and leaves the workspace's existing projects as they were: an Angular
+ * CLI workspace cannot become a native app, because `@angular/build` has no native target, so the
+ * native app lives beside the web one and Metro builds it.
+ */
+const { application } = require('../application/index.cjs');
+
+/** @param {{ name?: string, directory?: string, skipInstall?: boolean }} options */
+function ngAdd(options) {
+  return application({ ...options, name: options.name ?? 'native', prefix: 'app' });
+}
+
+module.exports = { ngAdd };

package/ng-add/schema.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema",
+  "$id": "NgNativeNgAdd",
+  "title": "Add Angular Native",
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "The native app's project name, in angular.json and as the Expo slug.",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "default": "native"
+    },
+    "directory": {
+      "type": "string",
+      "description": "Where the project goes. Defaults to newProjectRoot/name, usually projects/native."
+    },
+    "skipInstall": {
+      "type": "boolean",
+      "description": "Write the files and package.json without installing.",
+      "default": false
+    }
+  }
+}

package/package.json

@@ -1,12 +1,65 @@
 {
   "name": "@ng-native/schematics",
-  "version": "0.0.1",
-  "description": "Reserved for ng-native. The first release follows.",
+  "version": "0.1.0",
+  "description": "ng add and ng generate for Angular Native: an Expo app in an Angular CLI workspace, with builders that run it.",
+  "keywords": [
+    "angular",
+    "react-native",
+    "angular-native",
+    "ios",
+    "android",
+    "fabric",
+    "native",
+    "schematics",
+    "angular-cli",
+    "ng-add",
+    "expo"
+  ],
+  "type": "module",
+  "schematics": "./collection.json",
+  "builders": "./builders.json",
+  "ng-add": {
+    "save": "devDependencies"
+  },
+  "dependencies": {
+    "@angular-devkit/architect": ">=0.2200.0 <0.2300.0",
+    "@angular-devkit/core": "^22.0.0",
+    "@angular-devkit/schematics": "^22.0.0",
+    "semver": "^7.7.0"
+  },
+  "devDependencies": {
+    "@schematics/angular": "22.1.9",
+    "@types/semver": "^7.7.0"
+  },
+  "nx": {
+    "tags": [
+      "scope:schematics",
+      "layer:build"
+    ]
+  },
   "license": "MIT",
+  "homepage": "https://ng-native.com/packages/schematics",
+  "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/schematics"
   },
-  "homepage": "https://ng-native.com/packages/schematics"
+  "files": [
+    "*.cjs",
+    "collection.json",
+    "builders.json",
+    "*/*.cjs",
+    "*/*.json",
+    "files"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --test \"*.test.ts\" \"{application,component,builders}/*.test.ts\""
+  }
 }