AbsoluteJS

Native Quickstart

Take an AbsoluteJS app you already have and run it as an iOS and Android app: add a config block, create the native projects, and start bun dev.

#Before you start

You need an AbsoluteJS app whose pages are served by React, Svelte, Vue, Angular, HTML or HTMX page handlers. Then, for each platform you want to run:

PlatformYour machineWhat it needs
AndroidLinux, macOS, Windows or WSLAndroid SDK, emulator, API 36 system image and Java 21. bun dev offers to install them, or run absolute mobile doctor android --fix.
iOSmacOS, or any machine with a paired MacXcode with an iOS Simulator runtime. From Linux or Windows, pair a Mac once and AbsoluteJS builds and runs there over SSH.
BASH
bunx absolute mobile doctor            # what is installed, what is missing
bunx absolute mobile doctor android --fix   # install the Android SDK, emulator and Java 21

#1. Add the config

appId is the identifier the stores know your app by, in reverse-domain form. productionOrigin is the HTTPS address of your deployed server: the app loads each page’s data from there.

TS
// absolute.config.ts
import { defineConfig } from '@absolutejs/absolute';

export default defineConfig({
  reactDirectory: 'src/frontend',
  mobile: {
    appId: 'com.example.shop',
    appName: 'Shop',
    server: { productionOrigin: 'https://shop.example.com' }
  }
});

Both platforms are built unless you set platforms, and the app opens on / unless you set entry. Every other field is in the config reference.

#2. Export your server

The build loads your server to find its pages, so the Elysia app has to be exported as server, app or the default export. Your handlers stay exactly as they are: the same route returns HTML to a browser and JSON props to the app.

TS
// src/backend/server.ts
import { prepare, asset, networking } from '@absolutejs/absolute';
import { handleReactPageRequest } from '@absolutejs/absolute/react';
import { Elysia } from 'elysia';
import { Home } from '../frontend/pages/Home';

const { absolutejs, manifest } = await prepare();

// Export the app as server, app or default so the build can find your pages
export const app = new Elysia()
  .use(absolutejs)
  .get('/', () =>
    handleReactPageRequest({
      Page: Home,
      index: asset(manifest, 'HomeIndex'),
      props: { greeting: 'Welcome back' }
    })
  )
  .use(networking);

#3. Create the native projects

BASH
bunx absolute mobile init
package.jsonThe Capacitor packages AbsoluteJS has tested, pinned to exact versions. You are asked before anything is installed; --yes approves it up front.
capacitor.config.tsThe Capacitor config, generated from your mobile block. Edit absolute.config.ts, not this file.
mobile/android and mobile/iosThe Android Studio and Xcode projects. They are yours: commit them and add native code if you need to. Change the folder with nativeProject.directory.
Applied from your configYour app’s icons and splash screens, deep links, the permissions for the device features you import, and the settings for sign-in, offline data and updates.

After you change the mobile block or start using a new device feature, run bunx absolute mobile sync to apply it to the native projects.

#4. Run it

BASH
bun dev
1
Check the toolchain
If the Android toolchain is missing, bun dev offers to install it. If the native project is missing, it offers to create it.
2
Start the emulator and simulator
An Android emulator boots, and on macOS (or a paired Mac) an iOS Simulator starts beside it.
3
Install the app
The app is installed and pointed at your dev server, so every page, style and edit arrives over the same hot reload as the browser.
4
Develop
Native logs stream into your terminal as [android] and [ios]. Press d to see each device’s status, or type relaunch to restart the app.

To work on the web only, run bunx absolute dev --no-mobile or set ABSOLUTE_NO_MOBILE=1.

#5. Run it on your phone

Android. Turn on USB debugging, connect the phone, and pass its serial. Your dev server is reachable over your local network for the session.

BASH
adb devices                                   # find your phone's serial
bunx absolute dev --android-device R58M42ABCDE

iPhone. Pair it in Xcode once, turn on Developer Mode, and choose a signing team for the project. Then pass its identifier or name.

BASH
xcrun devicectl list devices                  # find your iPhone's identifier
bunx absolute dev --ios-device "Ada's iPhone"

iOS from Linux or Windows. Pair a Mac once. From then on bun dev sends your project to it, builds there, and streams hot reload back over SSH.

BASH
bunx absolute mobile pair mac studio builder@studio.local
bun dev                                       # iOS now runs on the paired Mac
Using HTTPS in dev
With dev.https on, AbsoluteJS trusts its development certificate inside debug builds only, so phones reach your dev server over HTTPS without changing any system settings. Development covers each platform.

#Preview in the browser

For quick layout work there is no need to wait for an emulator. The dev server prints a Mobile link that runs your real pages in an iPhone or Android frame, with controls for the platform, network, keyboard, Back and deep links.

bun dev
$ bun dev
  ➜  Local:   http://localhost:3000/
  ➜  Mobile:  http://localhost:3000/__absolute/mobile-preview

#Next steps