Getting Started with Hyperview

01 What is Hyperview?

Hyperview is a React Native client for developing mobile apps using hypermedia-driven development. Think of Hyperview like a web browser of sorts. A web browser takes HTML and shows you a document on your screen. Hyperview takes HXML, a new hypermedia format created by the Hypermedia developers, and shows an interface on a smartphone.

A Hyperview app can be installed and saved as an icon on a smartphone screen. It looks, and importantly, it acts like a native application.

The main difference between Hyperview and a typical mobile app is that native mobile apps usually follow the same React "fat client" style of application development. This leads to a complicated development cycle requiring a lot of developers to manage. The tradeoff is that the apps feel modern, as a user expects.

Hyperview, on the other hand, uses the same development model as traditional web development--a "thin client" model. As a result, development is significantly simpler than the typical approach. It is designed to allow developers to create "native feeling" apps. In other words, with Hyperview, you can create modern, native-feeling mobile apps without the complications of typical mobile app development.

Using Hyperview, you can code a backend on your server--in any language you like--and serve HXML to a Hyperview client installed on a user's smartphone.

02 Getting started with Hyperview -- Viewing Demo App

02.01 Follow Offical Guide

First, follow the Getting Started guide on the Hyperview website.. If you're new to mobile app development, you'll need to install an iOS and/or Android simulator. That means you need to install Xcode, making sure to also install the iOS development tools when you first start Xcode. For Android, install Android Studio.

02.02 TypeError: Network request failed

When I followed the guide, I was unable to actually display the demo app included. When I tried to view the demo app, I got the error: TypeError: Network request failed. I needed to do some additional configuration in order to view the demo app.

02.03 Modify app.config.ts to view the demo app

There are two important variables to configure in the Hyperview client, located in the demo folder. The first is baseUrl, located in demo/app.config.ts

1
2
3
4
  extra: {
    baseUrl: process.env.BASE_URL || 'http://0.0.0.0:8085',
    googleMapsApiKey: process.env.GOOGLE_MAPS_API_KEY || '', // Leaving the key empty will enable dev-only experience
  },

If you want to look at the actually see the demo app included with the Hyperview repository, then you need to set the default for baseUrl to the IP address given to you when you ran yarn start in the Hyperview Getting Started guide. For example, for me, when I run yarn start in the demo folder, I get the following output:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
yarn run v1.22.22
$ expo start
Starting project at /Users/micah/Work/Software_Development/demos/hyperview/demo
Starting Metro Bundler
▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
█ ▄▄▄▄▄ █   █▄ █▄██ ▄▄▄▄▄ █
█ █   █ █ ▀▄ █▀█ ██ █   █ █
█ █▄▄▄█ █▀██▀▀█▀▄██ █▄▄▄█ █
█▄▄▄▄▄▄▄█▄▀▄█ █▄█▄█▄▄▄▄▄▄▄█
█▄▄▀█▄ ▄█▀▀▀▄▀█▄ ███ ▀▄▄ ▄█
█▀▄▄ █▄▄▄▀█▀ ▄██  ▀ █▄  ▀██
█▀▄ █▄█▄▄█▀▄█▄▀▄▀▄▀▄▀▀▄ ▀██
████ ▀ ▄  ▄██▀██▄▄▄█▄▀ ▀███
█▄▄▄█▄▄▄█▀▄ ▄▀█▄▄ ▄▄▄ ▀ ▄▄█
█ ▄▄▄▄▄ █▀██ ▄██▀ █▄█ ▀▀█▀█
█ █   █ █▄███▄▀▄█▄▄ ▄▄▀   █
█ █▄▄▄█ █▀▀▀█▀█▀▄██▄▀█▀▀ ██
█▄▄▄▄▄▄▄█▄▄▄▄▄▄▄████▄▄▄▄▄▄█

› Metro waiting on exp://192.168.0.44:8081
› Scan the QR code above with Expo Go (Android) or the Camera app (iOS)

› Using Expo Go
› Press s │ switch to development build

› Press a │ open Android
› Press i │ open iOS simulator
› Press w │ open web

› Press j │ open debugger
› Press r │ reload app
› Press m │ toggle menu
› Press o │ open project code in your editor

› Press ? │ show all commands

