DOCS-3472: Add documentation for Viam Apps #4335

promptless · 2025-05-21T11:34:00Z

Main changes are here: https://deploy-preview-4335--viam-docs.netlify.app/operate/control/viam-app/

TODO:

Add note to https://docs.viam.com/manage/troubleshoot/teleoperate/custom-interface/
use a CNAME record to "hide" URL

Created comprehensive documentation for the new Viam Single Page Apps feature (APP-7529) that allows users to upload single page applications and access them via appname.publicnamespace.viamapps.com with hosting, authentication, and boilerplate logic handled by Viam. Added a main reference page, updated module configuration and naming documentation.

netlify · 2025-05-21T11:34:05Z

✅ Deploy Preview for viam-docs ready!

Name	Link
🔨 Latest commit	`36f207b`
🔍 Latest deploy log	https://app.netlify.com/projects/viam-docs/deploys/683d889a4f64eb00089ac3bc
😎 Deploy Preview	https://deploy-preview-4335--viam-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 53 (🟢 up 8 from production) Accessibility: 100 (no change from production) Best Practices: 100 (no change from production) SEO: 92 (no change from production) PWA: 70 (no change from production) View the detailed breakdown and full score reports

To edit notification comments on pull requests, go to your Netlify project configuration.

viambot · 2025-05-21T11:34:15Z

👋 Thanks for contributing! A reviewer will look at it on the next working day!

npentrel · 2025-05-23T21:01:10Z

docs/tutorials/projects/create-single-page-app.md

Haven't looked at this yet - do not review yet

npentrel · 2025-05-23T21:06:28Z

@bashar-515 would you mind reviewing just https://deploy-preview-4335--viam-docs.netlify.app/operate/control/single-page-apps/ this is the file: https://github.com/viamrobotics/docs/pull/4335/files#diff-1385fdec2acd1b00756a9f8d97d02712493ecd5909edc99b6db7cb4259c85a70 ? The rest isn't quite finished yet

npentrel · 2025-05-27T11:12:12Z

assets/tutorials/air-quality-fleet/get-readings.png

Unrelated but doesn't hurt to keep it here

npentrel · 2025-05-27T11:17:12Z

I have moved the tutorial update to #4340. This PR is ready for review

bashar-515 · 2025-05-27T19:24:28Z

docs/operate/control/viam-app.md

+weight: 5
+layout: "docs"
+type: "docs"
+description: "Create and deploy custom web interfaces for your machines as single-page applications without managing hosting and authentication."


Discussed on Slack- I think we should remove any mention of "single-page"

bashar-515 · 2025-05-27T19:27:46Z

docs/operate/control/viam-app.md

+
+### Access machines from your app
+
+Viam apps provide access to a machine by placing its API key in your local storage.


The API Key ends up getting stored as a cookie, not in localStorage or sessionStorage.

bashar-515 · 2025-05-27T19:29:46Z

docs/operate/control/viam-app.md

+} = JSON.parse(Cookies.get(machineId)!));
+```
+
+For developing your app on localhost, add the same information to your browsers local storage.


This is getting removed, right? If so, we'll make sure to ping you when this ticket is done so this doc can be updated.

yeah, we won't publish until that ticket is ready. I just thought we were more eager to get this live than we apparently are

docs/operate/control/viam-app.md

bashar-515 · 2025-05-27T19:31:22Z

docs/operate/control/viam-app.md

+<!-- prettier-ignore -->
+| Property     | Type   | Description |
+| ------------ | ------ | ----------- |
+| `name`       | string | The name of your application, which will be a part of the app's URL (`name_publicnamespace.viamapplications.com`). For more information on valid names see [](/operate/reference/naming-modules/#valid-application-identifiers). |


This didn't render anything for me in the preview.

bashar-515 · 2025-05-27T19:32:35Z

docs/operate/control/viam-app.md

+
+- Customer apps are stored publicly available on the internet
+- Avoid uploading sensitive information in your application code or assets
+- API keys and secrets are stored in the browser's localStorage or sessionStorage


Same as previous comment, stored in cookies rather than localStorage or sessionStorage

bashar-515

Looks good barring the section about local development since it's getting removed (as discussed offline)!

JessamyT

Chrome is forcibly re-launching so putting these here before they get lost; will continue reviewing after re-launch.

docs/dev/reference/changelog.md

docs/operate/control/viam-app.md

JessamyT · 2025-05-30T17:42:11Z

docs/operate/control/viam-app.md

+
+### Access machines from your app
+
+Viam apps provide access to a machine by placing its API key in your cookies.


Suggested change

Viam apps provide access to a machine by placing its API key in your cookies.

Viam single-page apps provide access to a machine by placing its API key in your cookies.

Also, to whom do they provide access? Is this how the apps themselves access the machines? Consider rewriting for less ambiguity

promptless · 2025-05-30T17:45:54Z

Just a reminder: If you'd like me to act on any feedback you have via Github comments, just type @Promptless in your suggestion and I'll get right on it! (I won't show up in the user dropdown, but I'll process any request that has @Promptless in the comment body.)

JessamyT · 2025-05-30T18:21:29Z

docs/operate/control/viam-app.md

+
+For developing your app on localhost, add the same information to your browser's cookies.
+
+1. Navigate to [Camera Viewer](https://camera-viewer_naomi.viamapplications.com/).


Add explanation of why we are going to your demo app? If I'm making my own app that has nothing to do with cameras this feels like a strange step

that'll go away once the cookie issue is fixed so will leave for not

docs/operate/control/viam-app.md

JessamyT · 2025-05-30T18:25:09Z

docs/operate/control/viam-app.md

+1. Navigate to [Camera Viewer](https://camera-viewer_naomi.viamapplications.com/).
+2. Log in and select the machine you'd like to use for testing.
+3. Open Developer tools and go to the console.
+4. Execute the following JavaScript to obtain the cookies you need:


[opt] Maybe tell users how (i.e., "Type "allow pasting" into the console, then paste the following script....")
Though maybe this is browser-dependent and they'll figure it out (like I did)...feel free to disregard, just a thought

JessamyT · 2025-05-30T18:25:42Z

docs/operate/control/viam-app.md

+   console.log("Set 2 cookies on localhost");
+   ```
+
+6. Open the app you are building on localhost and run the resulting script.


