example: add cross-package SharedTree schema consumption example by WillieHabi · Pull Request #26522 · microsoft/FluidFramework

WillieHabi · 2026-02-23T22:17:30Z

Description

Adds a minimal two-package example (schema-provider + schema-consumer) demonstrating cross-package consumption of SharedTree schemas defined with objectAlpha().

Also merges the tree entrypoint fix from jason-ha@4c04950, which restructures @fluidframework/tree's package.json exports so each API tier (., ./alpha, ./beta, etc.) has its own JS entrypoint.

With this fix, the example consumer imports schemas through standard imports with no workarounds needed.

Copilot

Pull request overview

Adds a new examples/utils/cross-package-schema two-package example intended to demonstrate consuming SharedTree objectAlpha() schemas across package boundaries by using TypeScript customConditions: ["source"] and a "source" export condition to bypass problematic .d.ts path normalization under TS 5.9 + moduleResolution: "bundler".

Changes:

Add a new schema-provider package exporting SharedTree schema classes with a "source" export condition and a TS 5.9 “bundler” build mode to reproduce the .d.ts issue.
Add a new schema-consumer package that imports the provider’s schemas and demonstrates success/failure with and without customConditions: ["source"].
Add documentation and lockfile updates to wire the new example packages into the repo.

Reviewed changes

Copilot reviewed 13 out of 14 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
pnpm-lock.yaml	Adds new workspace importers for the provider/consumer example packages and updates a dependency resolution entry.
examples/utils/cross-package-schema/README.md	Documents the problem, the `"source"`-condition workaround, and verification steps.
examples/utils/cross-package-schema/schema-provider/package.json	Defines the provider package exports (including `"source"`), build scripts, and dependencies.
examples/utils/cross-package-schema/schema-provider/tsconfig.json	Provider baseline TS config for Node16 resolution output to `lib`.
examples/utils/cross-package-schema/schema-provider/tsconfig.bundler.json	Provider TS 5.9+ `bundler`-resolution config to reproduce `.d.ts` normalization.
examples/utils/cross-package-schema/schema-provider/src/schema.ts	Declares a small set of `objectAlpha()`-based schema classes to export.
examples/utils/cross-package-schema/schema-provider/src/index.ts	Re-exports the provider schema classes as the public entrypoint.
examples/utils/cross-package-schema/schema-provider/eslint.config.mts	Adds local ESLint flat-config wiring consistent with other examples.
examples/utils/cross-package-schema/schema-consumer/package.json	Defines the consumer package scripts for the “with source condition” pass and “without source condition” failure demonstration.
examples/utils/cross-package-schema/schema-consumer/tsconfig.json	Enables `customConditions: ["source"]` for the success-path typecheck.
examples/utils/cross-package-schema/schema-consumer/tsconfig.no-source.json	Consumer TS config variant that omits `customConditions` to reproduce the failure.
examples/utils/cross-package-schema/schema-consumer/src/consume.ts	Imports provider schemas and constructs a `TreeViewConfiguration` to validate compatibility.
examples/utils/cross-package-schema/schema-consumer/src/index.ts	Re-exports the consumer example entrypoint/types.
examples/utils/cross-package-schema/schema-consumer/eslint.config.mts	Adds local ESLint flat-config wiring consistent with other examples.

Files not reviewed (1)

pnpm-lock.yaml: Language not supported

examples/utils/cross-package-schema/schema-consumer/src/consume.ts

examples/utils/cross-package-schema/schema-provider/package.json

examples/utils/cross-package-schema/schema-consumer/package.json

relying on tree exports being setup for normal consumption patterns - no special setup to share schema across packages

Stage tree entrypoint files such that none reference index.js directly that may result in consumer packages generating .d.ts files with incorrect tree imports. tree entrypoints are no longer generated during build. Changes for exposed API surface require updating files under src/entrypoints, which may use ` generate:entrypoint-sources` script. Update entrypoint linting to use new sources, but keep them from being formatted or linted. Until 0.64 build-tools are used, legacy.d.ts Node10 file won't be generated and is temporarily checked in.

This reverts commit 292b58b.

…nto cross-package-schema

Tree's generate:entrypoint-sources script produces files that overlap with tsc output, causing policy check failures. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

This reverts commit a989191.

into a bash script that policy checker doesn't understand.

jason-ha

Looks pretty good - you'll obviously need another review since I have decent contributions in here.
Do update the PR title and description.
Apologies if this posts with seemingly irrelevant comments. I apparently never submitted notes I had from last week. I tried to cleanup things that I could see to be accurate.

jason-ha · 2026-02-24T22:32:43Z

examples/utils/cross-package-schema/schema-provider/package.json

+			"types": "./src/index.ts",
+			"default": "./lib/index.js"


Should only support "import" condition - like is used in ".".

examples/utils/cross-package-schema/schema-provider/tsconfig.bundler.json

jason-ha · 2026-02-24T22:37:22Z

