Skip to content
NativeScript Unified

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.0 or >=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 install

Run 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 preview

nx 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:android

This 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 typecheck

Your 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

One template

The same markup renders in a browser and as native views.

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.