But I haven't started building an app yet have I? If I should have, the top of the doc should be tweaked to indicate this.
"Build a custom web interface" to me implies that I'm about to get instructions for how to build a custom web interface instead of just how to connect one to my machines. Maybe "Build a custom web interface" or similar should be a prereq

docs/operate/control/viam-app.md

JessamyT · 2025-05-30T18:38:41Z

docs/operate/control/viam-app.md

+- Customer apps are stored publicly available on the internet
+- Avoid uploading sensitive information in your application code or assets
+- API keys and secrets are stored in the browser's cookies
+- Authenticate users with FusionAuth


Suggested change

- Customer apps are stored publicly available on the internet

- Avoid uploading sensitive information in your application code or assets

- API keys and secrets are stored in the browser's cookies

- Authenticate users with FusionAuth

- Customer apps are stored such that they are publicly available on the internet, so avoid uploading sensitive information in your application code or assets.

- API keys and secrets are stored in the browser's cookies.

- Users authenticate with FusionAuth.

grammar, periods, and parallel structure

docs/operate/control/viam-app.md

JessamyT · 2025-05-30T18:41:58Z

docs/operate/get-started/other-hardware/_index.md

-<td><strong>Required</strong></td>
-<td><p>A list of one or more {{< glossary_tooltip term_id="model" text="models" >}} provided by your custom module. You must provide at least one model, which consists of an <code>api</code> and <code>model</code> key pair. If you are publishing a public module (<code>"visibility": "public"</code>), the namespace of your model must match the <a href="/operate/reference/naming-modules/#create-a-namespace-for-your-organization">namespace of your organization</a>.</p>
+<td>array</td>
+<td>Optional</td>


Suggested change

<td>Optional</td>

<td><strong>Required</strong> if your module provides models</td>

[opt] Maybe better to emphasize like this since it's not just plain optional, and this is within the integrate hardware section?

It makes that column too long. If anyone makes a mistake with this the CLI will tell them about it and mostly this is auto-generated, so I'm not worried that there will be confusion.

docs/operate/get-started/other-hardware/_index.md

JessamyT · 2025-05-30T18:46:24Z

docs/operate/reference/module-configuration.md

@@ -227,6 +227,64 @@ For any version type other than **Patch (X.Y.Z)**, the module will upgrade as so
 If, for example, the module provides a motor component, and the motor is running, it will stop while the module upgrades.
 {{% /alert %}}

+### Module meta.json configuration


I really don't think we should add this. I think it will confuse people because this isn't something you put in your machine config, and because I don't want meta.json reference split across many pages.

In my IA PR I've suggested making the meta.json reference into an includes and adding it to a separate page, and if you think this info is key and not redundant, maybe it could live there. But I don't want to conflate meanings of "configure"

changed configure to create. We can move it to that file, I don't mind. I think we do just need to now have that somewhere where we can explain about the apps and modules fields

docs/operate/control/viam-app.md

docs/operate/reference/module-configuration.md

Co-authored-by: Jessamy Taylor <[email protected]>

npentrel changed the title ~~docs: Add documentation for Viam Single Page Apps~~ DOCS-3472: Add documentation for Viam Single Page Apps May 21, 2025

npentrel marked this pull request as draft May 21, 2025 11:48

npentrel force-pushed the docs-update-a3ce53e9-1afa-4e47-8e40-7a3998fb4c11-20250521-113348 branch 4 times, most recently from d89e2d9 to dd2973a Compare May 23, 2025 20:55

