|
| 1 | +--- |
| 2 | +title: "Single Page Apps" |
| 3 | +linkTitle: "Single Page Apps" |
| 4 | +weight: 45 |
| 5 | +no_list: true |
| 6 | +type: docs |
| 7 | +icon: true |
| 8 | +description: "Create and deploy single page applications hosted by Viam." |
| 9 | +--- |
| 10 | + |
| 11 | +Viam Single Page Apps allow you to upload a single page application and access it via a dedicated URL (`appname.publicnamespace.viamapps.com`), with hosting, authentication, and boilerplate logic handled for you. This feature enables you to create custom web interfaces for your machines without having to manage the infrastructure for hosting and authentication. |
| 12 | + |
| 13 | +## Overview |
| 14 | + |
| 15 | +With Viam Single Page Apps, you can: |
| 16 | + |
| 17 | +- Host shared logic for users to choose an organization, location, and single machine |
| 18 | +- Render your application once a user has selected a machine |
| 19 | +- Store robot owner API key and secret in browser storage |
| 20 | +- Proxy requests through the viamapps.com domain to maintain same-origin across pages |
| 21 | +- Authenticate users via FusionAuth |
| 22 | +- Create and upload apps using the modules framework |
| 23 | + |
| 24 | +## Requirements |
| 25 | + |
| 26 | +To use Viam Single Page Apps, you need: |
| 27 | + |
| 28 | +- A module with a public visibility setting |
| 29 | +- A properly configured `meta.json` file with application information |
| 30 | +- A built single page application with an HTML entry point |
| 31 | + |
| 32 | +## Creating a Single Page App |
| 33 | + |
| 34 | +### 1. Build your application |
| 35 | + |
| 36 | +Build your single page application using your preferred framework (React, Vue, Angular, etc.). Your application should be built and ready for deployment, with all assets compiled into a distributable format. |
| 37 | + |
| 38 | +### 2. Configure your module's meta.json |
| 39 | + |
| 40 | +Add the `applications` field to your module's `meta.json` file to define your single page app: |
| 41 | + |
| 42 | +```json |
| 43 | +{ |
| 44 | + "module_id": "your-namespace:your-module", |
| 45 | + "visibility": "public", |
| 46 | + "url": "https://github.com/your-org/your-repo", |
| 47 | + "description": "Your module description", |
| 48 | + "models": [ |
| 49 | + { |
| 50 | + "api": "rdk:component:base", |
| 51 | + "model": "your-namespace:your-module:your-model" |
| 52 | + } |
| 53 | + ], |
| 54 | + "entrypoint": "run.sh", |
| 55 | + "applications": [ |
| 56 | + { |
| 57 | + "name": "your-app-name", |
| 58 | + "type": "web", |
| 59 | + "entrypoint": "dist/index.html" |
| 60 | + } |
| 61 | + ] |
| 62 | +} |
| 63 | +``` |
| 64 | + |
| 65 | +The `applications` field is an array of application objects with the following properties: |
| 66 | + |
| 67 | +| Property | Type | Description | |
| 68 | +| --- | --- | --- | |
| 69 | +| `name` | string | The name of your application, which will be used in the URL (`name.publicnamespace.viamapps.com`) | |
| 70 | +| `type` | string | The type of application (currently only `"web"` is supported) | |
| 71 | +| `entrypoint` | string | The path to the HTML entry point for your application | |
| 72 | + |
| 73 | +#### Entrypoint examples |
| 74 | + |
| 75 | +The `entrypoint` field specifies the path to your application's entry point. Here are some examples: |
| 76 | + |
| 77 | +- `"dist/index.html"` - Static content rooted at the `dist` directory |
| 78 | +- `"dist/foo.html"` - Static content rooted at the `dist` directory, with `foo.html` as the entry point |
| 79 | +- `"dist/"` - Static content rooted at the `dist` directory (assumes `dist/index.html` exists) |
| 80 | +- `"dist/bar/foo.html"` - Static content rooted at `dist/bar` with `foo.html` as the entry point |
| 81 | + |
| 82 | +### 3. Upload your module |
| 83 | + |
| 84 | +Package your module with your application included and upload it to the Viam Registry: |
| 85 | + |
| 86 | +```bash |
| 87 | +viam module build local |
| 88 | +viam module upload module.tar.gz |
| 89 | +``` |
| 90 | + |
| 91 | +## Accessing your Single Page App |
| 92 | + |
| 93 | +Once your module with the application configuration is uploaded and approved, your application will be available at: |
| 94 | + |
| 95 | +``` |
| 96 | +https://your-app-name.your-public-namespace.viamapps.com |
| 97 | +``` |
| 98 | + |
| 99 | +Users will be prompted to authenticate with their Viam credentials before accessing your application. |
| 100 | + |
| 101 | +## Application Flow |
| 102 | + |
| 103 | +1. User navigates to `your-app-name.your-public-namespace.viamapps.com` |
| 104 | +2. User authenticates with Viam credentials |
| 105 | +3. User selects an organization, location, and machine |
| 106 | +4. User is redirected to `your-app-name.your-public-namespace.viamapps.com/machine/{machine-id}` |
| 107 | +5. Your application is rendered with access to the selected machine |
| 108 | + |
| 109 | +## API Changes |
| 110 | + |
| 111 | +The Single Page Apps feature introduces the following API changes: |
| 112 | + |
| 113 | +### App Object |
| 114 | + |
| 115 | +```protobuf |
| 116 | +message App { |
| 117 | + string name = 1; |
| 118 | + string type = 2; |
| 119 | + string entrypoint = 3; |
| 120 | +} |
| 121 | +``` |
| 122 | + |
| 123 | +### UpdateModuleRequest |
| 124 | + |
| 125 | +```protobuf |
| 126 | +message UpdateModuleRequest { |
| 127 | + string module_id = 1; |
| 128 | + Visibility visibility = 2; |
| 129 | + string url = 3; |
| 130 | + string description = 4; |
| 131 | + repeated Model models = 5; |
| 132 | + string entrypoint = 6; |
| 133 | + optional string first_run = 7; |
| 134 | + repeated App apps = 8; |
| 135 | +} |
| 136 | +``` |
| 137 | + |
| 138 | +### GetAppContentRequest/Response |
| 139 | + |
| 140 | +```protobuf |
| 141 | +message GetAppContentRequest { |
| 142 | + string public_namespace = 1; |
| 143 | + string name = 2; |
| 144 | +} |
| 145 | +
|
| 146 | +message GetAppContentResponse { |
| 147 | + string url = 1; |
| 148 | +} |
| 149 | +``` |
| 150 | + |
| 151 | +## Limitations |
| 152 | + |
| 153 | +- Single Page Apps currently only support single-machine applications |
| 154 | +- All modules with apps must have public visibility |
| 155 | +- There is no versioning or separate deploy step; the page will always render the latest version |
| 156 | +- Browsers with cookies disabled are not supported |
| 157 | + |
| 158 | +## Security Considerations |
| 159 | + |
| 160 | +- Customer apps are stored in GCS buckets that are publicly available on the internet |
| 161 | +- Avoid uploading sensitive information in your application code or assets |
| 162 | +- API keys and secrets are stored in the browser's localStorage or sessionStorage |
| 163 | + |
| 164 | +## Example |
| 165 | + |
| 166 | +Here's a complete example of creating and uploading a simple React application as a Viam Single Page App: |
| 167 | + |
| 168 | +```bash |
| 169 | +# Create a new React app |
| 170 | +npx create-react-app my-viam-app |
| 171 | +cd my-viam-app |
| 172 | + |
| 173 | +# Build the app |
| 174 | +npm run build |
| 175 | + |
| 176 | +# Create a module with the app |
| 177 | +viam module create --name my-viam-app --public-namespace your-namespace |
| 178 | + |
| 179 | +# Edit meta.json to add the application configuration |
| 180 | +# Add the following to meta.json: |
| 181 | +# "visibility": "public", |
| 182 | +# "applications": [ |
| 183 | +# { |
| 184 | +# "name": "my-app", |
| 185 | +# "type": "web", |
| 186 | +# "entrypoint": "build/index.html" |
| 187 | +# } |
| 188 | +# ] |
| 189 | + |
| 190 | +# Copy the build directory to the module directory |
| 191 | +cp -r build/ path/to/module/ |
| 192 | + |
| 193 | +# Build and upload the module |
| 194 | +viam module build local |
| 195 | +viam module upload module.tar.gz |
| 196 | +``` |
| 197 | + |
| 198 | +After the module is approved, your application will be available at `https://my-app.your-public-namespace.viamapps.com`. |
0 commit comments