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
| Area | Web (apps/web) | Native (apps/native) |
|---|---|---|
| Entry | src/main.ts, src/app/app.config.ts | src/main.ts |
| Router | provideFileRouter from @analogjs/router | provideFileRouter from @nativescript-unified/analog-native |
| Change detection | provideZonelessChangeDetection() | provideZonelessChangeDetection() |
| Root component | app.ts | <page-router-outlet /> in app.component.ts |
| View layer | Browser DOM | MasonKit, installed by installMasonKit() before bootstrap |
| Build | Vite with @analogjs/platform, prerendered | Vite with @nativescript/vite and the nativescriptAnalog() plugin |
| Dark mode | dark class on <html> | ns-dark class on the root view |
| Styling | Tailwind and Spartan helm | Tailwind through @nativescript/tailwind and Spartan helm, with the same tokens.css |
CSS px | A CSS pixel | A CSS pixel on MasonKit elements, a device pixel on core NativeScript views |
| NativeScript view tags | Rendered by web-polyfills | Real 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.
<div class="flex flex-col gap-4 p-4 rounded-lg border bg-background text-foreground">
<h1 class="text-2xl font-bold">NativeScript, HTML first</h1>
<p class="text-muted-foreground">One set of HTML pages. Web and native stay separate at the top.</p>
<div class="flex flex-col gap-1 p-3 rounded-lg bg-card text-card-foreground">
<h2 class="text-base font-semibold">HTML first</h2>
<p class="text-sm text-muted-foreground">Plain HTML on both platforms.</p>
</div>
</div>Where does new code go
- If it is plain HTML, token classes and helm components, with no platform imports, put it in
packages/shared. See Writing shared HTML features. - If it needs a router service or a platform API, put it in the app that uses it.
- 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
overFullScreenpresentation 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
Drawerfrom@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 aUIMenuon 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-12orrounded-fullonhlmBtn, orgap-*andp-*onhlmCard, have no effect. This happens on the web too. - Opacity-modified token colours. Classes such as
bg-input/80,bg-destructive/10anddark:bg-input/30keep 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-flexbox lays its children out as an inline text run, so useflexfor a box that holds other boxes, aspackages/ui/native/native-overrides.cssdoes for the progress bar and the calendar. Text ignoreswhite-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,labeland the headings as flex boxes, soregisterSpartanNativeElements()inpackages/ui/native/spartan-native.tsbacks 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 nodocument.defaultView, and the NativeScript document has nocreateElement()for a CDK overlay. Where brain needs these, it takes a no-DOM path: the select trigger measures itself onlayoutChanged, 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.cssoverrides themotion-safevariant 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.