npentrel reviewed May 23, 2025

View reviewed changes

docs/tutorials/projects/create-single-page-app.md Outdated

Copy link

Collaborator

npentrel May 23, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Haven't looked at this yet - do not review yet

npentrel force-pushed the docs-update-a3ce53e9-1afa-4e47-8e40-7a3998fb4c11-20250521-113348 branch from dd2973a to 02c4c41 Compare May 23, 2025 21:03

npentrel and others added 4 commits May 26, 2025 19:02

Documentation updates from Promptless

a6bb349

Update

aa38d51

Draft

14fad22

Update

660da6e

npentrel force-pushed the docs-update-a3ce53e9-1afa-4e47-8e40-7a3998fb4c11-20250521-113348 branch from 02c4c41 to 11f6861 Compare May 26, 2025 17:03

Update SPA instructions

6b62ff7

npentrel force-pushed the docs-update-a3ce53e9-1afa-4e47-8e40-7a3998fb4c11-20250521-113348 branch from 11f6861 to 6b62ff7 Compare May 26, 2025 17:04

Move air quality tutorial to separate PR

79b1fc4

npentrel reviewed May 27, 2025

View reviewed changes

assets/tutorials/air-quality-fleet/get-readings.png Outdated

Copy link

Collaborator

npentrel May 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Unrelated but doesn't hurt to keep it here

npentrel force-pushed the docs-update-a3ce53e9-1afa-4e47-8e40-7a3998fb4c11-20250521-113348 branch from 03ef06e to e226798 Compare May 27, 2025 11:15

npentrel marked this pull request as ready for review May 27, 2025 11:16

npentrel force-pushed the docs-update-a3ce53e9-1afa-4e47-8e40-7a3998fb4c11-20250521-113348 branch 4 times, most recently from a6889e5 to 412fb4a Compare May 27, 2025 11:26

Cleanup

c12df67

npentrel force-pushed the docs-update-a3ce53e9-1afa-4e47-8e40-7a3998fb4c11-20250521-113348 branch from 412fb4a to c12df67 Compare May 27, 2025 11:29

npentrel requested a review from bashar-515 May 27, 2025 11:30

npentrel added 2 commits May 27, 2025 16:45

Fix links

9c78c33

Fix more links

cc31474

npentrel mentioned this pull request May 27, 2025

Update Air Quality tutorial #4340

Open

1 task

npentrel added 3 commits May 27, 2025 20:15

Change name

aedca96

Minor update

d587cff

update cachekey

939bd61

npentrel changed the title ~~DOCS-3472: Add documentation for Viam Single Page Apps~~ DOCS-3472: Add documentation for Viam Apps May 27, 2025

bashar-515 reviewed May 27, 2025

View reviewed changes

docs/operate/control/viam-app.md Show resolved Hide resolved

bashar-515 reviewed May 27, 2025

View reviewed changes

Update based on Bashar's feedback

503826a

npentrel requested a review from bashar-515 May 28, 2025 11:58

bashar-515 approved these changes May 28, 2025

View reviewed changes

JessamyT reviewed May 30, 2025

View reviewed changes

JessamyT requested changes May 30, 2025

View reviewed changes

npentrel reviewed May 30, 2025

View reviewed changes

docs/operate/control/viam-app.md Outdated Show resolved Hide resolved

npentrel reviewed May 30, 2025

View reviewed changes

docs/operate/control/viam-app.md Outdated Show resolved Hide resolved

npentrel reviewed May 30, 2025

View reviewed changes

docs/operate/reference/module-configuration.md Outdated Show resolved Hide resolved

npentrel and others added 2 commits May 30, 2025 21:50

Apply suggestions from code review

3102de7

Co-authored-by: Jessamy Taylor <[email protected]>

Updates

36f207b


		### Access machines from your app

		Viam apps provide access to a machine by placing its API key in your local storage.

	Viam apps provide access to a machine by placing its API key in your cookies.
	Viam single-page apps provide access to a machine by placing its API key in your cookies.


		For developing your app on localhost, add the same information to your browser's cookies.

		1. Navigate to [Camera Viewer](https://camera-viewer_naomi.viamapplications.com/).

	<td>Optional</td>
	<td><strong>Required</strong> if your module provides models</td>

DOCS-3472: Add documentation for Viam Apps #4335

Are you sure you want to change the base?

DOCS-3472: Add documentation for Viam Apps #4335

Uh oh!

Conversation

promptless bot commented May 21, 2025 • edited by npentrel Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

netlify bot commented May 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for viam-docs ready!

Uh oh!

viambot commented May 21, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

npentrel commented May 23, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

npentrel commented May 27, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bashar-515 left a comment

Choose a reason for hiding this comment

Uh oh!

JessamyT left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

promptless bot commented May 30, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

promptless bot commented May 21, 2025 •

edited by npentrel

Loading

netlify bot commented May 21, 2025 •

edited

Loading