• Documentation
    • Search documentation
    karat

    +

    K

    API Reference ↗
    Use case developmentOSDK React applicationsDevelopment environment

    Development environment

    This page will walk you through the development workflow when using an in-platform VS Code workspace to build OSDK React applications

    Get started

    After following the steps to set up your Developer Console, you can start developing in your code environment. To use a VS Code workspace, select Create code repository under the Code Repository section in the left side panel. This action will bootstrap your repository with the default React template. You can then select Open in VS Code to launch an in-platform workspace.

    Create a code repository in a VS Code Workspace from Develop Console

    The repository template will include a basic React application integrated with authorization and the Ontology SDK.

    Development lifecycle

    Once the VS Code Workspace is launched, you should see the code editor on the left and a live preview of your application on the right. You can start editing your code as if working in a local environment.

    The VS Code Workspace landing page.

    Edit

    You can now start building your React application. Be sure to edit and test your code after writing, then use git commands or the VS Code interface to commit and push your changes to make them visible to other developers in your project. In the terminal, run npm run lint, npm run test, and npm run build to ensure that checks will succeed.

    You can also refer to the Ontology tab in the left side panel to view generated documentation and code snippets for your OSDK and return to Developer Console.

    The available options in the "Ontology" tab in a VS Code workspace.

    Deploy

    To deploy a React application, you must first cut a release. This is commonly done with the git tag command, where you can set the version number and then push it to your repository:

    Copied!
    1
2
git tag <x.y.z>
git push origin tag

    Alternatively, you can cut a release from within the Code Repositories interface by selecting Open in Code Repositories from the top right corner of the screen. Navigate to the the Version control tab, the open the Tags and releases section to view previous releases and cut a new release.

    The "Tags and releases" section of the "Version control" tab in Code Repositories.

    Once the release passes checks, you will be able to view your application in Developer Console.

    Code Repositories checks & Developer Console website hosting

    Content Security Policy

    By default, we apply a restrictive Content Security Policy (CSP). This means a request to non-Foundry URIs will fail and must be explicitly allowed.

    To detect a CSP error, select <F12> and review logs inside the console. If you have CSP failures, you will see errors similar to those shown below:

    An example CSP error in a console.

    You can apply a temporary CSP to your VS Code workspace. For security reasons, this CSP will not apply to other users of this workspace and will expire when the workspace is paused or restarted.

    The workflow to add a CSP to a VS Code workspace.

    After testing your application inside the VS Code workspace, ensure that the CSP is updated for your Developer Console application.

    The CSP configuration screen for Developer Console.

    Development tips

    To Do application tutorial

    If you are new to Developer Console and OSDK, we recommend following one of our tutorials to get started. Navigate to the Build with AIP application in your enrollment and install one of our example workflows.

    Available To Do application tutorials in Build with AIP.

    Progressive Web Application (PWA)

    For an optimized editing experience, you can choose to install your workspace as a Progressive Web Application (PWA). A PWA will accept some commonly used shortcuts, such as Cmd+W (macOS) to close a tab.

    Pop-up messages to install and open a PWA application.

    An example PWA application in VS Code Workspaces.

    Zen mode

    For a nearly native VS Code experience, we recommend using Zen mode. Select View > Activate Zen mode to enable. Zen mode will hide the platform interface and make VS Code take up the entire browser window. To exit Zen mode, hover over the three dots ... in the top center of your screen.

    The option to use zen mode and a view of how it looks in the platform.

    Local development

    Instead of working inside the platform, you can work locally on your machine in the following ways:

    • Navigate to your repository in the Code Repositories application, then select Work locally in the top right corner of your screen to clone your repository.

    The option to work locally from Code Repositories.

    .npmrc configuration

    To work both locally and in-platform with a VS Code workspace, we require local development to use the Gradle commands ./gradlew npmInstall, ./gradlew npm_run_dev, ./gradlew npm_run_lint instead of using npm directly.

    Working locally and inside VS Code workspaces requires .npmrc to be configured to work in both environments. When you create Developer Console application, the default .npmrc looks something similar to below:

    //${ORG_GRADLE_PROJECT_artifactsApiUriWithoutProtocol}/repositories/ri.stemma.main.repository.<rid>/contents/release/npm/:_authToken=${ORG_GRADLE_PROJECT_bearerToken}
registry=${ORG_GRADLE_PROJECT_artifactsApiUri}/repositories/ri.stemma.main.repository.<rid>/contents/release/npm/
omit-lockfile-registry-resolved=true

    The .npmrc file is templated with environment variables. This is required because the network configuration inside a VS Code workspace differs from your local machine.