Generated portal project structure

The generated portal project combines a Portal Definition workspace with local preview tooling. This guide covers the files used for Portal Definition authoring. Each authored JSON file represents one PortalResource in the graph.

Definition files

Path	Purpose
`.fluidrc`	Links the project to a remote Portal Definition. Change it only when you intend to relink the project.
`portal/definition.json`	Stores top-level Portal Definition metadata.
`portal/screens/`	Stores one screen resource per JSON file.
`portal/navigations/`	Stores ordered web or mobile navigation resources.
`portal/profiles/`	Stores profile matching and navigation or theme assignments.
`portal/themes/`	Stores complete theme resources.
`.portal-sync/`	Stores tool-managed synchronization state. Never edit or commit it.

The file name is the resource slug. A display name inside the JSON does not replace that slug.

Project tooling

Path	Purpose
`package.json`	Defines the project scripts and dependency versions.
`vite.config.ts`	Configures the Vite build with the React and Tailwind CSS plugins. `fluid portal dev` adds the portal preview plugins itself when it starts the dev server, so the file doesn’t list them.
`tsconfig.json`	Configures TypeScript checks.
`.env.example`	Documents supported local environment variables without secrets.
`.env` and `.env.local`	Store local credentials and overrides. Never commit them.
`AGENTS.md`	Gives coding agents version-matched authoring instructions.

The installed package documentation matches the dependency versions in the project. Use it when local editor type information is unavailable.

Custom pages and route order

The project’s src/main.tsx starts the portal with createPortal from @fluid-app/portal-sdk. Keep screens, navigation and content in the Portal Definition, so admins can keep editing them in the Portal Builder. Add code only for a page the builder can’t make.

import { createPortal } from "@fluid-app/portal-sdk";
import { CommissionReport } from "./pages/CommissionReport";
import { RepProfile } from "./pages/RepProfile";

createPortal({
  customPages: {
    reports: CommissionReport,
  },
  memberTypeCustomPages: {
    rep: { profile: RepProfile },
  },
});

Option	What it does
`customPages`	React pages keyed by route slug. Each page receives the `slug` and any `params` from the rest of the path.
`memberTypeCustomPages`	Pages keyed by member type slug, then by route slug. For members of that type, they win over `customPages`.
`remoteWidgets`	Widget Package loading options, including the `functions` that implement your company’s portal functions.
`shell`	Options for the portal’s shell.
`providers`	A component that wraps the whole portal, for your own React providers.
`fluid`	Overrides for the SDK’s Fluid connection settings.
`errorReporter`	Receives errors the portal doesn’t catch.

When someone opens a route, the portal renders the first match:

A member type page for the viewer’s member type, at that slug.
A custom page at exactly that slug.
A custom page at the slug of the navigation item the route starts with. For example, customPages.reports renders /reports/2026-09 when a navigation item has the slug reports, with params set to 2026-09.
A system screen at that slug.
A screen from the Portal Definition, matched by its navigation item, then by slug.
Page not found.

So a custom page replaces the system screen or builder screen at the same slug. Use customPages.profile to replace the built-in profile screen. A builder screen can’t replace a system screen, so give your screens slugs that system screens don’t use. A member type page doesn’t get past the rep-only rule for messages and my-site. See System screens with extra rules. Company Widget Packages can also live in the generated project:

Path	Purpose
`src/widgets.config.ts`	Registers company-owned Widget Packages.
`src/widgets/`	Stores company widget source.
`.fluid/widget-dist/`	Contains generated publication artifacts. Do not edit or commit it.

These files belong to the company Widget Package workflow, not to the Portal Definition JSON contract.

Preserve generated state

Do not edit generated content to work around a failed command. Fix author-owned JSON or source, then regenerate. Preserve local changes before pull, clone, or recovery operations.

Get started

Sites

Mist apps

Core concepts

Guides

Guided setup

Storefront guides

SDKs

Portal & Widgets

Generated portal project structure

Definition files

Project tooling

Custom pages and route order

Widget files in a portal project

Preserve generated state