examples/utils/cross-package-schema/schema-provider/tsconfig.json

+	"compilerOptions": {
+		"rootDir": "./src",
+		"outDir": "./lib",
+		"exactOptionalPropertyTypes": false,


Do you need this? We prefer to not have this setting when possible.
I think you do - should comment on the need.

examples/utils/cross-package-schema/README.md

jason-ha · 2026-02-24T22:40:42Z

examples/utils/cross-package-schema/README.md

+## The Problem
+
+When SharedTree schema classes are defined using `objectAlpha()` and compiled with
+TypeScript 5.9+ using `moduleResolution: "bundler"`, the `.d.ts` emitter normalizes import


Is using bundler resolution a part of the problem? I didn't think that was part of the issue. The only issue as I understood it was working with generated .d.ts files.

Whoa. I'm reading step 1 below. That suggests bundler is part of the problem. So, the solution is maybe is don't use bundler resolution for your schema package? (office-bohemia doesn't require bundler resolution. It is largely used because it has relaxed rules. But should be easy to build schema package with node16 resolution.)

examples/utils/cross-package-schema/README.md

jason-ha · 2026-02-24T22:46:04Z

examples/utils/cross-package-schema/schema-provider/package.json

+	},
+	"scripts": {


For completeness, there should be a "files" block in here. "files" says what files are actually part of a published package. See presence package for an example. In this case, we want to call out src explicitly as some or all of it is needed. (Even if there aren't test files, I would exclude those paths to set a good example.)

The above is an old comment that was never apparently published. It matters more and less now that we don't need to publish src. More because a proper package wouldn't have to publish them. Less because this is super simple now.

jason-ha · 2026-03-03T00:28:01Z

biome.jsonc

 			"!**/src/**/test/types/**/*.generated.ts",
 			"!**/src/packageVersion.ts",
 			"!**/src/layerGenerationState.ts",
+			"!**/src/entrypoints/*.ts",


We do not want a broad disable of src/entrypoints from biome. The disable in tree should be temporary. If the package level biome config is a problem, then make this "absolute" just for tree with a comment.

jason-ha · 2026-03-03T00:29:05Z

pnpm-lock.yaml

-      minimatch: 10.1.1
+      minimatch: 10.2.1


okay, I think, but rogue unrelated change

jason-ha · 2026-03-03T00:33:54Z

examples/utils/cross-package-schema/schema-consumer/tsconfig.json

+		// Need to skip lib check since some .d.ts from provider are invalid.
+		"skipLibCheck": true,


No longer the case. All builds should be good.

jason-ha · 2026-03-03T00:45:56Z

Do update the PR title and description.

Do borrow liberally from jason-ha@4c04950 description. I am not planning on submitting those separately as we want to have tests in place. You get the credit. :)

CraigMacomber · 2026-03-03T01:13:43Z

If possible, do testing of stuff like this in the import-testing package, which exists for the purpose of testing the exporting of content using fluid types then importing of them.

Realistically I believe what you want to test is d.ts generation and consumption, which can be done with two ts projects in a single package, which is how import-testing is setup. This approach should be able to test what we need, as well as serve as examples of how to do it, while not requiring extra packages.

Note that this package already has tests/example for a lot of schema related APIs.

CraigMacomber · 2026-03-03T01:16:03Z

packages/dds/tree/src/entrypoints/alpha.ts

+ */
+
+/*
+ * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.


I'd prefer we don't commit auto generated files, and instead have them produces as part of the build, unless it is intended for human auditing like API reports. As we already have an API report for these, I don't think we want this as well for the same purpose.

This is exactly the plan. The API report files give us one thing, but they don't tell us what is exactly happening and we can miss things.
InternalTypes is an example of that. Our current "generate entrypoints" actually emits and error for InternalTypes but you don't see it when run as part of the task infrastructure - run it on its own to see. You can also look at the current lib/public.d.ts to see the funkiness.
In the future (see AB#14504), we'll be able to review API surface changes more easily (easier to understand) than with API reports. (Though we'll likely keep one API report to keep track of documented/undocumented and tags.)
In some cases, we may want to temporarily or permanently handcraft parts of the entrypoint files.

This result is not exactly what we want, but it is sufficient.

jason-ha · 2026-03-03T02:19:44Z

If possible, do testing of stuff like this in the import-testing package, which exists for the purpose of testing the exporting of content using fluid types then importing of them.

Realistically I believe what you want to test is d.ts generation and consumption, which can be done with two ts projects in a single package, which is how import-testing is setup. This approach should be able to test what we need, as well as serve as examples of how to do it, while not requiring extra packages.

Note that this package already has tests/example for a lot of schema related APIs.

I think testing can be relocated. I don't know that need (see below) to bother with two ts projects, though I know you can test that way as one form of setup in my personal iterations had observed that.

I do know that these cases need to be isolated. I observed too many things that would avoid recreating the issue. Maybe separate project is the best to help ensure that.

I don't think it is bad to have a clear example of practical use. Multiple ts projects does complicate the build a bit and is a lot less obvious.

I'm okay with this or rolled into import-testing.

jason-ha · 2026-03-03T02:33:06Z

@WillieHabi, to fix the build break probably should apply this diff to fluidBuild.config.cjs:

-		"build:api-reports:current": ["api-extractor:esnext"],
-		"build:api-reports:legacy": ["api-extractor:esnext"],
-		"ci:build:api-reports:current": ["api-extractor:esnext"],
-		"ci:build:api-reports:legacy": ["api-extractor:esnext"],
+		// Depend on "build:esnext" in case there is no "api-extractor:esnext".
+		"build:api-reports:current": ["api-extractor:esnext", "build:esnext"],
+		"build:api-reports:legacy": ["api-extractor:esnext", "build:esnext"],
+		"ci:build:api-reports:current": ["api-extractor:esnext", "build:esnext"],
+		"ci:build:api-reports:legacy": ["api-extractor:esnext", "build:esnext"],

github-actions · 2026-03-03T08:24:21Z

🔗 No broken links found! ✅

Your attention to detail is admirable.

linkcheck output


> fluid-framework-docs-site@0.0.0 ci:check-links /home/runner/work/FluidFramework/FluidFramework/docs
> start-server-and-test "npm run serve -- --no-open" 3000 check-links

1: starting server using command "npm run serve -- --no-open"
and when url "[ 'http://127.0.0.1:3000' ]" is responding with HTTP status code 200
running tests using command "npm run check-links"


> fluid-framework-docs-site@0.0.0 serve
> docusaurus serve --no-open

[SUCCESS] Serving "build" directory at: http://localhost:3000/

> fluid-framework-docs-site@0.0.0 check-links
> linkcheck http://localhost:3000 --skip-file skipped-urls.txt

Crawling...

Stats:
  257792 links
    1822 destination URLs
    2063 URLs ignored
       0 warnings
       0 errors

initial commit

091a146

Copilot AI review requested due to automatic review settings February 23, 2026 22:17

Copilot started reviewing on behalf of WillieHabi February 23, 2026 22:18 View session

moduleResolution: "bundler"

e3786b3

Copilot AI reviewed Feb 23, 2026

View reviewed changes

WillieHabi and others added 10 commits February 23, 2026 16:40

policy-check

121e361

clean package.json for policy check

f99fae7

caret ts dependency

0c9de71

/schema path

9862793

fix linting errors

d0bf922

test: cross package schema workaround attempt

56f9c89

test: cross package simplification

0cbe4a0

relying on tree exports being setup for normal consumption patterns - no special setup to share schema across packages

Merge branch 'main' into api/tree-schema-expressions

d471d3e

WillieHabi requested a review from a team as a code owner March 2, 2026 17:44

WillieHabi added 2 commits March 2, 2026 10:15

Revert "fix(client-tree): import resolution control"

b54c5ad

This reverts commit 292b58b.

Merge remote-tracking branch 'jason-ha/api/tree-schema-expressions' i…

703cb3f

…nto cross-package-schema

WillieHabi force-pushed the cross-package-schema branch from cb3ee9f to 703cb3f Compare March 2, 2026 18:18

WillieHabi requested a review from jason-ha March 2, 2026 18:21

WillieHabi and others added 6 commits March 2, 2026 10:54

disable fluid-build-tasks-tsc policy for tree package

a989191

Tree's generate:entrypoint-sources script produces files that overlap with tsc output, causing policy check failures. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Revert "disable fluid-build-tasks-tsc policy for tree package"

21d447b

This reverts commit a989191.

build(client-tree): fix policy check extracting source generation

5c4eb39

into a bash script that policy checker doesn't understand.

fix biome nested root config

d0458bf

Merge remote-tracking branch 'upstream/main' into cross-package-schema

d780d3a

updated packages to 2.91.0

aa5ffc7

jason-ha reviewed Mar 3, 2026

View reviewed changes

CraigMacomber reviewed Mar 3, 2026

View reviewed changes

WillieHabi added 3 commits March 2, 2026 22:32

scoped entrypoint exclusion to packages/dds/tree/

05ea21d

flub config changes + add "files" to schema provider

9890e31

policy check fix: sorting package.json

35edd9d

		// Need to skip lib check since some .d.ts from provider are invalid.
		"skipLibCheck": true,

Conversation

WillieHabi commented Feb 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jason-ha left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jason-ha commented Mar 3, 2026

Uh oh!

CraigMacomber commented Mar 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jason-ha commented Mar 3, 2026

Uh oh!

jason-ha commented Mar 3, 2026

Uh oh!

github-actions bot commented Mar 3, 2026

linkcheck output

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

WillieHabi commented Feb 23, 2026 •

edited

Loading

CraigMacomber commented Mar 3, 2026 •

edited

Loading