SuperRepo is in the beta phase of development and may not be available on your enrollment. Functionality may change during active development.
For a repository to be a SuperRepo, it must have a foundry.yml file at its root declaring the project structure: each component's type and path. This file also allows you to declare the output artifacts (a Marketplace product) or even multiple outputs.
The foundry.yml configuration file can either hold a top-level components list or a top-level products list with a components key within each product. In a multi-product configuration, declare a bundle key within each product to define its output artifact. Review the following example:
Copied!1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26products: - components: - type: ONTOLOGY path: ./ontology - type: APP path: ./app osdkOutput: ontology/osdk-output apiNamespace: com.palantir.ontology bundle: name: "operations-console" description: "example description" mavenCoordinate: "com.example:operations-console" installMode: SINGLETON - components: - type: ONTOLOGY path: ./analytics/ontology - type: APP path: ./analytics/app osdkOutput: analytics/ontology/osdk-output apiNamespace: com.palantir.analytics bundle: name: "analytics-console" description: "example description" mavenCoordinate: "com.example:analytics-console" installMode: SINGLETON
When using a multi-product configuration, pass the --product <bundle name> option to every Foundry CLI command to indicate which product to run against.
To exclude a product from the packaged output without removing it from the file, set includeInBundle: false on that product. The option defaults to true when omitted.
A single-product SuperRepo is packaged with one command, foundry bundle --project-version <VERSION>. That command does not accept a multi-product configuration: if foundry.yml declares more than one product, it fails and directs you to the two subcommands below instead.
Bundle a multi-product SuperRepo in two stages:
foundry bundle product --product <bundle name> --project-version <VERSION> once for each product. Each invocation writes that product's packaged output to build/<bundle name>/blockset.zip. Because --project-version is supplied per invocation, products in the same repository can be versioned independently.foundry bundle store to assemble those outputs into build/store.zip. This command takes no version argument; pass --output to write the store elsewhere. If a product has not been bundled yet, the command fails with the expected path and the foundry bundle product invocation needed to produce it.Neither stage is implied by foundry deploy, which expects the store to exist already and fails if it does not. Bundle before you deploy.
The components within a product can be freely moved around. For instance, moving ./ontology to ./platform/ontology touches three manifest keys:
Copied!1 2 3 4 5 6 7 8 9 10 11components: - type: ONTOLOGY - path: ./ontology + path: ./platform/ontology imports: - - ontology: ontology/external-imports/ontology-full-metadata.json + - ontology: platform/ontology/external-imports/ontology-full-metadata.json -osdkOutput: ontology/osdk-output +osdkOutput: platform/ontology/osdk-output
SuperRepo preview can use local seed data or read live objects from your Foundry Ontology. Set the top-level preview.ontology configuration in foundry.yml to choose the data source:
| Mode | Data source | Ontology edits |
|---|---|---|
SEED_ONLY (default) | Local embedded Ontology, populated with optional seed data | Supported locally |
REMOTE_ONLY | Live objects from the Foundry Ontology identified by ontologyRid | Rejected |
The mode applies to the entire preview Ontology. preview is a top-level key, so in a multi-product configuration a single setting applies to every product. Restart preview after changing foundry.yml. These settings affect preview only.
To preview against live data, add the following configuration to foundry.yml. Replace the example ontologyRid with the RID of the Ontology you want to read. To find the RID, open Ontology Manager, select your Ontology, open the Ontology configuration tab, and copy the RID from the Ontology metadata section:
Copied!1 2 3 4preview: ontology: mode: REMOTE_ONLY ontologyRid: ri.ontology.main.ontology.00000000-0000-0000-0000-000000000000
Remote reads use the credentials stored by foundry login, so preview returns only objects you can access on your enrollment.
When preview starts, it compares each ontology type defined or imported in your ONTOLOGY component with the ontology type of the same API name in the target Ontology. If a type does not exist in that Ontology or you cannot access it, preview fails to start. If its properties differ, preview fails with a Foundry schema mismatch error. Deploy your Ontology changes first, update imported definitions if they have changed in Foundry, or use SEED_ONLY to preview without matching Foundry schema.
Your application and functions still run locally. Functions can read Foundry data through the platform API proxy without additional platformApiProxy routes. Ontology edits, including edits returned by function-backed actions, are rejected. Use SEED_ONLY to preview creating, updating, or deleting objects and links.
In SEED_ONLY mode, foundry runs a local embedded Ontology server for the types defined or imported inside your SuperRepo's ONTOLOGY component. You can populate it with seed data or create objects by invoking local actions. Seed data is local to preview and is never deployed.
To configure a directory of TypeScript seed files, add seedDir to preview.ontology in foundry.yml. The path is relative to the directory containing foundry.yml.
Copied!1 2 3 4preview: ontology: mode: SEED_ONLY seedDir: ontology/seed
Only top-level .mts files are compiled, in sorted filename order, which is why the demo template numbers them 001-, 002-, and 003-. Each file default-exports a createSeed call. The first argument to seed.add is the generated SDK constant for the object type, and every non-nullable property is required, including the primary key. Primary keys must be unique within an object type across the whole directory. The seed.link function takes the references returned by seed.add, and both ends must be registered in the same call.
Copied!1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17import { seller, superproduct } from "@ontology/sdk"; import { createSeed } from "@osdk/seed-helpers"; export default createSeed((seed) => { const charger = seed.add(superproduct, { pk: "prod-004", title: "USB-C 100W GaN Charger", price: 5900, newPrice: 4720, description: "Compact 100W USB-C GaN wall charger", }); const halcyon = seed.add(seller, { pk: "seller-003", name: "Halcyon Desk Co.", }); seed.link("charger-seller-link", charger, "sellers", halcyon, "superproducts"); });
Each invocation of foundry start ontology starts with a fresh local database and reapplies the seed files. Stopping and starting preview discards local edits.
Within a running preview, changes to the Ontology schema or compiled seed data reset the local data and reapply the seeds. Function-only changes preserve local data.
If a seed file fails to compile during preview, the server continues with the previous seed data and retries when you edit the file. A failure while loading recompiled seed data can leave incomplete local data until the next successful reload. Inspect the preview output and correct the seed files.
The foundry create command wires up Nx, but the CLI reads neither the nx.json nor the project.json file. SuperRepo and the Foundry CLI are therefore independent of the orchestration framework you choose. The default template uses Nx because it is widely used; to migrate away from Nx, port the Foundry CLI invocations from the project.json files into another system.
During migration, you must wrap every Node install with foundry run-with-auth. It injects FOUNDRY_HOSTNAME and FOUNDRY_TOKEN so that the .npmrc files can rely on these environment variables.
When your application consumes resources from other origins, you must allow those origins in the Content Security Policy (CSP) of the website that Foundry manages for your product. Otherwise, the browser blocks the request. Declare the additions with the contentSecurityPolicyAdditions key:
Copied!1 2 3contentSecurityPolicyAdditions: img-src: - tile.openstreetmap.org
Each key is a standard CSP directive name and each value is a list of allowed sources, such as https://api.example.com or 'self'. The following directive names are valid: connect-src, frame-src, img-src, media-src, script-src, style-src, font-src, and frame-ancestors.
contentSecurityPolicyAdditions is a per-product key, declared alongside components and bundle, and it only applies when the product has an APP component. In a single-product foundry.yml the key therefore appears at the top level of the file, as shown above. In a multi-product configuration, declare it within each product that needs it, as described in the Add multiple products section.
Applications commonly call Foundry platform APIs through the Ontology SDK. The SuperRepo local preview server implements some of these platform APIs, but not all. For instance, to use the LLM provider proxies of the platform API, you must send requests to your Foundry enrollment. To read Ontology objects from Foundry, use REMOTE_ONLY preview instead of proxy routes.
SuperRepo preview supports proxying API calls to a remote Foundry instance by defining the top-level platformApiProxy key inside the foundry.yml file, as shown in the following example:
Copied!1 2 3 4 5 6platformApiProxy: passthrough: - path: /api/v2/admin/users/getCurrent methods: [GET] - path: /api/v2/llm/proxy/openai/v1/responses methods: [POST]
After you declare these paths, the preview server answers requests from the Ontology SDK client for the paths and methods listed above. These requests are proxied to your Foundry enrollment using the credentials stored by foundry login, not the token you exported when you installed the Foundry CLI. If your stored credentials expire, run foundry login refresh and restart local preview.
The platformApiProxy configuration does not affect the deployed products and is only effective during preview.