Skip to content
NativeScript Unified

Getting started

Web vs native

Web and native diverge often, so they are two apps at the top of the workspace. Each has its own pages and its own core. Shared HTML and features sit underneath both. The approach on both is HTML first.

Why they diverge

Web and native run on different form factors, and they handle flows and interactions in different ways. Neither platform has one right way to build a UI, and a layout or flow that suits one is often not the best choice on the other.

Keeping them as separate apps is a strength. Each app can design its pages and flows for its own platform, instead of settling for one UI that is only passable on both. The parts that are the same everywhere, such as content, HTML features and design tokens, are written once in packages/shared. The parts that differ live in the app that owns them. Shared code then needs no platform checks, which is why packages/shared has no platform imports.

The core of each app

AreaWeb (apps/web)Native (apps/native)
Entrysrc/main.ts, src/app/app.config.tssrc/main.ts
RouterprovideFileRouter from @analogjs/routerprovideFileRouter from @nativescript-unified/analog-native
Change detectionprovideZonelessChangeDetection()provideZonelessChangeDetection()
Root componentapp.ts<page-router-outlet /> in app.component.ts
View layerBrowser DOMMasonKit, installed by installMasonKit() before bootstrap
BuildVite with @analogjs/platform, prerenderedVite with @nativescript/vite and the nativescriptAnalog() plugin
Dark modedark class on <html>ns-dark class on the root view
StylingTailwind and Spartan helmTailwind through @nativescript/tailwind and Spartan helm, with the same tokens.css
CSS pxA CSS pixelA CSS pixel on MasonKit elements, a device pixel on core NativeScript views
NativeScript view tagsRendered by web-polyfillsReal native views

Pages

Both use src/app/pages and the same file conventions, but a page is written for its platform.

A web page imports RouterLink and Spartan helm components. A native page imports ActionBarComponent from @nativescript/angular, sets NO_ERRORS_SCHEMA, and wraps its content in <scroll>:

@Component({
  selector: 'shared-page',
  imports: [ActionBarComponent, HomeFeature],
  schemas: [NO_ERRORS_SCHEMA],
  template: `
    <ActionBar title="Shared HTML" />
    <scroll>
      <app-home-feature />
    </scroll>
  `,
})
export default class SharedPage {}

That is apps/native/src/app/pages/shared.page.ts. The HomeFeature it renders lives in packages/shared, and the web home page reads the same FEATURES data.

What is shared

packages/shared holds HTML-first components and content. They use plain elements and Tailwind classes, with no platform imports. Here is the shape of a shared feature, running live:

NativeScript, HTML first

One set of HTML pages. Web and native stay separate at the top.

HTML first

Plain HTML on both platforms.

Where does new code go

  1. If it is plain HTML, token classes and helm components, with no platform imports, put it in packages/shared. See Writing shared HTML features.
  2. If it needs a router service or a platform API, put it in the app that uses it.
  3. If a NativeScript view tag must render in a browser, it belongs in packages/web-polyfills. Native never imports that package, because on a device those tags are real views. See NativeScript views.

Spartan on native

packages/ui/native holds the glue helm needs on NativeScript, and provideSpartanNativeScript() installs it. The native app renders these docs pages, and each html live demo is compiled on the device against the same helm components the web uses. Overlays open in native windows instead of a CDK overlay:

  • A dialog or alert dialog opens as the platform's dialog. See Native elements. Content the platform dialog cannot hold opens in a full-screen, transparent modal window, which uses the overFullScreen presentation on iOS.
  • A sheet or drawer on the bottom edge opens in a native bottom sheet from @nativescript-community/ui-bottomsheet, sized to its content.
  • A sheet or drawer on the left, right or top edge docks to that edge in the app's Drawer from @nativescript-community/ui-drawer.
  • A popover opens in an anchored window from @nativescript-community/ui-popover. Select, combobox, autocomplete and date picker use the same window.
  • A dropdown menu opens the platform menu from @nativescript-community/ui-menu. That is a Material 3 popup menu on Android and a UIMenu on iOS.

Native status lists what each component does in the native app.

Known native limitations

These apply across components.

  • Helm rules beat utilities on helm hosts. helm's .style-vega .spartan-* rules have a specificity of 0,2,0 and sit outside any layer, so they override a Tailwind utility you put on the same element. For example, h-12 or rounded-full on hlmBtn, or gap-* and p-* on hlmCard, have no effect. This happens on the web too.
  • Opacity-modified token colours. Classes such as bg-input/80, bg-destructive/10 and dark:bg-input/30 keep the plain light token colour on native, in every theme.
  • Text layout in MasonKit. A button does not always center its text on its first layout. An inline-flex box lays its children out as an inline text run, so use flex for a box that holds other boxes, as packages/ui/native/native-overrides.css does for the progress bar and the calendar. Text ignores white-space: pre. To keep line breaks and indents, draw each line as its own block, as <analog-code> does.
  • Block-backed tags. Spartan styles button, a, li, kbd, label and the headings as flex boxes, so registerSpartanNativeElements() in packages/ui/native/spartan-native.ts backs them with block elements. A list item therefore draws no marker. The Markdown renderer draws its own.
  • Browser APIs in brain components. MasonKit elements have no getBoundingClientRect() or pointer events, there is no document.defaultView, and the NativeScript document has no createElement() for a CDK overlay. Where brain needs these, it takes a no-DOM path: the select trigger measures itself on layoutChanged, and the tooltip and hover card open through the overlay host. The switch, checkbox, slider and toaster are native shims (packages/ui/native/shims).
  • Media queries. NativeScript drops media queries. apps/native/src/app.css overrides the motion-safe variant so that the spinner and skeleton animations run.
  • Hover. A touch screen has no hover, so the tooltip and the hover card open on a tap instead.