React app SDKs

React apps are .tsx or .jsx files that compile and run in an isolated preview inside Arg. They can use two built-in packages without installing anything:

@arg/ui

Exact shared React controls that inherit the active Arg theme.

@arg/actions

A typed facade for discovering and running workspace Actions.

Create a React app

Create the file

Open Arg, click New file, and choose React app. A .tsx file starts with a live component and preview.

Export a component

Export one React component as the default export. The preview rebuilds from the current editor buffer, including unsaved changes.

import { useState } from "react";
import { Button, Card } from "@arg/ui";

export default function Counter() {
  const [count, setCount] = useState(0);

  return (
    <main style={{ maxWidth: 640, margin: "0 auto", padding: 32 }}>
      <Card>
        <h1>Counter</h1>
        <p>Count: {count}</p>
        <Button onClick={() => setCount((value) => value + 1)}>
          Add one
        </Button>
      </Card>
    </main>
  );
}

Add capabilities when you need them

Import @arg/ui for controls. Import @arg/actions when the app needs to run an Action. Workspace files are available separately through the folder-scoped, read-only window.arg.fs access that previews start with.

Import workspace modules

Relative imports resolve from the importing file. You can import .tsx, .ts, .jsx, .js, .mjs, .cjs, .json, and .css files, with extension and index.* fallback.

import data from "./data/summary.json";
import { MetricCard } from "./components/metric-card";
import "./styles.css";

Static imports are bundled when the preview builds. Use fs from @arg-ai/sdk (or the injected window.arg.fs, the same object) when the app needs to read changing data at runtime or write it back to the workspace.

Import npm packages

React and React DOM are provided by the preview. For another npm package, pin an exact version in the nearest workspace package.json:

{
  "dependencies": {
    "date-fns": "4.1.0"
  }
}

Then import it normally:

import { formatDistanceToNow } from "date-fns";

You can also import an exact-version HTTPS module. Node.js built-in modules do not run in the browser preview.

Desktop bundles React, React DOM, @arg/ui, and @arg/actions, so those imports compile offline. Other npm packages still need a network connection.

Grant preview capabilities

The two capability grants are independent. Workspace access starts on in folder-scoped Read mode, while Actions starts off:

Grant	What it allows	Scope
Workspace access	`window.arg.fs`, identity, and workspace member APIs	Read or read and write, over the current folder or the whole workspace
Actions	`@arg/actions` and `window.arg.actions`	The whole cloud workspace

Workspace access can be Read or Read and write, and an unconfigured preview starts with Read enabled. Under Read the app can still read files and list members, but write, remove, mkdir, move, copy, and db.exec are refused. An app that saves data should check arg.canWrite and disable those controls rather than letting them fail. On web and desktop, open Permissions in the preview toolbar to change either grant. The Advanced section there holds the access scope, whether the choice is remembered for the file, and a list of the workspace files and Actions the app’s source refers to. On iOS and Android, open the … file menu and choose Permissions. Enabling Actions opens an Allow Actions for this preview? confirmation because an Action can change files, spend credits, or use your connected services. The one-time Actions grant applies to the exact source that was reviewed. A code change revokes it. Remember for this file stores both preview choices on the current device and reapplies them when the file is opened or edited. There is no account or organization setting for these SDKs. Every control lives in the current file’s Permissions menu.

Where React apps run

Surface	React preview	`@arg/ui`	`@arg/actions`
Web	Yes	Yes	Cloud workspaces with an explicit grant
Desktop	Yes	Yes	Cloud workspaces with an explicit grant
iOS	Yes	Yes	Cloud workspaces with an explicit grant
Android	Yes	Yes	Cloud workspaces with an explicit grant

Read-only and public previews can render the app and @arg/ui, but they cannot receive viewer-authorized Actions. A deployed Site also does not inherit the viewer’s Arg session.

Build limits

One preview build can load up to 128 workspace modules. A module and the complete workspace module graph are each capped at 100 MB. Browser-compatible npm dependencies are loaded separately and must use exact versions.

Getting started

Building with agents

Core concepts

Apps

Arg SDK

Integrations

Command line

Recipes & patterns

Changelog

React app SDKs

@arg/ui

@arg/actions

Create a React app

Import workspace modules

Import npm packages

Grant preview capabilities

Where React apps run

Build limits

Next steps

@arg/ui

@arg/actions

​Create a React app

​Import workspace modules

​Import npm packages

​Grant preview capabilities

​Where React apps run

​Build limits

​Next steps

Create a React app

Import workspace modules

Import npm packages

Grant preview capabilities

Where React apps run

Build limits

Next steps