Private components — Frontfriend

Private components extend your Design System with source owned by your team. Frontfriend provides the cloud infrastructure for the private registry, authenticated access and version management, alongside the CLI workflows that connect your applications to the system.

Your team creates the components and controls their versions. Frontfriend hosts the registry and provides the delivery infrastructure. See the CLI reference for project setup, component downloads and design-context sync.

A clear home for custom code

A private component belongs to one Design System and is bound to its ffId. Its explicit address uses a custom/... namespace with categories chosen by the client. That address is separate from framework metadata and from the installation path chosen by the application.

No invisible overrides

Private components do not automatically shadow canonical components. Installing private source over a canonical file must be explicit and confirmed. Sharing the same source with another Design System requires deliberate republication under that system’s identity.

Immutable versions

A private component version is an immutable source bundle with an independent semantic version, Markdown changelog and declared npm/private dependencies. Releases pin exact versions and validate dependency closure.

Install and publish

pnpm exec frontfriend add custom/acme/data-grid --dry-run
pnpm exec frontfriend add custom/acme/data-grid --yes
pnpm exec frontfriend publish --manifest ./frontfriend-component.json

The manifest identifies the custom/... address, target, SemVer, changelog, local source files and declared dependencies. Publication is a platform write and advances the base Release according to your plan and role. Review the manifest and source before publishing. Component downloads require authenticated Studio access.

For example, place frontfriend-component.json at your app root next to the source file it names:

{
  "address": "custom/acme/status-note",
  "semver": "1.0.0",
  "changelog": "Add a reusable status note for account screens.",
  "projectTarget": { "framework": "react", "primitive": "base" },
  "files": [
    {
      "source": "src/components/status-note.tsx",
      "target": "src/components/status-note.tsx"
    }
  ],
  "npmDependencies": ["react@^19.0.0"],
  "componentRequirements": []
}

Both file paths are relative: source is relative to the manifest; target is the installation path. Include every local dependency in the bundle or declare its component requirement. Never include credentials or environment files. Publish a new SemVer for later changes; an existing version is immutable.

Deleted components

Owners and admins can delete a private component with all its versions. In Studio, open the component’s menu, choose Delete component… and type its address to confirm. A component that another component requires cannot be deleted; delete that one first. A deleted address cannot be published again; publish under a new address.

When a private component is deleted from the Design System, no Release provides it any more. The next frontfriend update removes it from frontfriend.lock.json and reports custom/... was deleted from the design system. It keeps the component’s files in the app; remove them and their imports if you no longer use them. add and download refuse a deleted component that the lock still pins. diff and doctor show the pin until update removes it.

Who can publish

In Cloud Self-serve, members can publish to base. Admins and owners promote and roll back along custom workflows directly. A member requests a promotion or rollback, and an admin or owner approves it before the tag moves. Cloud Managed workspaces consume releases while Frontfriend operates authoring, publication and approvals.

Follow Versions & releases, Plans and access before planning a rollout.