native applications

introduction

dframework allows you to package your web application as native apps for ios, android, and desktop platforms. the native layer is a lightweight webview wrapper that provides device api access through a javascript bridge while keeping your application logic entirely web based.

unlike hybrid frameworks that require separate codebases or complex build configurations, dframework maintains a single source of truth. your routes, controllers, models, and views work identically across web and native environments.

supported platforms

the framework provides native runtimes for three platforms:

ios - native swift application using wkwebview
android - native kotlin application using android webview
desktop - cross platform application using tauri (rust + webview)

each runtime includes automatic network adaptation, javascript polyfills, and a unified bridge api. no platform specific code is required in your application unless you need custom native plugins.

configuration

basic setup

native configuration lives in config/native.js at your project root. the framework merges your configuration with sensible defaults.

1export default {
2  name: 'myapp',
3  identifier: 'com.example.myapp',
4  version: '1.0.0',
5  build: 1,
6};

if you omit the name field, the framework uses Config('app.name') as the fallback.

application identity

the identifier field must follow reverse domain notation and uniquely identifies your application on each platform. this value cannot be changed after distribution without creating a new app listing.

1export default {
2  identifier: 'com.example.myapp',
3  version: '2.1.0',
4  build: 42,
5};

the version string is user facing. the build number must increment with every release and is used by app stores to differentiate versions.

url configuration

by default, native apps load content from Config('app.url') plus Config('app.port'). you can override this behavior by setting the index field.

1export default {
2  index: 'https://myapp.com',
3};

when index is null, the framework constructs the url from your primary application config. this ensures that changing your api url automatically updates native builds without manual synchronization.

during simulation, the framework injects the development server url via environment variable, allowing you to test against localhost regardless of your production configuration.

static fallback

you can bundle a static html site inside your native application as a fallback when the remote url is unreachable. this enables offline functionality or provides an error page with retry logic.

1export default {
2  index: 'https://api.myapp.com',
3  fallback: 'native/static/index.html',
4};

the static site has full access to the bundled dframework css and javascript runtime. place your static files in the native/static/ directory. the framework copies this directory into the native bundle during build.

a minimal fallback page might display a network error with a reload button:

1<!DOCTYPE html>
2<html>
3<head>
4  <meta charset="utf-8">
5  <meta name="viewport" content="width=device-width, initial-scale=1">
6  <link rel="stylesheet" href="/css/dstrn.css">
7  <title>offline</title>
8</head>
9<body class="bg-container flex-center" style="height: 100vh;">
10  <div class="flex-column g-2 text-center p-2">
11    <h1>no connection</h1>
12    <p class="text-content-secondary">
13      please check your internet connection and try again
14    </p>
15    <button onclick="location.reload()">retry</button>
16  </div>
17  <script src="/js/dstrn.js"></script>
18</body>
19</html>

the native runtime automatically attempts to load the fallback when the primary url fails. you can also build fully offline applications by setting index to null and providing a complete static implementation.

development workflow

simulation

use the simulate command to test your application in a native environment during development. the framework starts your server automatically if it is not already running.

1dstrn simulate --ios
2dstrn simulate --android
3dstrn simulate --desktop

the simulator connects to your local development server. changes to your application code are immediately visible after refresh, just as they are in the browser.

press r to refresh the native app. press q to quit.

building

the build command compiles a production ready binary for distribution. builds are written to native/builds/ organized by platform.

1dstrn build --target ios
2dstrn build --target android
3dstrn build --target desktop

production builds use the configured index url. if you have not set an explicit value, the framework uses your production api endpoint from config/app.js.

builds require platform specific toolchains. see the build and distribution documentation for environment setup instructions.

project structure

native assets and configuration live in the native directory at your project root:

1native/
2├── assets/
3│   └── icon.png       # application icon
4├── static/            # optional static fallback site
5│   ├── index.html
6│   ├── css/
7│   └── js/
8└── builds/            # compiled binaries (gitignored)
9    ├── ios/
10    ├── android/
11    └── desktop/

the framework generates the builds directory during compilation. you should exclude it from version control.

the icon.png file must be at least 1024x1024 pixels. the framework automatically generates all required sizes and formats for each platform during the build process.

On this page