Create an offline-capable application with the embedded ontology

The embedded ontology enables applications to sync ontology data locally, allowing users to interact with data without network connectivity and install applications as progressive web apps ↗ (PWAs). This guide offers a walkthrough for creating a Foundry application with offline support using the embedded ontology React template in the @palantir/lohi-ts library.

Prerequisites

Before starting, complete standard application setup with the steps below.

1. Create a client-facing application in Developer Console. See Create an application using Developer Console for detailed instructions. On the Application type page, select Client-facing application.
2. Select your ontology and the object types you want to include.
3. Generate the SDK for your application.
4. Configure website hosting, including subdomain and redirect URLs. Refer to Deploy a custom application on Foundry for more information.

1. Enable WebAssembly execution in the content security policy

To support offline functionality, your application will use WebAssembly (Wasm). You must configure the content security policy to allow Wasm execution.

1. In Developer Console, navigate to Website Hosting and open the Advanced tab.
2. Under the scriptSrc section, add: 'wasm-unsafe-eval', including the single quotes.
3. Verify that the configuration appears in the preview panel on the right.

2. Bootstrap a repository with the embedded ontology React template

Use the repository bootstrapper to create your repository with the ontology React template.

1. In Developer Console, navigate to Start developing > Bootstrap in Foundry.
2. From the template dropdown, select Embedded Ontology React.
3. Select Generate repo.

The template will be configured with the following backing repositories:

• osdk-templates-bundle: Provides the embedded ontology (lohi-ts) application template.
• lohi-asset-bundle: Contains the lohi-ts library and dependencies.
• nodejs-bundle: Node.js runtime for CI/CD.

3. Configure your application

Verify environment configuration

1. Open .env.production in your repository.
2. Update VITE_FOUNDRY_REDIRECT_URL with your website subdomain, substituting your-enrollment with your enrollment name.

Copied!
1
VITE_FOUNDRY_REDIRECT_URL=https://your-subdomain.your-enrollment.palantirfoundry.com/auth/callback

Configure objects to be synced

The template comes with a pre-configured client.ts file that uses lohi-ts. You need to specify which ontology objects to sync for offline use.

1. Open src/client.ts.
2. Import the object types from your generated SDK as shown below:

Copied!
1
import { Employee, Task } from "@your-app/sdk";import { type ObjectTypeDefinition } from "@osdk/client";

3. Update the syncObjects array with the objects you want available offline:

Copied!
1
const syncObjects: ObjectTypeDefinition[] = [Employee, Task];

The template includes a working example in src/components/LohiExample.tsx that demonstrates the sync pattern.

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
import { SyncState, type Client } from "@palantir/lohi-ts";import { useOsdkClient } from "@osdk/react";
function YourComponent() {
  const client = useOsdkClient() as Client;
  const [syncState, setSyncState] = useState<SyncState | null>(null);

  useEffect(() => {
    (async () => {
      const currentState = await client.syncState();
      setSyncState(currentState);

      if (currentState !== SyncState.Ready) {
        await client.sync();
        setSyncState(await client.syncState());
      }
    })();
  }, [client]);

  *// Your component logic here*
}

For more details on using an embedded ontology in your application, refer to the README.md in your generated repository.

4. Develop your application

With the template configured, you can now develop your application logic offline, or in a VS Code workspace.

1. Use the embedded ontology client to query and load objects.
2. Apply actions and edits as needed.
3. The template handles offline sync automatically.

The template is pre-configured with the following features:

• Preinstalled @palantir/lohi-ts dependency.
• The lohi-ts Vite plugin configured for Wasm optimization.
• A client configured with proper error handling.
• Example components showing the correct sync pattern.

5. Deploy your application

You can use the tag version feature in a Foundry VS Code workspace or code repository to create a version tag for your application’s release.

You can also deploy your application using git tags if you are working offline:

Copied!
1
2
git tag 1.0.0
git push origin tag 1.0.0

Code Repositories will automatically build and deploy your application to the configured subdomain. For more details on deployment options, refer to Deploy a custom application on Foundry.

6. Install as a progressive web app

Once your application is deployed, users can install it as a progressive web app for offline access and a native-like experience.

Install the application

1. Navigate to your deployed application in a supported browser. This includes Chrome, Edge, Safari, or other Chromium-based browsers.

2. Look for the Install or Add to Home Screen prompt:

   • Desktop browsers: An install icon typically appears in the address bar as shown below:
     
     
     
     You can also navigate to Cast, Save, and Share > Install Page as App... from the menu button to the right of the address bar.
     
     
     
     
   • Mobile browsers: An Add to Home Screen option appears in the browser menu.

3. Select Install and follow the browser's prompts.

4. The application will be installed and can be launched from your device like a native application.

Use the application offline

After installation, you can launch the application from your installed apps or home screen. The application will work offline using synced ontology data. When connectivity is restored, the application will automatically sync the latest data. Users can continue working with local data even without network access.

Common issues

CORS errors

Ensure that your Foundry enrollment allows CORS for the following:

• Development: http://localhost:8080
• Production: Your website subdomain

Configure CORS in Control Panel if you have permission, or contact your Foundry administrator.

TypeScript errors on client.sync()

If you see TypeScript errors when calling client.sync() or client.syncState(), ensure that you are casting the client as follows:

Copied!
1
const client = useOsdkClient() as Client;

Build failures with dev-dist

If you see build errors related to the dev-dist directory, delete the directory. This directory is automatically generated and is already included in the .gitignore.

Next steps

• Explore the template README for advanced usage patterns.
• Test your application offline by disabling network connectivity.
• Configure additional PWA features like custom icons and splash screens.
• Share your PWA install link with users.