Getting started
Installation
nativescript-unified is an Nx workspace. Run the commands below from its root.
Requirements
- Node and npm. Angular 22.2 supports Node
^22.22.3,^24.15.0or>=26. An older Node still installs, with engine warnings. - For native: the NativeScript CLI (
ns), plus the Android SDK for Android, or a Mac with Xcode for iOS.
Install
npm installRun the web docs
npx nx serve web # dev server, same as: npm run web
npx nx build web # prerendered static site
npx nx run web:preview # serves the build on http://localhost:4300
npm run audit:web # headless Edge checks against the previewnx build web prerenders / and every /docs/:slug, and writes the result to dist/apps/web/analog/public. web:preview depends on the build and serves that folder.
Each push to main deploys the site to GitHub Pages through .github/workflows/pages.yml. GitHub Pages serves a repository's site from a subpath such as /nativescript-unified/, so the workflow sets BASE_PATH and the build prefixes links and assets with it. To make the same build locally, run BASE_PATH=nativescript-unified npx nx build web.
Run native
npx nx run native:androidThis runs ns run android --no-hmr with the arm64-v8a and x86_64 ABIs. It builds the app and runs it on an Android emulator or device. The other native targets are ios, debug-android, build-android and clean.
If you call ns yourself from PowerShell, quote the Gradle argument: ns build android '--gradleArgs=-Pabis=arm64-v8a,x86_64'. Without the quotes, PowerShell splits the value at the comma, and the APK ships without its native libraries. On Windows, a before-prepare hook (apps/native/tools/gradle-env.mjs) clears NoDefaultCurrentDirectoryInExePath so the CLI can run gradlew.bat.
For iOS, run npx nx run native:ios on a Mac with Xcode. It runs ns run ios --no-hmr.
Check your work
npx nx test web-polyfills
npx nx test analog-native
npx nx run-many -t typecheckYour first page
Pages are files. Create apps/web/src/app/pages/hello.page.ts while nx serve web is running, and the dev server serves it at /hello:
import { Component } from '@angular/core';
import { HlmButton } from '@spartan-ng/helm/button';
import { HlmCardImports } from '@spartan-ng/helm/card';
@Component({
selector: 'web-hello-page',
imports: [HlmButton, HlmCardImports],
template: `<!-- the HTML below -->`,
})
export default class HelloPage {}The template is plain HTML with Tailwind classes and helm attributes. This one is running live:
Hello, HTML first
The same markup renders in a browser and as native views.
<div class="flex flex-col gap-4 p-4">
<h1 class="text-2xl font-bold">Hello, HTML first</h1>
<section hlmCard class="max-w-sm">
<div hlmCardHeader>
<div hlmCardTitle>One template</div>
<p hlmCardDescription>The same markup renders in a browser and as native views.</p>
</div>
<div hlmCardFooter class="gap-2">
<button hlmBtn>Get started</button>
<button hlmBtn variant="outline">Learn more</button>
</div>
</section>
</div>The native app has its own pages/ folder with the same conventions. See File-based routing. To write a template once and render it in both apps, put it in packages/shared. See Writing shared HTML features.
Next steps
Read Project structure and Web vs native.