Getting Started

VastX Native brings Nuxt's developer experience — file-based pages, auto-imported composables/components/style helpers, a single module system — to real native apps, built on NativeScript's native runtime rather than reinventing one from scratch.

Vue components render as actual native views (UIView / android.view.View), the same way React Native components render as real native views instead of HTML.

Status: early / pre-alpha. Both platforms are now verified on real hardware. The create command has taken a project from an empty folder to a rendering app on physical Android hardware, repeatedly. iOS verification started more recently, on a real physical device (no simulator): install, launch, full-screen rendering, safe-area layout, and tap/gesture responsiveness are all confirmed working. Not every code path has been exercised on-device yet — see Architecture & Status for the precise boundary of what's actually been run.

Why not Capacitor / a WebView?

Capacitor-style tools ship your Nuxt app as compiled web code running inside a native WebView. That's a fine, fast path to "app-store distributable," but it isn't native UI — you still get DOM rendering, web-style scrolling, and a WebView's performance ceiling.

VastX Native takes the harder path on purpose: Vue's renderer targets real native views directly, so the result looks, scrolls, and performs like a native app because it is one — the same tradeoff React Native and Flutter made, applied to the Nuxt/Vue ecosystem.

Quickstart

One command, empty directory to a project with dependencies installed and native platforms wired up:

npx github:vastx-tech/vastx-native create my-app --app-id com.example.myapp
cd my-app
npx vastx-native dev android   # or: ios

create scaffolds nuxt.config.ts and a starter app/pages/index.vue with a reactive counter and increment/decrement buttons, runs npm install, writes nativescript.config.ts, and runs ns platform add for each platform (--platforms ios,android, defaults to both) — including replacing the splash screen NativeScript's own template generates with VastX Native's own branding.

Adding it to an existing Nuxt project

npm install github:vastx-tech/vastx-native#v3.0.0 nativescript-vue @nativescript/core

export default defineNuxtConfig({
  modules: ['vastx-native'],
  native: {
    appId: 'com.example.myapp',
    appName: 'My App'
  }
})

npx vastx-native init          # scaffolds nativescript.config.ts + native platforms
npx vastx-native dev ios       # build, deploy, and LiveSync to a simulator/device
npx vastx-native dev android

Write pages under app/pages/ using NativeScript-Vue's native elements — <Frame>, <StackLayout>, <Label>, <Button>, <TabStrip> — instead of HTML. <NPage>, <NActionBar>, and <NTabs> wrap the common ones with sensible defaults.

Coming from nuxt-native?

VastX Native was called nuxt-native up to v2.2.1. Starting with v3.0.0 it is published as vastx-native. To move an existing app over:

1. Swap the package: npm uninstall nuxt-native && npm install github:vastx-tech/vastx-native#v3.0.0.
2. In your app, find and replace nuxt-native with vastx-native in every file except node_modules/ and platforms/. Besides nuxt.config.ts, the old name is in nativescript.config.ts, package.json, tsconfig.json, webpack.config.cjs, and the nuxt-native: comments under App_Resources/ that mark the blocks the CLI manages.
3. Do the same for NuxtNative → VastXNative and NUXT_NATIVE_ → VASTX_NATIVE_ if you import the options type or set the keystore environment variables.
4. Run npx vastx-native clean, then npx vastx-native init, and delete the old .nuxt-native/ folder.

Your native: { ... } options don't change. The changelog lists every rename.

How it fits together

• app/pages/ — you author pages the normal Nuxt way (file-based routing, dynamic segments like [id].vue).
• useNativeRouter() replaces vue-router at runtime — there's no DOM history to push state onto, so navigation pushes/pops NativeScript's native Frame backstack instead.
• Composables (useDevice, useSafeArea, useGeolocation, useCamera, ...) wrap native device APIs, auto-imported like any Nuxt composable.
• Components (<NPage>, <NActionBar>, <NTabs>) are thin, safe-area-aware wrappers around NativeScript-Vue's native primitives.
• A UI kit — see UI Kit.
• Tailwind, scoped to what NativeScript can actually render — see Styling & Tailwind.
• Pinia, Supabase, MCP, WebSockets — see State & Data.
• The vastx-native CLI generates the on-device bootstrap and hands off to NativeScript's own toolchain — see CLI Reference.