Logs for your project will appear below. Press Ctrl+C to exit.
Android Bundling complete 5941ms
› Stopped server
✨  Done in 20.59s.

Notice the line Metro waiting on exp://192.168.0.44:8081. 192.168.0.44:8081 is the important bit. In the app.config.ts file, set the default for baseUrl to use that address instead:

1
2
3
4
  extra: {
    baseUrl: process.env.BASE_URL || 'http://192.168.0.44:8081',
    googleMapsApiKey: process.env.GOOGLE_MAPS_API_KEY || '', // Leaving the key empty will enable dev-only experience
  },

Although the Metro bundler waits on exp://192.168.0.44:8081, we need to begin the baseUrl with http://, not exp://. With that one change, I am able to view the demo app.

You can also run BASE_URL="http://192.168.0.44:8081" yarn start to get the same result.

03 Getting Started with Hyperview -- Using Your Own backend

So now that you know how to view the demo, you probably want to start playing around with your own code.

03.01 Make Your Endpoint

First, you need to make the endpoint for your HXML code. For example, let's say that you have a Laravel project. You need to make a route and a view:

1
2
3
4
// myproject/routes/web.php
Route::get('/hv', function () {
    return view('hv_home');
});

In your view, you can place the following HXML code:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
<doc xmlns="https://hyperview.org/hyperview">
    <screen>
        <body>
            <header>
                <text>
                    Hello world header
                </text>
            </header>
            <view>
                <text>Hello World</text>
            </view>
        </body>
    </screen>
</doc>

Now the question is: how do view this code on your Hyperview client?

03.02 Modify app.config.ts

First, you need to set the baseUrl in app.config.ts

1
2
3
4
  extra: {
    baseUrl: process.env.BASE_URL || 'http://127.0.0.1:8081',
    googleMapsApiKey: process.env.GOOGLE_MAPS_API_KEY || '', // Leaving the key empty will enable dev-only experience
  },

When you start a Laravel server, by default the server is open to http://127.0.0.1:8000. In my experience, I needed to set it to open on port 8081--the same port the Metro bundler uses.

php artisan serve --port 8081

03.03 Modify App.tsx

If you make the modification to the baseUrl and restart the Hyperview server with yarn start, you'll still get the TypeError: Network request failed error. You need to configure another variable located in demo/App.tsx:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
<Hyperview
    behaviors={Behaviors}
    components={Components}
    entrypointUrl={`${Constants.expoConfig?.extra?.baseUrl}/hyperview/public/index.xml`}
    fetch={fetchWrapper}
    formatDate={formatDate}
    logger={new Logger(Logger.Level.log)}
    navigationComponents={{
      BottomTabBar,
    }}
/>

The Hyperview client is a React Native component. In the book hypermedia.systems, in addition to teaching how to use HTMX for modern hypermedia-driven development, it also teaches how to use Hyperview. In the book, it says to modify demo/src/constants.js as follows:

1
2
//export const ENTRY_POINT_URL = 'http://0.0.0.0:8085/index.xml';
export const ENTRY_POINT_URL = 'http://0.0.0.0:5000/';

http://0.0.0.0:5000/ corresponds to the Flask backend endpoint for the Contacts app built in the earlier part of the book. As of January 2025, the demo/src/constants.js file and the ENTRY_POINT_URL variable no longer exists. Instead, it's been replaced by the entrypointUrl attribute in the <Hyperview> component in demo/App.tsx.

Thus, if we want to point Hyperview to our Hyperview view on our Laravel backend, we need to modify the entrypointUrl:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
<Hyperview
    behaviors={Behaviors}
    components={Components}
    entrypointUrl={`${Constants.expoConfig?.extra?.baseUrl}/hv`}
    fetch={fetchWrapper}
    formatDate={formatDate}
    logger={new Logger(Logger.Level.log)}
    navigationComponents={{
      BottomTabBar,
    }}
/>

03.04 Access Endpoint

With the modifications to app.config.ts and App.tsx, if we start the Laravel dev server with php artisan serve --port 8081 and start the Hyperview app again with yarn start, we will be able to access the http://127.0.0.1:8081/hv endpoint and display our hv_home view. Congratulations, you are now a hypermedia-driven mobile application developer, or a mobilemaster!

Profile Photo

Author

Added

Jan. 13, 2025

Technologies
hyperview hyperview
laravel laravel